Géocodage OSM · GeoService

Principe

Les fonctions disponibles

Toutes les fonctions s'appellent en GET, avec des paramètres d'URL. Un POST reçoit une erreur 405.

Fonction	Usage
`search`	Recherche libre (`q`) ou structurée (rue, ville, code postal…)
`reverse`	Adresse ou lieu le plus proche de coordonnées
`lookup`	Adresse d'objets OpenStreetMap connus par leur identifiant
`details`	Fiche complète d'un lieu : noms, étiquettes, hiérarchie administrative
`status`	État du moteur et date des données

Précisez toujours format. Sans lui, search répond en JSON mais reverse répond en XML, et les erreurs arrivent en XML. Avec format=jsonv2, tout est en JSON.

Paramètres

Paramètres communs

Paramètre	Description
`format`	`jsonv2` (recommandé), `json`, `geojson`, `geocodejson` ou `xml`. Voir formats.
`accept-language`	Langue des noms, par exemple `fr`. Sans lui, les noms sont dans la langue locale (néerlandais ou français à Bruxelles, allemand en Allemagne).
`addressdetails`	`1` pour détailler l'adresse (numéro, rue, quartier, ville, code postal, pays) dans `address`. Actif par défaut en `reverse`.
`limit`	Nombre maximal de résultats de `search`.
`countrycodes`	Restreint à des pays : `fr`, `be`, `de`, ou une liste `fr,be`.
`viewbox`, `bounded`	Emprise `lon1,lat1,lon2,lat2` qui favorise les résultats situés à l'intérieur ; avec `bounded=1`, les exclut au dehors.
`extratags`, `namedetails`	`1` pour recevoir les étiquettes OSM supplémentaires (site web, horaires…) et les noms dans toutes les langues.

Endpoint

Rechercher une adresse ou un lieu

GET/v2/geocoding/osm/search

La recherche libre prend la saisie complète dans q : adresse, nom de lieu ou combinaison des deux.

curl -G "https://geoservice.example.com/v2/geocoding/osm/search" \
  -H "X-API-Key: $GEOSERVICE_KEY" \
  --data-urlencode "q=Avenue d'Italie 75013 Paris France" \
  -d format=jsonv2 -d accept-language=fr -d addressdetails=1 -d limit=1

const url = new URL("https://geoservice.example.com/v2/geocoding/osm/search");
url.search = new URLSearchParams({
  q: "Avenue d'Italie 75013 Paris France",
  format: "jsonv2",
  "accept-language": "fr",
  addressdetails: 1,
  limit: 1,
});
const [place] = await (await fetch(url, { headers: { "X-API-Key": GEOSERVICE_KEY } })).json();
console.log(place.display_name, Number(place.lat), Number(place.lon));

import httpx

r = httpx.get(
    "https://geoservice.example.com/v2/geocoding/osm/search",
    headers={"X-API-Key": GEOSERVICE_KEY},
    params={
        "q": "Avenue d'Italie 75013 Paris France",
        "format": "jsonv2",
        "accept-language": "fr",
        "addressdetails": 1,
        "limit": 1,
    },
)
place = r.json()[0]
print(place["display_name"], float(place["lat"]), float(place["lon"]))

200 OK

[{
  "place_id": 256245,
  "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
  "osm_type": "way",
  "osm_id": 685719842,
  "lat": "48.8254891",
  "lon": "2.3574814",
  "category": "highway",
  "type": "primary",
  "place_rank": 26,
  "importance": 0.0533433333333333,
  "addresstype": "road",
  "name": "Avenue d'Italie",
  "display_name": "Avenue d'Italie, Maison-Blanche, Paris 13e Arrondissement, Paris, 75013, France",
  "address": {
    "road": "Avenue d'Italie",
    "quarter": "Maison-Blanche",
    "suburb": "Paris 13e Arrondissement",
    "city": "Paris",
    "postcode": "75013",
    "country": "France",
    "country_code": "fr"
  },
  "boundingbox": ["48.8252637", "48.8257150", "2.3574144", "2.3575502"]
}]

