GET /v1/reverse

Vue d'ensemble

Le géocodage inverse convertit des coordonnées géographiques (latitude, longitude) en une adresse lisible. Contrairement à /v1/geocode qui renvoie un tableau de résultats, cet endpoint renvoie un seul résultat, le meilleur correspondant.

Requête

GET https://api.geocodeme.net/v1/reverse

Header requis : X-Api-Key: gm_YOUR_API_KEY

Paramètres

Paramètre	Type	Requis	Défaut	Description
`lat`	float	Oui	aucun	Latitude du lieu (-90 à 90)
`lon`	float	Oui	aucun	Longitude du lieu (-180 à 180)
`zoom`	integer	Non	`18` (bâtiment)	Niveau de détail de l'adresse (3 à 18). Par défaut, précision au niveau du bâtiment ; voir les niveaux de zoom ci-dessous
`addressdetails`	integer	Non	`1`	Inclure le détail structuré de l'adresse dans la réponse (`1` = oui, `0` = non)
`format`	string	Non	`json`	Format de la réponse : `json` ou `geojson`

Niveaux de zoom

Le paramètre zoom contrôle la granularité de l'adresse renvoyée :

Zoom	Granularité
3	Pays
5	État / Région
8	Comté
10	Ville
14	Quartier
16	Rue
18	Bâtiment (défaut)

Par exemple, les coordonnées 48.8566, 2.3522 (centre de Paris) renvoient des résultats différents à chaque niveau de zoom :

zoom=3 (Pays) → "France"
zoom=5 (Région) → "Île-de-France, France"
zoom=10 (Ville) → "Paris, Île-de-France, France"
zoom=14 (Quartier) → "4e Arrondissement, Paris, Île-de-France, 75004, France"
zoom=18 (Bâtiment) → "3, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France"

astuce

Utilisez zoom=18 (défaut) pour des résultats précis au niveau du bâtiment. Utilisez des valeurs de zoom plus faibles pour les limites administratives.

Exemples de code

