API d'altitude

Envoyez une coordonnée ou jusqu'à mille et recevez l'altitude du MNE en mètres, dans le même ordre. Les valeurs, le datum et les métadonnées de la source changent ensemble avec la publication active; /coverage.json l'indique. La publication 6, fondée sur Mapterhorn, est en service.

Chaque requête nécessite une clé API; voir Authentification.

import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  center: [-114.0719, 51.0447],
  zoom: 11,
});

const [metres] = await unmap.elevation.get([-114.0719, 51.0447]);

unmap.map!.on("click", async (e) => {
  const [here] = await unmap.elevation.get([e.lngLat.lng, e.lngLat.lat]);
  console.log(here === null ? "no data here" : `${here} m`);
});

npm i @unmap/elevation

pnpm add @unmap/elevation

yarn add @unmap/elevation

bun add @unmap/elevation

@unmap/elevation est le client autonome; @unmap/sdk expose le même objet sous unmap.elevation. Tout ce qui suit est le contrat HTTP sous les deux.

GET /elevation

• near (obligatoire, sauf si points est fourni) : une coordonnée unique sous la forme lng,lat, par exemple near=-114.0719,51.0447. C'est l'écriture qu'utilise tout autre point de terminaison unmap qui prend un point d'ancrage.
• points (obligatoire, sauf si near est fourni) : plusieurs coordonnées en une seule requête, des paires lng,lat séparées par |, par exemple -114.0719,51.0447|-115.5708,51.1784. Jusqu'à 1000 coordonnées.

Exactement une des deux formes. Envoyer les deux donne un 400.

Un lot est aussi borné par l'URL de la requête, pas seulement par le nombre de coordonnées. Une URL est limitée à 16 Ko, et les séparateurs sont encodés en pourcent sur le fil, donc environ 700 coordonnées à six décimales tiennent avant que l'URL ne soit pleine : en pratique, ce plafond arrive avant la limite de 1000. Au-delà, la requête est refusée en périphérie avec un 414, avant que la passerelle ne la voie, donc il n'y a aucune enveloppe d'erreur à lire. @unmap/elevation vérifie l'URL qu'il a construite et lève une erreur d'abord, en nommant combien de vos coordonnées tiennent.

Une requête vaut un appel facturé, qu'elle porte une seule coordonnée ou les 1000, la même règle que suivent /route et /isochrone : grouper des coordonnées dans une seule requête ne coûte rien de plus que les demander une à une.

curl "https://api.unmap.dev/elevation?near=-114.0719,51.0447&key=YOUR_KEY"

import { Unmap } from "@unmap/sdk";
 
const unmap = new Unmap({ key: "um_live_..." });
const [metres] = await unmap.elevation.get([-114.0719, 51.0447]);

Avec la publication mondiale 6 active, la réponse HTTP prend cette forme :

{
  "elevations": [1046.2],
  "units": "m",
  "datum": "mixed",
  "resolution": null,
  "model": "mixed",
  "sampling": {
    "zoom": 12,
    "tile_size": 512,
    "height_increment_m": 0.5,
    "interpolation": "bilinear"
  },
  "meta": {
    "source": "Mapterhorn / underlying elevation suppliers: Global digital elevation model, publisher snapshot 0.0.13",
    "source_updated_at": "2026-09-11T14:58:22.000Z",
    "source_version": "Mapterhorn 0.0.13; unmap terrain release 5",
    "data_version": "5",
    "attribution": "© Mapterhorn and underlying elevation suppliers. Supplier notices and licences: https://mapterhorn.com/attribution"
  }
}

• elevations : mètres arrondis au dixième, dans l'ordre demandé. Les valeurs négatives et zéro sont valides; les données absentes donnent null.
• units : toujours "m".
• datum : "mixed" pour Mapterhorn, "CGVD2013" pour le MNEMR canadien. La mosaïque mondiale n'uniformise pas les datums verticaux.
• resolution : null pour le MNE mondial mixte, 30 pour le MNEMR. Null indique ici une résolution native variable, pas une altitude absente.
• model : "mixed" pour Mapterhorn : terrain nu (MNT) dans certaines régions, surface incluant végétation ou bâtiments (MNS) ailleurs. Absent de la réponse du MNEMR canadien.
• sampling : interpolation bilinéaire à z12 sur des tuiles de 512 px. L'incrément de 0,5 m concerne l'encodage, pas la précision de mesure. Absent de la réponse du MNEMR canadien.
• meta : d'où viennent les valeurs, dans la même forme qu'utilisent Lieux, Transport en commun et Événements routiers. attribution est la mention que vous devez afficher; le reste indique la fraîcheur du MNT. Notez qu'il se trouve à côté des valeurs plutôt qu'autour : ce point de terminaison est antérieur à l'enveloppe { data, meta } et conserve la forme de corps qu'il a publiée.

