GET /v1/geocode

Vue d'ensemble

Le géocodage direct convertit une adresse postale, un nom de lieu ou une requête de recherche en coordonnées géographiques. L'API renvoie jusqu'à 50 résultats classés par pertinence, basés sur les données OpenStreetMap.

Requête

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

Header requis : X-Api-Key: gm_YOUR_API_KEY

Paramètres

Paramètre	Type	Requis	Défaut	Description
`q`	string	Oui	aucun	Adresse ou nom de lieu à géocoder
`limit`	integer	Non	`5`	Nombre maximal de résultats à renvoyer (1 à 50). Des valeurs élevées augmentent la taille de la réponse. Il n'y a pas de pagination : tous les résultats sont renvoyés dans une seule réponse.
`countrycodes`	string	Non	aucun	Codes ISO 3166-1 alpha-2 séparés par des virgules, restreignant les résultats à l'intérieur de la zone couverte (par ex. `de`, `es,pt`). Les alias de région (`gp`, `mq`, `gf`, `yt`, `re`, `eu`) choisissent quel index régional est interrogé ; tout autre code s'applique par-dessus comme filtre pays. Les deux se composent, et les mélanger ne fait jamais que restreindre (`eu,de` rend les mêmes résultats que `de` en n'interrogeant qu'une instance au lieu de six), alors qu'un second code de même nature élargit, comme une liste doit le faire (`de,es`, `gp,mq`). `fr` est un code pays, pas un alias : il désigne toute la donnée française, métropole et outre-mer. Les codes hors zone couverte ne renvoient aucun résultat. Voir Alias de région et filtres pays.
`format`	string	Non	`json`	Format de la réponse : `json` ou `geojson`

Alias de région et filtres pays

countrycodes porte deux décisions indépendantes, et elles se combinent :

où chercher. Les alias de région gp (Guadeloupe), mq (Martinique), gf (Guyane), yt (Mayotte), re (La Réunion) et eu (Europe continentale) sélectionnent chacun un index régional. Ils sont résolus par notre routeur et ne sont jamais transmis au moteur de recherche. Sans aucun alias dans la liste, les six instances régionales sont interrogées.
quoi garder. Tout autre code (de, es, pt, fr…) est transmis comme filtre pays, lu comme un OU logique, et appliqué à l'intérieur des instances sélectionnées ci-dessus.

Mélanger les deux natures restreint toujours. Ajoutez un code pays à un alias : vous gardez la même zone, filtrée. Ajoutez un alias à un code pays : vous gardez le même filtre sur une zone plus petite. Ni l'un ni l'autre ne peut élargir la réponse.

Ajouter un code de même nature élargit, exactement comme une liste doit le faire : plusieurs alias interrogent plusieurs régions (gp,mq couvre les deux îles), et plusieurs codes pays se lisent comme un OU logique (de,es rend les résultats allemands et espagnols).

