📍
API Géolocalisation & Adresses (Geo)
Référentiel complet des Endpoints, RÎles et Payloads
GET / POST https://notif.compareb2b.com/public/geo/autocomplete.php
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ĂȘteValeur / 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

ChampTypeObligatoire ?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
}
GET / POST https://notif.compareb2b.com/public/geo/geocode.php
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ĂȘteValeur / Exemple
X-GEO-API-KEY geo_live_key_acme_logistics_2026_x1

Structure du Payload

ChampTypeObligatoire ?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
}
GET / POST https://notif.compareb2b.com/public/geo/reverse.php
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ĂȘteValeur / Exemple
X-GEO-API-KEY geo_live_key_acme_logistics_2026_x1

Structure du Payload

ChampTypeObligatoire ?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
}
GET / POST https://notif.compareb2b.com/public/geo/distance.php
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ĂȘteValeur / Exemple
X-GEO-API-KEY geo_live_key_acme_logistics_2026_x1

Structure du Payload

ChampTypeObligatoire ?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
}
GET / POST https://notif.compareb2b.com/public/geo/route.php
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ĂȘteValeur / Exemple
X-GEO-API-KEY geo_live_key_acme_logistics_2026_x1

Structure du Payload

ChampTypeObligatoire ?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
}