đ
API Géolocalisation & Adresses (Geo)
Référentiel complet des Endpoints, RÎles et Payloads
Autocomplétion d'adresses postales
SuggÚre des adresses normalisées en temps réel au fur et à mesure de la frappe avec bascule automatique de fournisseur (Fournisseur tenant -> data.gouv.fr 0⏠-> Mapbox/Google).
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
Content-Type |
application/json (si POST) |
X-GEO-API-KEY |
geo_live_key_acme_logistics_2026_x1 (ou Authorization: Bearer <clé>) |
Structure du Payload
| Champ | Type | Obligatoire ? | Description |
q |
string |
OUI
|
Texte ou début d'adresse recherché (ex: "10 rue de la Paix, Paris") |
limit |
integer |
Optionnel
|
Nombre maximal de suggestions souhaitées (défaut : 5) |
lat |
float |
Optionnel
|
Latitude pour prioriser les résultats autour d'une position géographique |
lon |
float |
Optionnel
|
Longitude pour prioriser les résultats |
Exemple de RequĂȘte JSON
{
"q": "10 rue de la Paix, Paris",
"limit": 5
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"provider": "datagouv",
"query": "10 rue de la Paix, Paris",
"count": 1,
"attempts_count": 1,
"cascade_history": [
{
"attempt": 1,
"provider": "datagouv",
"cost_1k": 0,
"quality": 85,
"success": true,
"latency_ms": 45
}
],
"results": [
{
"label": "10 Rue de la Paix 75002 Paris",
"name": "10 Rue de la Paix",
"postcode": "75002",
"city": "Paris",
"lat": 48.8698,
"lon": 2.3308,
"score": 0.98
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Le paramĂštre de recherche \"q\" est obligatoire.",
"code": 400
}
Géocodage direct (Adresse -> GPS)
Convertit une adresse textuelle complÚte en coordonnées géodésiques précises (latitude, longitude, score de confiance).
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
X-GEO-API-KEY |
geo_live_key_acme_logistics_2026_x1 |
Structure du Payload
| Champ | Type | Obligatoire ? | Description |
address |
string |
OUI
|
Adresse postale à convertir en coordonnées GPS (ex: "Tour Eiffel, Paris") |
Exemple de RequĂȘte JSON
{
"address": "Champ de Mars, 5 Av. Anatole France, 75007 Paris"
}
Réponse SuccÚs (HTTP 200)
{
"found": true,
"provider": "datagouv",
"formatted_address": "5 Avenue Anatole France 75007 Paris",
"city": "Paris",
"postcode": "75007",
"country": "France",
"lat": 48.85837,
"lon": 2.294481,
"confidence": 0.96,
"attempts_count": 1
}
Réponse Erreur Type
{
"found": false,
"error": "Adresse introuvable.",
"code": 404
}
Géocodage inverse (GPS -> Adresse)
Détermine l'adresse postale normalisée correspondant à une coordonnée GPS (latitude, longitude).
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
X-GEO-API-KEY |
geo_live_key_acme_logistics_2026_x1 |
Structure du Payload
| Champ | Type | Obligatoire ? | Description |
lat |
float |
OUI
|
Latitude WGS84 (ex: 48.8584) |
lon |
float |
OUI
|
Longitude WGS84 (ex: 2.2945) |
Exemple de RequĂȘte JSON
{
"lat": 48.85837,
"lon": 2.294481
}
Réponse SuccÚs (HTTP 200)
{
"found": true,
"provider": "datagouv",
"formatted_address": "Avenue Anatole France 75007 Paris",
"city": "Paris",
"postcode": "75007",
"country": "France",
"lat": 48.85837,
"lon": 2.294481,
"distance_meters": 12.4
}
Réponse Erreur Type
{
"found": false,
"error": "Aucune adresse trouvée pour ces coordonnées.",
"code": 404
}
Calcul de distance Ă vol d'oiseau (Haversine)
Calcule instantanément la distance sphérique géodésique, l'azimut (cap en degrés) et l'estimation routiÚre sans coût externe.
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
X-GEO-API-KEY |
geo_live_key_acme_logistics_2026_x1 |
Structure du Payload
| Champ | Type | Obligatoire ? | Description |
origin_lat |
float |
OUI
|
Latitude de départ (ex: 48.8566) |
origin_lon |
float |
OUI
|
Longitude de départ (ex: 2.3522) |
dest_lat |
float |
OUI
|
Latitude d'arrivée (ex: 45.7640) |
dest_lon |
float |
OUI
|
Longitude d'arrivée (ex: 4.8357) |
Exemple de RequĂȘte JSON
{
"origin_lat": 48.8566,
"origin_lon": 2.3522,
"dest_lat": 45.764,
"dest_lon": 4.8357
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"distance_km": 391.54,
"distance_meters": 391540,
"distance_miles": 243.29,
"bearing_degrees": 156.4,
"cardinal_direction": "SSE",
"estimated_road_km": 489.43,
"formula": "Haversine spherical geodesy"
}
Réponse Erreur Type
{
"success": false,
"error": "Les 4 coordonnées GPS sont obligatoires.",
"code": 400
}
Calcul d'itinéraire routier (Routing)
Calcule la distance réelle de conduite, la durée estimée et les étapes de trajet via OSRM, Mapbox ou Google Directions avec failover.
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
X-GEO-API-KEY |
geo_live_key_acme_logistics_2026_x1 |
Structure du Payload
| Champ | Type | Obligatoire ? | Description |
origin_lat |
float |
OUI
|
Latitude de départ |
origin_lon |
float |
OUI
|
Longitude de départ |
dest_lat |
float |
OUI
|
Latitude de destination |
dest_lon |
float |
OUI
|
Longitude de destination |
mode |
string |
Optionnel
|
"driving" (défaut), "walking", "cycling" |
Exemple de RequĂȘte JSON
{
"origin_lat": 44.8378,
"origin_lon": -0.5792,
"dest_lat": 43.6047,
"dest_lon": 1.4442,
"mode": "driving"
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"provider": "nominatim",
"distance_km": 244.5,
"duration_sec": 8820,
"duration_min": 147,
"mode": "driving",
"steps_count": 3,
"attempts_count": 1,
"steps": [
{
"instruction": "Prendre l'autoroute A62 vers Toulouse",
"distance_m": 240000,
"duration_sec": 8400
},
{
"instruction": "Prendre la sortie vers Centre-Ville",
"distance_m": 4500,
"duration_sec": 420
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Coordonnées d'itinéraire manquantes.",
"code": 400
}