GET /v1/nearest

Vue d'ensemble

Le snap-to-road corrige une coordonnée GPS unique en trouvant le point le plus proche sur le réseau routier. C'est utile pour corriger un relevé GPS qui a dérivé hors route à cause de problèmes de signal.

Contrairement au map matching qui traite une trace GPS entière, cet endpoint traite un seul point.

Ordre des coordonnées

L'endpoint /v1/nearest renvoie la coordonnée recalée sous forme de tableau location: [longitude, latitude] suivant l'ordre standard GeoJSON, et non sous forme de champs lat/lon séparés. Lisez snapped.location[0] pour la longitude et snapped.location[1] pour la latitude.

info

Le paramètre de requête format (pour demander une sortie GeoJSON) n'est pas pris en charge sur cet endpoint. La réponse est toujours en JSON. Utilisez /v1/geocode ou /v1/reverse si vous avez besoin d'une sortie GeoJSON.

Requête

GET https://api.geocodeme.net/v1/nearest

Header requis : X-Api-Key: gm_YOUR_API_KEY

Paramètres

Paramètre	Type	Requis	Défaut	Description
lat	float	Oui	aucun	Latitude du point GPS (-90 à 90)
lon	float	Oui	aucun	Longitude du point GPS (-180 à 180)
profile	string	Non	car	Profil de routage : car, bike, foot, truck ou moto, soumis au plan

Coût : 1 crédit par requête. Gating par plan : car sur tous les plans ; bike/foot dès Startup ; truck/moto dès Growth. Un profil hors plan renvoie 403 PLAN_UPGRADE_REQUIRED, sans jamais consommer de crédit.

Exemples de code

cURL

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/nearest?lat=48.8566&lon=2.3522"

Python

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.get(
    "https://api.geocodeme.net/v1/nearest",
    params={"lat": 48.8566, "lon": 2.3522},
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
snapped = data["snapped"]
if snapped is not None:
    print(f"Snapped to: {snapped['name']}")
    print(f"Distance from input: {snapped['distance_meters']}m")

JavaScript

const apiKey = process.env.GEOCODEME_API_KEY;

const response = await fetch(
  "https://api.geocodeme.net/v1/nearest?lat=48.8566&lon=2.3522",
  { headers: { "X-Api-Key": apiKey } }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const data = await response.json();
if (data.snapped !== null) {
  console.log(`Snapped to: ${data.snapped.name}`);
  console.log(`Distance from input: ${data.snapped.distance_meters}m`);
}

PHP

<?php
$apiKey = getenv('GEOCODEME_API_KEY');

$url = 'https://api.geocodeme.net/v1/nearest?' . http_build_query([
    'lat' => 48.8566,
    'lon' => 2.3522,
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: $apiKey"]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new \RuntimeException("HTTP $httpCode: $response");
}

$data = json_decode($response, true);
if ($data['snapped'] !== null) {
    echo "Snapped to: " . $data['snapped']['name'] . "\n";
    echo "Distance from input: " . $data['snapped']['distance_meters'] . "m\n";
}

Réponse

info

Toutes les réponses incluent les headers de limitation de débit (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Monthly-Remaining, etc.).

{
  "snapped": {
    "location": [2.3519, 48.8567],
    "name": "Rue de Rivoli",
    "distance_meters": 3.2
  },
  "attribution": "Route data (c) OpenStreetMap contributors",
  "meta": {
    "took_ms": 12,
    "cache_hit": false
  }
}

Schéma

Réponse de premier niveau

Champ	Type	Description
snapped	object | null	Le point recalé, ou null si aucune route n'est trouvée à proximité
attribution	string	Toujours "Route data (c) OpenStreetMap contributors"
meta	object	Métadonnées de la requête
meta.took_ms	integer	Temps de traitement serveur en millisecondes
meta.cache_hit	boolean	Indique si la réponse a été servie depuis le cache

snapped

Champ	Type	Description
location	array	Coordonnée recalée sous la forme [longitude, latitude]
name	string	Nom du segment de route le plus proche (peut être vide pour les routes sans nom)
distance_meters	float	Distance en mètres entre le point d'entrée et la position recalée

Réponses d'erreur

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'lat' is missing",
    "field": "lat"
  }
}

astuce

Tous les endpoints sont également soumis aux erreurs INVALID_API_KEY (401) et RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED (429). Consultez Codes d'erreur pour la référence complète.