Démarrage rapide

Prérequis

Une clé API (obtenez-en une ici)
Un outil pour émettre des requêtes HTTP (curl, ou le runtime de votre langage)
Python : Python 3.6+ (les exemples utilisent des f-strings et des annotations de type de la bibliothèque requests compatibles 3.6+)
JavaScript : Node.js 18+ (les exemples utilisent le await de premier niveau et les modules ES)
PHP : PHP 7.4+ avec l'extension curl activée (les exemples utilisent curl_init()). La plupart des distributions l'incluent ; sinon, installez php-curl via votre gestionnaire de paquets.

Effectuez votre première requête

Remplacez gm_YOUR_API_KEY ci-dessous par la véritable clé API copiée depuis votre tableau de bord.

Pour cURL, passez-la directement dans le header. Pour Python, JavaScript et PHP, définissez d'abord la variable d'environnement GEOCODEME_API_KEY :

# macOS / Linux
export GEOCODEME_API_KEY="gm_YOUR_API_KEY"

# Windows PowerShell
$env:GEOCODEME_API_KEY = "gm_YOUR_API_KEY"

:: Windows Command Prompt
set GEOCODEME_API_KEY=gm_YOUR_API_KEY

cURL
Python
JavaScript
PHP

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

Pour vérifier également le code de statut HTTP, utilisez -f (échoue en cas d'erreur HTTP) :

curl -sf -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/geocode?q=Paris%2C%20France&limit=1" || echo "Error: request failed" >&2

Installez d'abord la bibliothèque requests :

pip install requests

Puis exécutez :

import os
import sys
import requests

api_key = os.environ.get("GEOCODEME_API_KEY")
if not api_key:
    sys.exit("Set the GEOCODEME_API_KEY environment variable")

base_url = "https://api.geocodeme.net/v1"


def check_api_error(response: requests.Response) -> None:
    """Check for API errors and exit with a clear message."""
    if not response.ok:
        try:
            error = response.json()
            sys.exit(f"{error['error']['code']}: {error['error']['message']}")
        except (ValueError, KeyError):
            sys.exit(f"HTTP {response.status_code}: {response.text}")


response = requests.get(
    f"{base_url}/geocode",
    params={"q": "Paris, France", "limit": 1},
    headers={"X-Api-Key": api_key},
)
check_api_error(response)

data = response.json()
if not data["results"]:
    print("No results found for the given query")
    sys.exit(1)
print(data["results"][0]["display_name"])
# Affiche l'attribution exigée par la licence OSM (ODbL)
print(data["attribution"])

// Node.js uniquement — pas pour les navigateurs. Nécessite Node.js 18+ avec le await de premier niveau (extension .mjs, ou "type": "module" dans package.json).
const apiKey = process.env.GEOCODEME_API_KEY;
if (!apiKey) {
  console.error("Set the GEOCODEME_API_KEY environment variable");
  process.exit(1);
}

const baseUrl = "https://api.geocodeme.net/v1";

async function handleError(response) {
  const text = await response.text();
  let parsed;
  try {
    parsed = JSON.parse(text);
  } catch {
    console.error(`HTTP ${response.status}: ${text}`);
    process.exit(1);
  }
  const code = parsed.error?.code ?? response.status;
  const message = parsed.error?.message ?? text;
  console.error(`${code}: ${message}`);
  process.exit(1);
}

const response = await fetch(
  `${baseUrl}/geocode?q=Paris%2C%20France&limit=1`,
  { headers: { "X-Api-Key": apiKey } }
);

if (!response.ok) await handleError(response);

const data = await response.json();
if (data.results.length === 0) {
  console.error("No results found for the given query");
  process.exit(1);
}
console.log(data.results[0].display_name);
// Affiche l'attribution exigée par la licence OSM (ODbL)
console.log(data.attribution);

Utilise le helper geocodeme_get() de la page d'exemples PHP :

<?php
// Collez le helper geocodeme_get() de la page d'exemples PHP, puis :

$data = geocodeme_get('/geocode', ['q' => 'Paris, France', 'limit' => 1]);
if (empty($data->results)) {
    throw new RuntimeException('No results found for the given query');
}
echo $data->results[0]->display_name . PHP_EOL;
// Affiche l'attribution exigée par la licence OSM (ODbL)
echo $data->attribution . PHP_EOL;

Paramètres de requête

Paramètre	Type	Requis	Description
`q`	string	Oui	Adresse ou nom de lieu à rechercher (encodé en URL)
`limit`	integer	Non	Nombre maximum de résultats à retourner (défaut : 10, max : 50)

Pour la liste complète des paramètres, voir la Référence API.

Réponse attendue

Attribution OSM requise

Le champ attribution présent dans chaque réponse doit être affiché dans votre application lorsque vous utilisez des données geocodeme.net, comme l'exige la licence OpenStreetMap (ODbL). Incluez-le dans le footer de votre interface ou sur votre page « À propos », par exemple :

<footer>Geocoding by geocodeme.net — © OpenStreetMap contributors</footer>

{
  "results": [
    {
      "name": "Paris",
      "display_name": "Paris, Île-de-France, France",
      "lat": 48.8566101,
      "lon": 2.3514992,
      "type": "city",
      "importance": 0.9288,
      "address": {
        "city": "Paris",
        "state": "Île-de-France",
        "country": "France",
        "country_code": "fr"
      }
    }
  ],
  "attribution": "© OpenStreetMap contributors",
  "meta": {
    "took_ms": 12,
    "cache_hit": false
  }
}

Champ	Description
`results`	Tableau d'objets de localisation correspondant à la requête
`results[].name`	Nom propre du lieu (tag OSM `name`) : `null` pour un objet sans nom, par exemple une simple rue. Affichez-le en titre, `display_name` en dessous. Voir Le champ `name`
`results[].display_name`	Libellé de lieu lisible par un humain (toujours présent)
`results[].lat`, `lon`	Coordonnées sous forme de nombres (toujours présentes)
`results[].address`	Objet d'adresse structurée (optionnel, peut être absent pour certains résultats). Les champs comme `house_number`, `road`, `suburb`, `city`, `state`, `country` et `country_code` sont optionnels et dépendent du lieu.
`results[].type`, `importance`	Type de lieu (ex. `city`, `house`) et score de pertinence (0 à 1), optionnels
`attribution`	Chaîne d'attribution OSM obligatoire : doit être affichée dans toute application destinée au public
`meta.took_ms`	Temps de traitement serveur en millisecondes
`meta.cache_hit`	Indique si la réponse a été servie depuis le cache Redis

attention

Les champs address, type et importance sont optionnels et peuvent être absents selon le résultat. Vérifiez toujours leur présence avant d'y accéder dans votre code.

Géocodage inverse

Convertissez des coordonnées en adresse avec l'endpoint /v1/reverse.

Paramètres de requête

Paramètre	Type	Requis	Description
`lat`	number	Oui	Latitude du lieu (-90 à 90)
`lon`	number	Oui	Longitude du lieu (-180 à 180)
`zoom`	integer	Non	Niveau de détail de l'adresse (3 à 18, défaut : 18). Des valeurs plus élevées retournent des adresses plus précises
`addressdetails`	integer	Non	Inclut une décomposition de l'adresse en éléments (0 ou 1, défaut : 1)

Pour la liste complète des paramètres, voir la Référence API du géocodage inverse.

cURL
Python
JavaScript
PHP

curl -s -f -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/reverse?lat=48.8566&lon=2.3522" || echo "Error: request failed" >&2

import os
import sys
import requests

api_key = os.environ.get("GEOCODEME_API_KEY")
if not api_key:
    sys.exit("Set the GEOCODEME_API_KEY environment variable")

base_url = "https://api.geocodeme.net/v1"

response = requests.get(
    f"{base_url}/reverse",
    params={"lat": 48.8566, "lon": 2.3522},
    headers={"X-Api-Key": api_key},
)
if not response.ok:
    try:
        error = response.json()
        sys.exit(f"{error['error']['code']}: {error['error']['message']}")
    except (ValueError, KeyError):
        sys.exit(f"HTTP {response.status_code}: {response.text}")

data = response.json()
if data["result"] is None:
    print("No results found for the given coordinates")
    sys.exit(1)
print(data["result"]["display_name"])

// Node.js uniquement — pas pour les navigateurs. Nécessite Node.js 18+ avec le await de premier niveau.
const apiKey = process.env.GEOCODEME_API_KEY;
if (!apiKey) {
  console.error("Set the GEOCODEME_API_KEY environment variable");
  process.exit(1);
}

const baseUrl = "https://api.geocodeme.net/v1";

const reverseResponse = await fetch(
  `${baseUrl}/reverse?lat=48.8566&lon=2.3522`,
  { headers: { "X-Api-Key": apiKey } }
);

if (!reverseResponse.ok) {
  const text = await reverseResponse.text();
  let parsed;
  try {
    parsed = JSON.parse(text);
  } catch {
    console.error(`HTTP ${reverseResponse.status}: ${text}`);
    process.exit(1);
  }
  console.error(`${parsed.error?.code ?? reverseResponse.status}: ${parsed.error?.message ?? text}`);
  process.exit(1);
}

const reverseData = await reverseResponse.json();
if (reverseData.result === null) {
  console.error("No results found for the given coordinates");
  process.exit(1);
}
console.log(reverseData.result.display_name);

Utilise le helper geocodeme_get() de la page d'exemples PHP :

<?php
// Collez le helper geocodeme_get() de la page d'exemples PHP, puis :

$data = geocodeme_get('/reverse', ['lat' => 48.8566, 'lon' => 2.3522]);
if (empty($data->result)) {
    throw new RuntimeException('No results found for the given coordinates');
}
echo $data->result->display_name . PHP_EOL;

Réponse attendue

{
  "result": {
    "display_name": "3 Rue de Rivoli, Paris, Île-de-France, France",
    "lat": 48.8565,
    "lon": 2.3524,
    "address": {
      "house_number": "3",
      "road": "Rue de Rivoli",
      "city": "Paris",
      "state": "Île-de-France",
      "country": "France",
      "country_code": "fr"
    }
  },
  "attribution": "© OpenStreetMap contributors",
  "meta": {
    "took_ms": 8,
    "cache_hit": false
  }
}

attention

Contrairement à /v1/geocode qui retourne results (un tableau), /v1/reverse retourne result : un objet unique, ou null quand aucune adresse n'est trouvée. Les champs d'adresse comme house_number et road sont optionnels ; vérifiez toujours leur présence avant d'y accéder.

Erreurs courantes

L'API retourne les erreurs dans un format standard :

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

Statut HTTP	Code d'erreur	Cause	Correctif
400	`MISSING_PARAMETER`	Paramètre de requête requis manquant (ex. `q` absent)	Ajoutez le paramètre manquant à votre requête
400	`INVALID_PARAMETER`	Valeur de paramètre hors limites (ex. `lat=999`)	Vérifiez les contraintes des paramètres dans la Référence API
401	`INVALID_API_KEY`	Header `X-Api-Key` manquant ou clé révoquée	Vérifiez votre clé dans le tableau de bord ; régénérez-la si nécessaire
429	`RATE_LIMIT_EXCEEDED`	Trop de requêtes pour votre plan ; voir les limites par plan	Implémentez un backoff exponentiel ; consultez le header `X-RateLimit-Remaining`
500	`INTERNAL_ERROR`	Erreur serveur inattendue	Réessayez après un court délai ; contactez le support si le problème persiste

Limites de débit

Plan	Requêtes/seconde	Quota de crédits
Free	1	3 000 / jour
Startup	10	150 000 / mois
Growth	15	500 000 / mois
Pro	25	1 500 000 / mois

Voir les tarifs en vigueur pour le détail des plans.

Chaque réponse de l'API inclut des headers de limite de débit. Inspectez-les avec :

curl -I -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/geocode?q=Paris"

X-RateLimit-Remaining : nombre de requêtes restantes dans la fenêtre par seconde en cours
X-RateLimit-Reset : timestamp Unix de réinitialisation de la fenêtre de limite de débit
X-RateLimit-Monthly-Remaining : nombre de requêtes restantes dans votre quota mensuel

Voir Limitation de débit pour la liste complète des headers et la gestion des réponses 429.

Étapes suivantes

Authentification : bonnes pratiques de sécurité des clés API et limites de débit par plan
Référence API : documentation complète des endpoints avec tous les paramètres
Exemples : plus d'exemples de code pour les tâches de géocodage courantes

Prérequis​

Effectuez votre première requête​

Paramètres de requête​

Réponse attendue​

Géocodage inverse​

Paramètres de requête​

Réponse attendue​

Erreurs courantes​

Limites de débit​

Étapes suivantes​

Prérequis

Effectuez votre première requête

Paramètres de requête

Réponse attendue

Géocodage inverse

Paramètres de requête

Réponse attendue

Erreurs courantes

Limites de débit

Étapes suivantes