Géocodage BAN · GeoService

Principe

Les fonctions disponibles

Fonction	Méthode	Usage
`search`	GET	Recherche d'adresse, de rue, de lieu-dit ou de commune
`reverse`	GET	Adresse la plus proche de coordonnées
`search/csv`	POST	Géocodage d'un fichier CSV d'adresses
`reverse/csv`	POST	Géocodage inverse d'un fichier CSV de coordonnées

Le chemin peut se terminer ou non par une barre oblique : /v2/geocoding/ban/search et /v2/geocoding/ban/search/ sont équivalents. Les réponses sont en GeoJSON (coordonnées [lon, lat]) ou en CSV pour les fichiers.

Endpoint

Rechercher une adresse

GET/v2/geocoding/ban/search

Paramètre	Description
`q`requis	Texte recherché : `87 avenue d'Italie, 75013`. La tolérance aux fautes et aux abréviations est large.
`limit`	Nombre maximal de résultats (5 par défaut).
`type`	Restreint à un type de résultat : `housenumber`, `street`, `locality` ou `municipality` (voir types).
`postcode`	Filtre sur le code postal : `75013`.
`citycode`	Filtre sur le code INSEE de la commune : `75113`.
`lat`, `lon`	Favorise les résultats proches de ce point, sans exclure les autres. Utile pour la saisie semi-automatique autour de la position de l'utilisateur.
`autocomplete`	`1` (par défaut) complète le dernier mot en cours de saisie ; `0` pour des adresses déjà complètes.

curl -G "https://geoservice.example.com/v2/geocoding/ban/search" \
  -H "X-API-Key: $GEOSERVICE_KEY" \
  --data-urlencode "q=87 avenue d'italie, 75013" \
  -d limit=1

const url = new URL("https://geoservice.example.com/v2/geocoding/ban/search");
url.search = new URLSearchParams({ q: "87 avenue d'italie, 75013", limit: 1 });

const res = await fetch(url, { headers: { "X-API-Key": GEOSERVICE_KEY } });
const { features } = await res.json();
const [lon, lat] = features[0].geometry.coordinates;  // GeoJSON : longitude d'abord

import httpx

r = httpx.get(
    "https://geoservice.example.com/v2/geocoding/ban/search",
    headers={"X-API-Key": GEOSERVICE_KEY},
    params={"q": "87 avenue d'italie, 75013", "limit": 1},
)
feature = r.json()["features"][0]
lon, lat = feature["geometry"]["coordinates"]  # GeoJSON : longitude d'abord

200 OK

{
  "type": "FeatureCollection",
  "version": "draft",
  "features": [{
    "type": "Feature",
    "geometry": {"type": "Point", "coordinates": [2.358434, 48.824031]},
    "properties": {
      "label": "87 Avenue d'Italie 75013 Paris",
      "score": 0.89274,
      "housenumber": "87",
      "id": "75113_4754_00087",
      "banId": "aee01bd3-241d-4939-9981-2432d129343f",
      "name": "87 Avenue d'Italie",
      "postcode": "75013",
      "citycode": "75113",
      "x": 652897,
      "y": 6858410.19,
      "city": "Paris",
      "district": "Paris 13e Arrondissement",
      "context": "75, Paris, Île-de-France",
      "type": "housenumber",
      "importance": 0.82014,
      "street": "Avenue d'Italie"
    }
  }],
  "attribution": "BAN",
  "licence": "ETALAB-2.0",
  "query": "87 avenue d'italie, 75013",
  "limit": 1
}

Propriétés d'un résultat

Propriété	Contenu
`label`	Adresse complète, prête à afficher.
`score`	Pertinence, de 0 à 1. Voir interpréter le score.
`type`	`housenumber`, `street`, `locality` ou `municipality`.
`housenumber`, `street`, `name`	Numéro, voie, et libellé sans la commune.
`postcode`, `city`, `district`	Code postal, commune, arrondissement municipal le cas échéant.
`citycode`	Code INSEE de la commune (pour Paris, Lyon et Marseille : celui de l'arrondissement).
`context`	Département et région : `75, Paris, Île-de-France`.
`id`, `banId`	Identifiants de l'adresse dans la BAN.
`x`, `y`	Coordonnées en Lambert 93 (EPSG:2154), en mètres.

Une recherche sans résultat renvoie 200 avec une liste features vide.

Référence

Types de résultat

`type`	Désigne	Exemple de `label`
`housenumber`	Un numéro dans une voie	87 Avenue d'Italie 75013 Paris
`street`	Une voie, sans numéro	Avenue d'Italie 75013 Paris
`locality`	Un lieu-dit	—
`municipality`	Une commune, avec sa `population`	Paris

Qualité

Interpréter le score

Le score mesure la ressemblance entre la saisie et le résultat. Il n'y a pas de seuil universel : il dépend de la qualité de vos adresses. Une démarche éprouvée :

vérifier que le type correspond à la précision attendue : un street quand on cherchait un numéro signale un numéro inconnu de la BAN ;
fixer un seuil de confiance à partir d'un échantillon de vos propres adresses, contrôlées à la main ;
envoyer en vérification manuelle les résultats sous ce seuil.

Sur l'exemple ci-dessus, la saisie 87 avenue d'italie, 75013 obtient 0,89 ; en géocodage inverse sur le point exact, le score approche 1.

Endpoint

Trouver l'adresse d'un point

GET/v2/geocoding/ban/reverse

Renvoie les adresses les plus proches de lat et lon. Acceptent aussi limit et type : avec type=street, vous obtenez la voie la plus proche plutôt que le numéro.

Requête

curl "https://geoservice.example.com/v2/geocoding/ban/reverse?lat=48.8240267&lon=2.3584248&limit=1" \
  -H "X-API-Key: $GEOSERVICE_KEY"

200 OK · extrait

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {"type": "Point", "coordinates": [2.358434, 48.824031]},
    "properties": {
      "label": "87 Avenue d'Italie 75013 Paris",
      "score": 0.9999999997274487,
      "type": "housenumber",
      "citycode": "75113",
      "distance": 0,
      …
    }
  }],
  "attribution": "BAN",
  "licence": "ETALAB-2.0",
  "limit": 1
}