lat, lon: Coordonnées, sous forme de chaînes : convertissez-les en nombres.
category, type: Nature de l'objet OSM : highway/primary pour une avenue, railway/station pour une gare…
place_rank: Niveau de précision : 30 pour un bâtiment ou un numéro, 26 pour une rue, 16 pour une ville.
boundingbox: Emprise [lat min, lat max, lon min, lon max], pratique pour cadrer une carte.

Lieux et points d'intérêt

La recherche libre trouve aussi les lieux par leur nom. Combinez-la avec viewbox et bounded=1 pour chercher dans une zone précise :

Requête : cathédrales dans le centre de Paris

curl -G "https://geoservice.example.com/v2/geocoding/osm/search" \
  -H "X-API-Key: $GEOSERVICE_KEY" \
  --data-urlencode "q=cathédrale" \
  -d viewbox=2.33,48.86,2.36,48.84 -d bounded=1 \
  -d format=jsonv2 -d limit=2

200 OK · champs principaux

[
  {"name": "Cathédrale Notre-Dame de Paris", "category": "amenity", "type": "place_of_worship",
   "lat": "48.8529371", "lon": "2.3500501", "…": "…"},
  {"name": "Cathédrale Ukrainienne Saint-Vladimir-le-Grand", "category": "amenity", "type": "place_of_worship",
   "lat": "48.8547258", "lon": "2.3310118", "…": "…"}
]

Recherche structurée

Quand l'adresse est déjà découpée en champs, passez-les séparément : la recherche est plus fiable qu'une chaîne recomposée.

Paramètre	Contenu
`street`	Numéro et nom de rue : `87 avenue d'Italie`
`city`	Ville
`postalcode`	Code postal
`county`, `state`	Département, région (ou Land)
`country`	Pays
`amenity`	Nom ou type de point d'intérêt

Requête

curl -G "https://geoservice.example.com/v2/geocoding/osm/search" \
  -H "X-API-Key: $GEOSERVICE_KEY" \
  --data-urlencode "street=87 avenue d'Italie" \
  -d city=Paris -d countrycodes=fr -d format=jsonv2 -d limit=1

Libre ou structurée, pas les deux. Mélanger q et les champs structurés renvoie une erreur 400 : Structured query parameters (…) cannot be used together with 'q' parameter.

Endpoint

Trouver l'adresse d'un point

GET/v2/geocoding/osm/reverse

Renvoie l'objet le plus proche des coordonnées lat et lon. Le paramètre zoom (de 3, pays, à 18, bâtiment) règle le niveau de détail recherché.

Requête

curl "https://geoservice.example.com/v2/geocoding/osm/reverse?lat=48.8240267&lon=2.3584248&format=jsonv2&accept-language=fr" \
  -H "X-API-Key: $GEOSERVICE_KEY"

200 OK

{
  "place_id": 255476,
  "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
  "osm_type": "node",
  "osm_id": 2540682965,
  "lat": "48.8240267",
  "lon": "2.3584248",
  "category": "place",
  "type": "house",
  "place_rank": 30,
  "addresstype": "place",
  "name": "",
  "display_name": "87, Avenue d'Italie, Maison-Blanche, Paris 13e Arrondissement, Paris, 75013, France",
  "address": {
    "house_number": "87",
    "road": "Avenue d'Italie",
    "quarter": "Maison-Blanche",
    "suburb": "Paris 13e Arrondissement",
    "city": "Paris",
    "postcode": "75013",
    "country": "France",
    "country_code": "fr"
  },
  "boundingbox": ["48.8239767", "48.8240767", "2.3583748", "2.3584748"]
}

Endpoint

Retrouver des objets par identifiant

GET/v2/geocoding/osm/lookup

Renvoie l'adresse d'objets OpenStreetMap dont vous connaissez l'identifiant, par exemple mémorisé lors d'une recherche précédente. osm_ids est une liste séparée par des virgules ; chaque identifiant est préfixé par son type : N (nœud), W (voie) ou R (relation).

