Démarrage rapide

Il vous faut une clé d'API. Les clés seront délivrées à l'ouverture du service ; d'ici là, les exemples montrent la forme exacte des requêtes et réponses de la spécification OpenAPI. Les valeurs des réponses sont illustratives.

L'URL de base est https://api.addrova.eu (pas encore en ligne). Remplacez-la par http://localhost:8000 pour essayer une instance de développement locale.

1. Géocoder une adresse

Utilisez POST avec un corps JSON : l'adresse n'apparaît ainsi jamais dans une URL.

curl

curl -s https://api.addrova.eu/v1/geocode \
  -H "X-API-Key: $ADDROVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "4 place d'\''Armes, Belfort", "country": "FR", "limit": 3}'

Python

import os
import requests

resp = requests.post(
    "https://api.addrova.eu/v1/geocode",
    headers={"X-API-Key": os.environ["ADDROVA_API_KEY"]},
    json={"q": "4 place d'Armes, Belfort", "country": "FR", "limit": 3},
    timeout=10,
)
resp.raise_for_status()
for r in resp.json()["results"]:
    print(r["label"], r["location"], r["confidence_level"])

JavaScript (Node 18+ ou navigateur)

const resp = await fetch("https://api.addrova.eu/v1/geocode", {
  method: "POST",
  headers: { "X-API-Key": process.env.ADDROVA_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ q: "4 place d'Armes, Belfort", country: "FR", limit: 3 }),
});
if (!resp.ok) throw new Error((await resp.json()).code);
const { results, attribution } = await resp.json();

Forme de la réponse

{
  "results": [
    {
      "id": "90010_xxxx_00004",
      "label": "4 Place d'Armes 90000 Belfort",
      "components": { "housenumber": "4", "street": "Place d'Armes", "postcode": "90000", "city": "Belfort", "country_code": "FR" },
      "location": { "lat": 47.64, "lon": 6.86 },
      "precision": "rooftop",
      "confidence": 0.97,
      "confidence_level": "high",
      "confidence_calibrated": true,
      "country": "FR",
      "sources": ["ban"]
    }
  ],
  "attribution": [
    { "source": "ban", "text": "© BAN — Base Adresse Nationale, Licence Ouverte 2.0", "license": "etalab-2.0" }
  ]
}

precision vaut rooftop, street, centroid (un lieu nommé plus petit qu’une commune, comme un lieu-dit) ou locality. confidence_level vaut high (calibrée et au moins égale au seuil du pays, 0,985 par défaut pour la France), medium (0,5 ou plus) ou low. confidence_calibrated indique si la confiance est calibrée pour ce pays : high n'existe que dans ce cas, et ailleurs le meilleur niveau est medium ; n'affichez pas de pourcentage quand il vaut false. Vous pouvez stocker les résultats, à condition de conserver l'attribution.

2. Géocodage inverse

curl -s "https://api.addrova.eu/v1/reverse?lat=47.64&lon=6.86&limit=1" \
  -H "X-API-Key: $ADDROVA_API_KEY"

Le géocodage inverse prend les coordonnées dans l'URL. Chaque résultat porte une distance_m depuis votre point.

3. Réparer une adresse approximative

curl -s https://api.addrova.eu/v1/repair \
  -H "X-API-Key: $ADDROVA_API_KEY" -H "Content-Type: application/json" \
  -d '{"address": "4 pl darmes 90000 belfor", "country": "FR"}'

La réponse contient un status (unchanged, repaired, unrepairable ou pending), le result corrigé, une confidence et la liste des changes avec leur motif (abbreviation, typo, missing…). La réparation n'est facturée qu'en cas de succès. Le repli asynchrone par LLM n'est pas activé : aucune adresse n'est envoyée à un service externe.

4. Géocoder un fichier

curl -s https://api.addrova.eu/v1/batch \
  -H "X-API-Key: $ADDROVA_API_KEY" \
  -F file=@adresses.csv -F address_column=adresse -F country=FR

L'appel renvoie 202 avec un id de job et un en-tête Location. Interrogez GET /v1/batch/{id} jusqu'à ce que status vaille succeeded, puis téléchargez GET /v1/batch/{id}/result. Par défaut : 50 Mo et 100 000 lignes. Le fichier d'entrée est supprimé dès la fin du traitement ; le résultat l'est au bout d'une heure par défaut, ou immédiatement avec DELETE /v1/batch/{id}.

5. Gérer les erreurs

Les erreurs sont en application/problem+json avec un code : invalid_request, unauthorized, quota_exceeded et rate_limited (tous deux 429, avec un en-tête Retry-After), engine_unavailable (503), etc. La valeur fautive n'est jamais renvoyée. Citez l'en-tête de réponse X-Request-Id en contactant le support : nous ne pouvons pas retrouver votre requête, puisque nous ne la conservons pas.

6. Compatibilité directe

Vous utilisez déjà Google ou Nominatim ? Voir migrer depuis Google et migrer depuis Nominatim.