Un near ou une entrée de points mal formé donne un 400 nommant la valeur en cause : near=200,51 répond near: lng must be a number between -180 and 180. Plus de 1000 coordonnées dans points donne aussi un 400, tout comme envoyer à la fois near et points. Ces corps sont { "error": "<la règle>", "code": "bad_request" }. Une longitude ou une latitude hors du WGS84 est ce 400.

Une archive de relief non configurée est un 404 { "error": "terrain archive not configured", "code": "not_found" }, le même corps qu'une tuile de relief non configurée. Une tuile qui ne se décode pas est un 502 { "error": "elevation sample failed", "code": "upstream_error" }. Une coordonnée que l'archive ne couvre pas reste un 200 avec null.

Une publication mondiale inconnue, non vérifiée ou absente donne 503, code service_unavailable, sans repli automatique sur un autre MNE.

Ce que null veut dire

null dans elevations veut dire que l'archive ne couvre rien à cette coordonnée. Cela ne veut jamais dire le niveau de la mer, et le client ne substitue aucun nombre à un trou dans les données. Vérifiez null avant de faire un calcul sur un résultat, comme vous vérifieriez un champ manquant venant de toute autre API : un zéro silencieux à cet endroit se lirait comme une vraie mesure sur la côte, l'endroit le plus mal choisi pour se tromper.

Le jeu de données et sa couverture

Le relief et l'altitude utilisent la même copie immuable de l'archive planet de Mapterhorn. Elle combine des produits régionaux et un fond mondial Copernicus GLO-30. Les résolutions natives, datums verticaux et modèles de terrain/surface varient. Ce n'est pas un MNT uniforme, un lidar national ni un produit d'arpentage. Les licences et mentions des fournisseurs sont conservées à la page Attribution.

La couverture Web Mercator s'étend approximativement de 85,0511°S à 85,0511°N. Les coordonnées au-delà donnent null; l'interpolation en longitude franchit ±180°. Une tuile absente donne également null. Le zéro océanique peut être un remplissage et n'est ni une bathymétrie ni une preuve de mesure du niveau de la mer.

Sources

Ne présentez pas les valeurs mondiales comme des hauteurs du sol nu ou en CGVD2013. La quantification de l'encodage n'est pas la précision de mesure; la date de publication ou de copie n'est pas la date de chaque levé. Les valeurs négatives et zéro sont valides; le zéro océanique peut être un remplissage. Les tuiles absentes et coordonnées au-delà d'environ ±85,0511° donnent null; une corruption donne 502 et une publication indisponible donne 503, sans repli automatique.

La publication 6 combine la mosaïque Mapterhorn copiée avec une correction régionale MNEMR-30 auditée. La zone de transition mélange les deux sources; les métadonnées mondiales restent mixtes. Cette correction ne transforme pas le jeu mondial en MNT uniforme de 30 m ni en données utilisant un seul référentiel vertical.

Le MNEMR-30 est servi avec sa couverture canadienne, son datum CGVD2013, ses cellules nominales de 30 m et l'extrapolation près des limites de couverture. /terrain/4/{z}/{x}/{y}.png et les courbes de niveau canadiennes gardent cette provenance indépendamment du MNE actif. Les graphes routiers gardent la source de leur construction; une altitude mondiale ne rend pas les itinéraires mondiaux.

Conservez l'attribution du style et affichez celle de la réponse d'altitude. La page Attribution conserve le catalogue des fournisseurs et les mentions MNEMR et Copernicus.

Limites et facturation

Une requête vaut un appel, qu'elle porte une seule coordonnée ou un lot complet de 1000 (ou les quelque 700 que laisse la limite d'URL de 16 Ko, selon ce que vous atteignez en premier). Il n'y a pas de module complémentaire : l'altitude est disponible sur tous les forfaits, au même tarif par appel que le reste de la passerelle.

Voir Erreurs pour l'enveloppe d'erreur commune.

Prochaines étapes

• Trouver l'altitude reprend ce point de terminaison comme exemple à copier.
• Erreurs pour le contrat d'échec commun à tous les points de terminaison.
• L'API de cartes pour les tuiles de terrain qui rendent le même modèle.