Requête : l'avenue d'Italie et le 87 de l'avenue

curl "https://geoservice.example.com/v2/geocoding/osm/lookup?osm_ids=W685719842,N2540682965&format=jsonv2&accept-language=fr" \
  -H "X-API-Key: $GEOSERVICE_KEY"

La réponse est une liste au même format que search.

Endpoint

Consulter la fiche d'un lieu

GET/v2/geocoding/osm/details

Renvoie tout ce que le moteur sait d'un objet : noms dans toutes les langues, étiquettes OSM, code postal calculé, rattachements administratifs. Désignez l'objet par osmtype (N, W, R) et osmid, ou par place_id.

Requête

curl "https://geoservice.example.com/v2/geocoding/osm/details?osmtype=W&osmid=685719842&format=json" \
  -H "X-API-Key: $GEOSERVICE_KEY"

200 OK · extrait

{
  "place_id": 256245,
  "osm_type": "W",
  "osm_id": 685719842,
  "category": "highway",
  "type": "primary",
  "localname": "Avenue d'Italie",
  "names": {"name": "Avenue d'Italie", "name:fr": "Avenue d'Italie", "name:zh": "意大利大道", "old_ref": "N 7"},
  "calculated_postcode": "75013",
  "country_code": "fr",
  …
}

Pour l'affichage, préférez lookup. details sert surtout à comprendre pourquoi un lieu est trouvé (ou non) ; son format peut évoluer d'une version du moteur à l'autre.

Formats

Choisir un format de réponse

`format`	Forme	Pour
`jsonv2`	Liste d'objets, coordonnées en chaînes	Usage général, recommandé
`json`	Comme `jsonv2`, avec `class` au lieu de `category`	Compatibilité avec d'anciens clients
`geojson`	FeatureCollection, coordonnées `[lon, lat]`	Affichage direct sur une carte
`geocodejson`	GeoJSON avec un bloc `geocoding` normalisé (`label`, `name`…)	Outils qui suivent la spécification GeocodeJSON

format=geocodejson · 200 OK

{
  "type": "FeatureCollection",
  "geocoding": {"version": "0.1.0", "licence": "ODbL", "query": "notre dame paris", "…": "…"},
  "features": [{
    "type": "Feature",
    "properties": {
      "geocoding": {
        "osm_type": "way", "osm_id": 201611261,
        "osm_key": "amenity", "osm_value": "place_of_worship",
        "name": "Cathédrale Notre-Dame de Paris",
        "label": "Cathédrale Notre-Dame de Paris, 6, Parvis Notre-Dame - Place Jean-Paul II, Quartier Les Îles, Paris 4e Arrondissement, Paris, 75004, France"
      }
    },
    "geometry": {"type": "Point", "coordinates": [2.3500501, 48.8529371]}
  }]
}

Endpoint

Statut du moteur

GET/v2/geocoding/osm/status?format=json

200 OK

{"status": 0, "message": "OK", "data_updated": "2026-09-16T19:20:55+00:00", "software_version": "5.3.2", "database_version": "5.3.2-0"}

data_updated donne la fraîcheur des données OpenStreetMap en service.

Erreurs

Erreurs du moteur

Une requête invalide reçoit une erreur 400 de Nominatim, au format demandé par format :

400 Bad Request · format=jsonv2

{"error": {"code": 400, "message": "Parameter 'lat' must be a number."}}

Sans format, la même erreur arrive en XML (<error><code>400</code>…). Une recherche sans résultat n'est pas une erreur : la réponse est 200 avec une liste vide [].

Licence

Citer OpenStreetMap

Les données OpenStreetMap sont sous licence ODbL. Toute carte ou application qui affiche des résultats du géocodage OSM ou des itinéraires doit mentionner la source, par exemple :

Mention à afficher

© les contributeurs d'OpenStreetMap