Le géocodage inverse ajoute distance : l'écart, en mètres, entre le point demandé et l'adresse trouvée.

Traitement par lot

Géocoder un fichier CSV

POST/v2/geocoding/ban/search/csvmultipart/form-data

Envoyez un fichier CSV d'adresses : vous recevez le même fichier, enrichi de colonnes de résultat. C'est bien plus rapide que des milliers d'appels à search.

Champ du formulaire	Description
`data`requis	Le fichier CSV, encodé en UTF-8, avec une ligne d'en-tête. Le séparateur (virgule, point-virgule…) est détecté automatiquement.
`columns`	Colonne à utiliser pour la recherche. À répéter pour combiner plusieurs colonnes : numéro, voie, commune… Par défaut, toutes les colonnes sont concaténées.
`postcode`	Nom de la colonne contenant le code postal, utilisé comme filtre.
`citycode`	Nom de la colonne contenant le code INSEE, utilisé comme filtre.

adresses.csv

numero;voie;cp;ville
87;avenue d italie;75013;Paris
10;rue de rivoli;75004;Paris

curl "https://geoservice.example.com/v2/geocoding/ban/search/csv" \
  -H "X-API-Key: $GEOSERVICE_KEY" \
  -F data=@adresses.csv \
  -F columns=numero -F columns=voie -F columns=ville \
  -F postcode=cp \
  -o adresses-geocodees.csv

import httpx

with open("adresses.csv", "rb") as f:
    r = httpx.post(
        "https://geoservice.example.com/v2/geocoding/ban/search/csv",
        headers={"X-API-Key": GEOSERVICE_KEY},
        files={"data": ("adresses.csv", f, "text/csv")},
        data={"columns": ["numero", "voie", "ville"], "postcode": "cp"},
        timeout=60,
    )
r.raise_for_status()
open("adresses-geocodees.csv", "wb").write(r.content)

200 OK · adresses-geocodees.csv

numero;voie;cp;ville;latitude;longitude;result_label;result_score;result_type;result_id;result_housenumber;result_name;result_street;result_postcode;result_city;result_context;result_citycode;result_oldcitycode;result_oldcity;result_district
87;avenue d italie;75013;Paris;48.824031;2.358434;87 Avenue d'Italie 75013 Paris;0.98;housenumber;75113_4754_00087;87;Avenue d'Italie;;75013;Paris;75, Paris, Île-de-France;75113;;;Paris 13e Arrondissement
10;rue de rivoli;75004;Paris;48.8555;2.36041;10 Rue de Rivoli 75004 Paris;0.97;housenumber;75104_8249_00010;10;Rue de Rivoli;;75004;Paris;75, Paris, Île-de-France;75104;;;Paris 4e Arrondissement

Le fichier renvoyé garde vos colonnes et votre séparateur, suivis de latitude, longitude et des colonnes result_*, qui reprennent les propriétés d'un résultat. Il commence par une marque d'ordre des octets (BOM) UTF-8, pour qu'Excel l'ouvre avec les bons accents. Une ligne non trouvée a des colonnes de résultat vides.

Taille des fichiers

Découpez les gros fichiers. La taille d'un fichier et son temps de traitement sont limités. Un fichier trop gros est refusé avec 413 (payload_too_large) ; un envoi trop lent est interrompu avec 408 (request_timeout).

Pour un volume important, envoyez plusieurs fichiers de quelques milliers de lignes, l'un après l'autre plutôt qu'en parallèle.

Traitement par lot

Géocodage inverse d'un fichier CSV

POST/v2/geocoding/ban/reverse/csvmultipart/form-data

Même principe, à partir d'un fichier de coordonnées. Les colonnes lat et lon (ou latitude et longitude) sont reconnues automatiquement.

Requête

curl "https://geoservice.example.com/v2/geocoding/ban/reverse/csv" \
  -H "X-API-Key: $GEOSERVICE_KEY" \
  -F data=@points.csv \
  -o points-adresses.csv

200 OK · points-adresses.csv

id,latitude,longitude,result_latitude,result_longitude,result_label,result_distance,result_type,result_id,result_housenumber,result_name,result_street,result_postcode,result_city,result_context,result_citycode,result_oldcitycode,result_oldcity,result_district
1,48.8240267,2.3584248,48.824031,2.358434,87 Avenue d'Italie 75013 Paris,0,housenumber,75113_4754_00087,87,Avenue d'Italie,,75013,Paris,"75, Paris, Île-de-France",75113,,,Paris 13e Arrondissement

result_distance est en mètres. Les mêmes limites de taille s'appliquent.

Licence

Citer la Base Adresse Nationale

La BAN est publiée sous Licence Ouverte 2.0 (Etalab) : réutilisation libre, à condition de mentionner la source, par exemple :

Mention à afficher

Base Adresse Nationale (BAN), Licence Ouverte 2.0