API d'altitude

Un seul point de terminaison : envoyez-lui une coordonnée unique ou jusqu'à mille, et il répond avec l'altitude du sol en mètres au-dessus du CGVD2013 pour chacune d'elles.

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

résultat en direct

le code qui l’a produit

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.

Altitude

GET /elevation

lon, lat (obligatoires, sauf si points est fourni) : une coordonnée unique.
points (obligatoire, sauf si lon/lat sont fournis) : plusieurs coordonnées en une seule requête, des paires lon,lat séparées par |, par exemple -114.0719,51.0447|-115.5708,51.1784. Jusqu'à 1000 coordonnées. Fournir points en même temps que lon/lat 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?lon=-114.0719&lat=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]);

{ "elevations": [1046.9], "units": "m", "datum": "CGVD2013", "resolution": 30 }

elevations : une entrée par coordonnée, dans l'ordre demandé, en mètres, arrondie au dixième près. Une entrée vaut null là où l'archive n'a aucune donnée à cet endroit; voir « Ce que null veut dire » plus bas.
units : toujours "m".
datum : "CGVD2013", le datum vertical par rapport auquel chaque valeur est mesurée.
resolution : 30, la taille nominale de la cellule du MNT source, en mètres. Cela décrit la donnée de référence, pas la requête : les échantillons sont lus sur une surface plus fine, interpolée bilinéairement, donc resolution n'est pas l'espacement entre les points que vous pouvez interroger.

Un lon, un lat, ou une entrée de points mal formé donne un 400 nommant la valeur en cause. Plus de 1000 coordonnées dans points donne aussi un 400.

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

Les altitudes viennent du MRDEM-30 de RNCan, qui fait partie de la série CanElevation. C'est un modèle numérique de terrain (un MNT) : il décrit le sol, pas la canopée ni les toits. Les cellules font 30 m nominal, dans le système de référence source EPSG:3979, sur le datum vertical CGVD2013, donc une valeur est une hauteur au-dessus du géoïde, pas une hauteur ellipsoïdale.

Le MRDEM-30 est construit à partir de Copernicus GLO-30, avec comblement des vides, et le lidar HRDEM de RNCan y est fusionné là où il existe. /elevation échantillonne cette surface par interpolation bilinéaire à partir des quatre cellules environnantes, plutôt que de se caler sur la plus proche.

Les données sont sous Licence du gouvernement ouvert - Canada (OGL-Canada). Un avis Copernicus WorldDEM-30 est reproduit sur unmap.dev/attribution.

La couverture et sa limite

La couverture est le Canada, plus le débordement de bassin versant à travers la frontière américaine que la source porte elle-même; elle atteint 85°N.

Au-delà de 85,05°N et de 85,05°S, là où s'arrête la grille web mercator sur laquelle l'archive est tuilée, la réponse est null plutôt que la valeur à la latitude la plus proche qu'elle peut échantillonner.

À environ une tuile de la limite de couverture, le long des côtes, de la frontière américaine et des embouchures de fjords, les valeurs sont extrapolées à partir de la cellule réelle la plus proche plutôt que mesurées, parce que le même jeu de données sert aussi à l'ombrage du relief et qu'un bord net y dessinerait une falaise. Considérez les altitudes à moins d'environ 10 km d'eau libre comme indicatives.

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.