GET /v1/elevation

Vue d'ensemble

Récupère l'altitude du terrain pour un ou plusieurs points. Avec range=true, la réponse associe aussi chaque point à sa distance cumulée le long du tracé : un profil altimétrique prêt à tracer pour une sortie vélo ou une randonnée. Autres usages : logistique sensible à la pente (autonomie VE, itinéraires poids lourds), enrichissement de traces GPS avec l'altitude.

Coût : 2 crédits par requête (quel que soit le nombre de points). Disponibilité : à partir du plan Startup.

Requête

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

Header requis : X-Api-Key: gm_YOUR_API_KEY

Paramètres

Paramètre	Type	Requis	Défaut	Description
points	string	Oui	aucun	Points au format lon,lat séparés par | (1 à 500 entrées), par ex. 6.8652,45.8326|6.8700,45.8300
range	boolean	Non	false	Avec true, renvoie aussi le profil altimétrique à distance cumulée (range_profile)

remarque

Pensez à encoder le séparateur | en %7C dans l'URL si votre client HTTP ne le fait pas pour vous.

Exemples de code

cURL

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/elevation?points=6.8652,45.8326%7C6.8700,45.8300&range=true"

Python

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.get(
    "https://api.geocodeme.net/v1/elevation",
    params={"points": "6.8652,45.8326|6.8700,45.8300", "range": "true"},
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
for distance_m, height_m in data["range_profile"]:
    print(f"{distance_m:>7.0f} m -> {height_m} m d'altitude")

JavaScript

const apiKey = process.env.GEOCODEME_API_KEY;

const params = new URLSearchParams({
  points: "6.8652,45.8326|6.8700,45.8300",
  range: "true",
});

const response = await fetch(
  `https://api.geocodeme.net/v1/elevation?${params}`,
  { headers: { "X-Api-Key": apiKey } }
);

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

const data = await response.json();
for (const [distanceM, heightM] of data.range_profile) {
  console.log(`${distanceM} m -> ${heightM} m d'altitude`);
}

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.).

Avec range=true :

{
  "elevations": [1035.0, 1002.0],
  "range_profile": [
    [0.0, 1035.0],
    [472.0, 1002.0]
  ],
  "attribution": "Route data (c) OpenStreetMap contributors; elevation (c) Tilezen/AWS",
  "meta": {
    "took_ms": 12,
    "cache_hit": false
  }
}

Sans range, la réponse ne contient que elevations (le champ range_profile est absent, pas null).

Schéma

Champ	Type	Description
elevations	array	elevations[i] = altitude en mètres du i-ème point d'entrée, ou null si le point est hors du terrain connu
range_profile	array	Paires [distance_cumulée_m, altitude_m] le long du tracé (présent uniquement avec range=true)
attribution	string	Toujours "Route data (c) OpenStreetMap contributors; elevation (c) Tilezen/AWS"
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

Altitudes null

Une entrée null signifie que le point est hors de la couverture du modèle de terrain (par exemple en pleine mer). La requête elle-même réussit ; vérifiez chaque entrée plutôt que le statut HTTP.

Réponses d'erreur

Trop de points (ou aucun)

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "'points' must contain between 1 and 500 'lon,lat' entries",
    "field": "points"
  }
}

Endpoint non inclus dans votre plan (Free)

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "The 'elevation' feature is not included in your plan. Upgrade to unlock it.",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

astuce

Tous les endpoints sont également soumis aux erreurs INVALID_API_KEY (401) et RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED (429). Consultez Codes d'erreur pour la référence complète.