{
    "module": "Géolocalisation & Adresses SaaS (Geo)",
    "base_url": "https://notif.compareb2b.com/public/geo",
    "endpoints": [
        {
            "id": "autocomplete",
            "method": "GET / POST",
            "path": "/autocomplete.php",
            "title": "Autocomplétion d'adresses postales",
            "summary": "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).",
            "headers": {
                "Content-Type": "application/json (si POST)",
                "X-GEO-API-KEY": "geo_live_key_acme_logistics_2026_x1 (ou Authorization: Bearer <clé>)"
            },
            "payload": {
                "q": {
                    "type": "string",
                    "required": true,
                    "description": "Texte ou début d'adresse recherché (ex: \"10 rue de la Paix, Paris\")"
                },
                "limit": {
                    "type": "integer",
                    "required": false,
                    "description": "Nombre maximal de suggestions souhaitées (défaut : 5)"
                },
                "lat": {
                    "type": "float",
                    "required": false,
                    "description": "Latitude pour prioriser les résultats autour d'une position géographique"
                },
                "lon": {
                    "type": "float",
                    "required": false,
                    "description": "Longitude pour prioriser les résultats"
                }
            },
            "request_example": {
                "q": "10 rue de la Paix, Paris",
                "limit": 5
            },
            "response_success": {
                "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
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Le paramètre de recherche \"q\" est obligatoire.",
                "code": 400
            }
        },
        {
            "id": "geocode",
            "method": "GET / POST",
            "path": "/geocode.php",
            "title": "Géocodage direct (Adresse -> GPS)",
            "summary": "Convertit une adresse textuelle complète en coordonnées géodésiques précises (latitude, longitude, score de confiance).",
            "headers": {
                "X-GEO-API-KEY": "geo_live_key_acme_logistics_2026_x1"
            },
            "payload": {
                "address": {
                    "type": "string",
                    "required": true,
                    "description": "Adresse postale à convertir en coordonnées GPS (ex: \"Tour Eiffel, Paris\")"
                }
            },
            "request_example": {
                "address": "Champ de Mars, 5 Av. Anatole France, 75007 Paris"
            },
            "response_success": {
                "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
            },
            "response_error": {
                "found": false,
                "error": "Adresse introuvable.",
                "code": 404
            }
        },
        {
            "id": "reverse",
            "method": "GET / POST",
            "path": "/reverse.php",
            "title": "Géocodage inverse (GPS -> Adresse)",
            "summary": "Détermine l'adresse postale normalisée correspondant à une coordonnée GPS (latitude, longitude).",
            "headers": {
                "X-GEO-API-KEY": "geo_live_key_acme_logistics_2026_x1"
            },
            "payload": {
                "lat": {
                    "type": "float",
                    "required": true,
                    "description": "Latitude WGS84 (ex: 48.8584)"
                },
                "lon": {
                    "type": "float",
                    "required": true,
                    "description": "Longitude WGS84 (ex: 2.2945)"
                }
            },
            "request_example": {
                "lat": 48.85837,
                "lon": 2.294481
            },
            "response_success": {
                "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
            },
            "response_error": {
                "found": false,
                "error": "Aucune adresse trouvée pour ces coordonnées.",
                "code": 404
            }
        },
        {
            "id": "distance",
            "method": "GET / POST",
            "path": "/distance.php",
            "title": "Calcul de distance à vol d'oiseau (Haversine)",
            "summary": "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.",
            "headers": {
                "X-GEO-API-KEY": "geo_live_key_acme_logistics_2026_x1"
            },
            "payload": {
                "origin_lat": {
                    "type": "float",
                    "required": true,
                    "description": "Latitude de départ (ex: 48.8566)"
                },
                "origin_lon": {
                    "type": "float",
                    "required": true,
                    "description": "Longitude de départ (ex: 2.3522)"
                },
                "dest_lat": {
                    "type": "float",
                    "required": true,
                    "description": "Latitude d'arrivée (ex: 45.7640)"
                },
                "dest_lon": {
                    "type": "float",
                    "required": true,
                    "description": "Longitude d'arrivée (ex: 4.8357)"
                }
            },
            "request_example": {
                "origin_lat": 48.8566,
                "origin_lon": 2.3522,
                "dest_lat": 45.764,
                "dest_lon": 4.8357
            },
            "response_success": {
                "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"
            },
            "response_error": {
                "success": false,
                "error": "Les 4 coordonnées GPS sont obligatoires.",
                "code": 400
            }
        },
        {
            "id": "route",
            "method": "GET / POST",
            "path": "/route.php",
            "title": "Calcul d'itinéraire routier (Routing)",
            "summary": "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.",
            "headers": {
                "X-GEO-API-KEY": "geo_live_key_acme_logistics_2026_x1"
            },
            "payload": {
                "origin_lat": {
                    "type": "float",
                    "required": true,
                    "description": "Latitude de départ"
                },
                "origin_lon": {
                    "type": "float",
                    "required": true,
                    "description": "Longitude de départ"
                },
                "dest_lat": {
                    "type": "float",
                    "required": true,
                    "description": "Latitude de destination"
                },
                "dest_lon": {
                    "type": "float",
                    "required": true,
                    "description": "Longitude de destination"
                },
                "mode": {
                    "type": "string",
                    "required": false,
                    "description": "\"driving\" (défaut), \"walking\", \"cycling\""
                }
            },
            "request_example": {
                "origin_lat": 44.8378,
                "origin_lon": -0.5792,
                "dest_lat": 43.6047,
                "dest_lon": 1.4442,
                "mode": "driving"
            },
            "response_success": {
                "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
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Coordonnées d'itinéraire manquantes.",
                "code": 400
            }
        }
    ]
}