`countrycodes`	Instances interrogées	Filtre pays	Ce que vous obtenez
(absent)	les six	aucun	toute la zone couverte
`de`	les six	`de`	les résultats allemands (seul l'index continental en contient)
`eu`	continentale seule	aucun	tout ce qui est en Europe continentale
`eu,de`	continentale seule	`de`	les mêmes résultats que `de`, depuis une instance au lieu de six
`fr`	les six	`fr`	toute la donnée française : métropole et les cinq DROM
`fr,eu`	continentale seule	`fr`	la métropole seule, un sous-ensemble strict de `fr`
`gp`	Guadeloupe seule	aucun	tout ce qui est en Guadeloupe
`gp,mq`	Guadeloupe + Martinique	aucun	tout ce qui est sur ces deux îles
`gp,de`	Guadeloupe seule	`de`	vide : vous avez demandé des adresses allemandes en Guadeloupe
`eu,zz`	continentale seule	`zz`	vide : `zz` n'est pas un pays couvert

Les codes sont insensibles à la casse, les espaces autour sont ignorés, les doublons sont supprimés et le filtre transmis est trié : eu,de, de,eu et EU, DE sont une seule et même requête.

Un code inconnu ou hors couverture n'est jamais écarté en silence : il reste un filtre et produit une liste vide honnête, jamais une réponse plus large.

Astuce de latence. Si vous savez déjà que le pays est en Europe continentale, préfixer l'alias (eu,de plutôt que de) ramène la diffusion de six instances à une, pour un résultat identique.

/v1/autocomplete sélectionne, mais ne peut pas filtrer

/v1/autocomplete lit les mêmes alias et suit la même règle de sélection : un alias choisit l'index interrogé, et un code ne peut apporter que l'index qu'il désigne ; mélanger les natures n'y élargit pas davantage, tandis qu'un second alias, lui, élargit (gp,mq). gp,fr y restreint à la Guadeloupe exactement comme ici, et fr,eu y interroge l'index continental comme ici.

Ce qui lui manque, c'est la moitié filtre de la composition : son moteur de suggestions n'a aucun filtre pays à transmettre, donc un code qui n'est pas un alias ne sélectionne rien au lieu de restreindre quoi que ce soit. Deux conséquences si vous partagez des valeurs countrycodes entre les endpoints :

eu,de y rend toute l'Europe continentale ; ici, l'Allemagne seule.
une valeur qui ne contient aucun alias n'y rend aucune suggestion : de comme fr,de reviennent vides, là où ici de rend les résultats allemands et fr,de les résultats français ou allemands.

Filtrez les suggestions côté client sur address.country_code.

Exemples de code

cURL
Python
JavaScript
PHP

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/geocode?q=10%20Rue%20de%20Rivoli%2C%20Paris&limit=3"

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.get(
    "https://api.geocodeme.net/v1/geocode",
    params={"q": "10 Rue de Rivoli, Paris", "limit": 3},
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
for result in data["results"]:
    print(f"{result['display_name']} ({result['lat']}, {result['lon']})")

const apiKey = process.env.GEOCODEME_API_KEY;

const response = await fetch(
  "https://api.geocodeme.net/v1/geocode?q=10%20Rue%20de%20Rivoli%2C%20Paris&limit=3",
  { headers: { "X-Api-Key": apiKey } }
);

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

const data = await response.json();
for (const result of data.results) {
  console.log(`${result.display_name} (${result.lat}, ${result.lon})`);
}

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

$url = 'https://api.geocodeme.net/v1/geocode?' . http_build_query([
    'q' => '10 Rue de Rivoli, Paris',
    'limit' => 3,
]);

$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);
foreach ($data['results'] as $result) {
    echo $result['display_name'] . " ({$result['lat']}, {$result['lon']})\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.).

Réponse JSON

{
  "results": [
    {
      "lat": 48.8566,
      "lon": 2.3522,
      "name": null,
      "display_name": "10, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France",
      "type": "house",
      "importance": 0.62,
      "address": {
        "house_number": "10",
        "road": "Rue de Rivoli",
        "city": "Paris",
        "state": "Île-de-France",
        "postcode": "75004",
        "country": "France",
        "country_code": "fr"
      }
    }
  ],
  "attribution": "© OpenStreetMap contributors",
  "meta": {
    "took_ms": 45,
    "cache_hit": false
  }
}

Réponse GeoJSON

Avec format=geojson, la réponse est une FeatureCollection GeoJSON standard :

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

Schéma

Réponse de premier niveau

Champ	Type	Description
`results`	array	Tableau d'objets `GeocodingResult`
`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

`GeocodingResult`

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
`type`	string	Type de lieu OSM (par ex. `house`, `road`, `city`, `building`), peut être null
`importance`	float	Score de pertinence entre 0 et 1, peut être null
`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 : "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.

{
  "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",
  "type": "museum",
  "importance": 0.83
}

null quand l'objet n'a pas de tag name : le cas courant d'une simple rue ou d'une adresse numérotée. Le champ est toujours présent dans la charge utile, avec la valeur JSON null, jamais une chaîne vide.
Différent de type, qui porte la catégorie OSM (museum, school, bakery, house) : les deux sont complémentaires, pas redondants.
Différent de la tête de display_name. Utilisez name comme titre d'un résultat et display_name comme ligne d'adresse en dessous ; ne découpez jamais display_name sur sa première virgule pour obtenir un titre ; sur 10, Rue de Rivoli, … cela donne 10.

Le même champ, avec le même contrat, est renvoyé par /v1/reverse 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 :

Paramètre `q` manquant

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

Clé API invalide

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key missing or invalid"
  }
}

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

Vue d'ensemble​

Requête​

Paramètres​

Alias de région et filtres pays​

Exemples de code​

Réponse​

Réponse JSON​

Réponse GeoJSON​

Schéma​

Réponse de premier niveau​

GeocodingResult​

Le champ name​

Address​

Réponses d'erreur​

Paramètre q manquant​

Clé API invalide​