cURL
Python
JavaScript
PHP

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/reverse?lat=48.8566&lon=2.3522"

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.get(
    "https://api.geocodeme.net/v1/reverse",
    params={"lat": 48.8566, "lon": 2.3522},
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
print(data["result"]["display_name"])

const apiKey = process.env.GEOCODEME_API_KEY;

const response = await fetch(
  "https://api.geocodeme.net/v1/reverse?lat=48.8566&lon=2.3522",
  { headers: { "X-Api-Key": apiKey } }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const data = await response.json();
console.log(data.result.display_name);

<?php
$apiKey = getenv('GEOCODEME_API_KEY');

$url = 'https://api.geocodeme.net/v1/reverse?' . http_build_query([
    'lat' => 48.8566,
    'lon' => 2.3522,
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: $apiKey"]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new \RuntimeException("HTTP $httpCode: $response");
}

$data = json_decode($response, true);
echo $data['result']['display_name'] . "\n";

Réponse

info

Toutes les réponses incluent les headers de limitation de débit (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Monthly-Remaining, etc.).

attention

Contrairement à /v1/geocode qui renvoie "results" (un tableau), cet endpoint renvoie "result" (un objet unique).

Réponse JSON

{
  "result": {
    "lat": 48.8566,
    "lon": 2.3522,
    "name": null,
    "display_name": "3, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France",
    "address": {
      "house_number": "3",
      "road": "Rue de Rivoli",
      "city": "Paris",
      "state": "Île-de-France",
      "postcode": "75004",
      "country": "France",
      "country_code": "fr"
    }
  },
  "attribution": "© OpenStreetMap contributors",
  "meta": {
    "took_ms": 28,
    "cache_hit": true
  }
}

Réponse GeoJSON

Avec format=geojson :

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [2.3522, 48.8566]
  },
  "properties": {
    "name": null,
    "display_name": "3, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France",
    "address": {
      "house_number": "3",
      "road": "Rue de Rivoli",
      "city": "Paris",
      "state": "Île-de-France",
      "postcode": "75004",
      "country": "France",
      "country_code": "fr"
    }
  },
  "attribution": "© OpenStreetMap contributors",
  "meta": {
    "took_ms": 28,
    "cache_hit": true
  }
}

Schéma

Réponse de premier niveau

Champ	Type	Description
`result`	object \| null	Un objet `ReverseResult` unique, ou `null` si aucune adresse n'est trouvée aux coordonnées données
`attribution`	string	Toujours `"© OpenStreetMap contributors"`
`meta`	object	Métadonnées de la requête
`meta.took_ms`	integer	Temps de traitement serveur en millisecondes
`meta.cache_hit`	boolean	Indique si la réponse a été servie depuis le cache

`ReverseResult`

Champ	Type	Description
`lat`	float	Latitude du résultat
`lon`	float	Longitude du résultat
`name`	string \| null	Nom propre du lieu, issu du tag OpenStreetMap `name` (`null` quand l'objet n'a pas de nom). Voir Le champ `name`
`display_name`	string	Adresse complète lisible
`address`	object	Composants structurés de l'adresse, peut être null

Le champ `name`

name est un champ de premier niveau qui porte le tag OpenStreetMap name de l'objet trouvé aux coordonnées données : "Musée du Louvre", "École élémentaire Jules Ferry", "Boulangerie Chez Momo". Ce n'est pas une composante d'adresse et il n'apparaît jamais dans address.

{
  "result": {
    "lat": 48.8606,
    "lon": 2.3376,
    "name": "Musée du Louvre",
    "display_name": "Musée du Louvre, Rue de Rivoli, 1er Arrondissement, Paris, Île-de-France, 75001, France"
  }
}

null quand l'objet n'a pas de tag name : le cas courant quand les coordonnées tombent sur une simple rue ou une adresse numérotée. Le champ est toujours présent, avec la valeur JSON null, jamais une chaîne vide.
Utilisez-le comme titre de ce que vous affichez, avec display_name en ligne d'adresse dessous ; ne découpez jamais display_name sur sa première virgule pour obtenir un titre ; sur 3, Rue de Rivoli, … cela donne 3.

Le même champ, avec le même contrat, est renvoyé par /v1/geocode et /v1/autocomplete. Avec format=geojson, il se trouve dans properties, juste avant display_name.

`Address`

Tous les champs sont optionnels et dépendent du lieu :

Champ	Type	Description
`house_number`	string	Numéro de maison ou de bâtiment
`road`	string	Nom de la rue
`city`	string	Nom de la ville
`town`	string	Nom de la commune (alternative à `city` pour les agglomérations plus petites)
`village`	string	Nom du village (alternative à `city` pour les zones rurales)
`county`	string	Comté ou district
`state`	string	État ou région
`postcode`	string	Code postal
`country`	string	Nom du pays
`country_code`	string	Code pays ISO 3166-1 alpha-2 (par ex. `fr`)

Réponses d'erreur

Les erreurs les plus courantes pour cet endpoint :

Coordonnées manquantes

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'lat' is missing",
    "field": "lat"
  }
}

Plage de coordonnées invalide

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter 'lat' must be between -90 and 90",
    "field": "lat"
  }
}

Pour la référence complète des erreurs, consultez Codes d'erreur.

info

Le TTL du cache pour /v1/reverse est de 24 heures, comme /v1/geocode et /v1/autocomplete. Les réponses pour des coordonnées récemment interrogées sont servies depuis le cache Redis ; meta.cache_hit vous dit lesquelles.

Vue d'ensemble​

Requête​

Paramètres​

Niveaux de zoom​

Exemples de code​

Réponse​

Réponse JSON​

Réponse GeoJSON​

Schéma​

Réponse de premier niveau​

ReverseResult​

Le champ name​

Address​

Réponses d'erreur​

Coordonnées manquantes​

Plage de coordonnées invalide​