Référence de l'API

Toutes les routes servies par la passerelle, au même endroit. Les pages précédentes expliquent chaque service; celle-ci est le tableau que vous gardez ouvert pendant que vous écrivez l'appel.

La version lisible par machine est /openapi.json (OpenAPI 3.1), repérable depuis /.well-known/api-catalog. Générez un client à partir de là plutôt que de recopier cette page.

Conventions

Chaque route est un GET avec des paramètres de requête et sans corps, sauf les deux écritures BYOD et POST /geocode/batch. Les réponses sont en JSON, sauf les tuiles (octets Mapbox Vector Tile), le relief (PNG), les glyphes et les sprites.

Les coordonnées sont longitude,latitude, dans cet ordre, en degrés WGS84. Les cadres englobants sont minlng,minlat,maxlng,maxlat.

L'authentification est une clé à l'un de trois endroits, vérifiés dans cet ordre :

Forme	Quand
`Authorization: Bearer um_live_…`	Appels côté serveur. La forme normale.
`X-API-Key: um_live_…`	Clients qui réservent `Authorization` à autre chose.
`?key=um_live_…`	Obligatoire pour les tuiles, glyphes, sprites, relief et courbes de niveau : MapLibre ne peut pas joindre d'en-têtes aux requêtes qu'il émet pour eux. Retirée avant la mise en cache.

L'authentification précède le routage : une requête non authentifiée vers n'importe quel chemin retourne 401, y compris un chemin qui n'existe pas. Voir Authentification.

Les modules restreignent les couches et grammaires sectorielles : legal-land, energy, agriculture, remote, mining. Une clé sans le module requis reçoit 403 avec le module nommé. Voir Couches pour en acheter un.

Cartes

`GET /styles/{style}.json`

Un document de style MapLibre. L'unique URL dont la plupart des applications ont besoin.

Paramètre	Où	Notes
`style`	chemin, obligatoire	`base`, `muted`, `outdoor`, `blueprint`, `blush`, `orchid`, `canopy`, `lagoon`, `tropic`, `sunset`, `bold`, `pastel`. Un suffixe `-light` ou `-dark` fixe le mode.
`mode`	requête	`light` ou `dark`. Une valeur inconnue est ignorée, pas rejetée.
`lang`	requête	Sous-étiquette primaire BCP 47, `en` par défaut. `fr-CA` donne `fr`. Sinon `Accept-Language`, puis `en`.
`theme`	requête	Un code `ut1.` de unmap.dev/create. Un thème remplace la cartographie et l'emporte donc sur le style du chemin.
`overlays`	requête	Identifiants du catalogue séparés par des virgules, ou `byod:<id>`. L'emporte sur `profile`.
`profile`	requête	`energy`, `agriculture`, `remote` ou `mining`. Un préréglage de composition, pas un style.

Retourne application/json : un style complet avec sources, layers, glyphs, sprite et metadata.

Aussi 400 identifiant de superposition ou profil inconnu · 404 le nom du style ne résout pas.

`GET /tiles/{z}/{x}/{y}`

Le fond de carte du Canada, en octets Mapbox Vector Tile. Lu par plage depuis le stockage objet, jamais par le calcul, ce qui en fait la chose la plus rapide ici.

z, x, y sont des entiers de chemin. ?key= est obligatoire.

Retourne application/x-protobuf.

Aussi 204 la requête est dans l'archive mais il n'y a pas de tuile là · 400 coordonnées mal formées, en texte brut plutôt qu'en JSON.

`GET /terrain/{z}/{x}/{y}`

Élévation MRDEM-30 pour l'ombrage, encodée Terrarium. Utilisée par le style outdoor. Une forme versionnée, /terrain/{version}/{z}/{x}/{y}, existe pour qu'une archive reconstruite obtienne une nouvelle URL; celles-là sont mises en cache immuables pour un an.

Retourne image/png. Aussi 204 pas de tuile · 404 archive non configurée.

`GET /contours/{z}/{x}/{y}`

Courbes de niveau du même MNE, de z9 à z13, sans ligne de 0 m. Forme versionnée offerte.

Retourne application/x-protobuf. Aussi 204 pas de tuile · 404 non configurée.

`GET /glyphs/{fontstack}/{range}.pbf`

Glyphes de police, par exemple Noto Sans Regular/0-255.pbf. Inclut les fontes qui dessinent les syllabiques. Forme versionnée offerte. Non facturé.

Retourne application/x-protobuf. Aussi 404 fonte ou plage inconnue.

`GET /sprite/{file}`

Feuille de sprites, .json ou .png, avec variantes @2x. Forme versionnée offerte. Non facturé.

Retourne application/json ou image/png. Aussi 400 extension inattendue · 404 sprite inconnu.

Catalogue et données

`GET /layers`

Le catalogue complet. Les clés d'objets de stockage ne sont jamais exposées; une couverture incomplète l'est toujours.

Retourne application/json, un tableau de :

{
  "id": "energy.wells",
  "display_name": { "en": "Wells", "fr": "Puits" },
  "namespace": "energy",
  "source": "…",
  "source_url": "…",
  "licence": "…",
  "attribution": "…",
  "coverage": "…",
  "resolution": "…",
  "updated_at": "2026-09-10",
  "source_updated_at": "…",
  "ingestion_version": "1",
  "schema_version": "1",
  "freshness_policy": "…",
  "known_gaps": "…",
  "addon": "energy",
  "archives": [{ "id": "default", "minzoom": 4, "maxzoom": 12 }],
  "source_layer": "wells"
}

Une archive contenant plus d'une couche vectorielle porte aussi source_layers, la liste complète. Les grilles d'arpentage s'en servent : survey.dls empile seize niveaux dans un fichier et survey.nts quatre, chacun avec sa plage de zoom, pour qu'un client ajoute exactement le niveau voulu. Voir Couches.

Lisez known_gaps avant de promettre une couverture à un utilisateur. C'est rédigé pour être exact plutôt que flatteur : plusieurs couches ne couvrent qu'une province.

`GET /layers/{id}`

Une fiche du catalogue, même forme. Aussi 404 couche inconnue.

`GET /layers/{id}/{z}/{x}/{y}`

Tuiles de superposition pour une couche. ?key= est obligatoire.

Retourne application/x-protobuf.

Aussi 204 hors de la plage de zoom, ou pas de tuile · 403 module requis · 404 la couche est cataloguée mais son archive n'est pas encore téléversée.

`GET /identify`

Quelles entités du catalogue contiennent un point. C'est le gestionnaire de clic d'une carte, et ce n'est pas du géocodage inverse : /geocode/reverse trouve les lieux nommés les plus proches, identify retourne les polygones qui contiennent le point.

Paramètre	Où	Notes
`at`	requête, obligatoire	`lng,lat`. Obligatoire sauf si vous envoyez `lon` et `lat` séparément.
`lon`, `lat`	requête	Alternative à `at`.
`layers`	requête	Identifiants identifiables, séparés par des virgules. `municipalities` par défaut, qui est du noyau : une clé sans module fonctionne quand même.
`geometry`	requête	`true` pour inclure le polygone de chaque résultat, si la fiche en a un.

Retourne application/json :

{
  "at": [-114.0719, 51.0447],
  "results": [
    { "layer": "municipalities", "id": "ab:calgary", "name": "Calgary", "province": "AB" }
  ]
}

Un résultat porte les champs de sa couche : unit et survey_system sur les cellules d'arpentage, uwi, licence, operator et status sur les fiches énergie, pid sur les parcelles, geometry si demandé.

Aussi 400 point ou couche invalide · 403 module requis · 502 / 503 le service est injoignable ou en train de démarrer.

`GET /data/query`

Toutes les entités d'une couche dans un cadre englobant. Une couche par appel, par choix.

Paramètre	Où	Notes
`layer`	requête, obligatoire	Un identifiant interrogeable du catalogue.
`bbox`	requête, obligatoire	`minlng,minlat,maxlng,maxlat`. Un filtre strict : rien en dehors n'est jamais retourné.
`limit`	requête	1 à 50, 50 par défaut. Une valeur non numérique retombe sur la valeur par défaut plutôt que d'échouer.
`geometry`	requête	`true` pour inclure la géométrie.

Retourne application/json : { "layer": …, "bbox": [4], "results": [ … ] }, les résultats ayant la même forme que pour /identify.

Aussi 400 couche inconnue ou bbox mal formée · 403 module requis · 501 la couche existe mais n'est offerte qu'en tuiles, avec les identifiants interrogeables nommés dans le message.

Géocodage

Une seule URL lit la forme de votre requête et l'achemine. Vous ne choisissez pas de service, et profile= n'a aucun effet ici : il compose des cartes, pas des recherches.

Ressemble à	Exemple	Exige
Adresse civique ou lieu	`Calgary`	noyau
Terres légales, ARD ou SNRC	`NW-25-24-1-W5`	`legal-land`
Identifiant de puits	`00/07-10-013-09W4/0`	`energy`
PID de la C.-B.	`010-867-813`	`agriculture`
Installation par son nom	`Kaybob South` avec `layers=facility`	`energy`
Route rurale ou poste restante	`RR 2 Okotoks`	noyau

`GET /geocode/search`

Paramètre	Où	Notes
`q`	requête, obligatoire	Le texte recherché.
`lang`	requête	Dans quelle langue rendre `name`, `en` par défaut. Chaque résultat porte aussi toutes ses langues sous `names`.
`limit`	requête	1 à 50, 10 par défaut.
`bbox`	requête	Un filtre strict, pas une pondération.
`layers`	requête	Types de résultats civiques admis (`address`, `street`, `locality`, `region`, `poi`), ou `well` / `facility` pour chercher dans l'énergie. Les deux ensembles ne se mélangent pas, et une valeur inconnue donne un `400`.
`focus`	requête	`lng,lat`. Préférence de proximité souple : elle réordonne, elle n'exclut pas.
`region`	requête	Province ou territoire, n'importe quelle graphie. Exclut les fiches d'une autre province; conserve celles qui n'en portent pas.
`geometry`	requête	`true` pour inclure le polygone d'arpentage.

Retourne application/json, un tableau de lieux :

[
  {
    "id": "…",
    "name": "Iqaluit",
    "layer": "locality",
    "lng": -68.5170,
    "lat": 63.7467,
    "score": 18.4,
    "names": { "en": "Iqaluit", "iu": "ᐃᖃᓗᐃᑦ" }
  }
]

Chaque résultat porte aussi source et source_id (le jeu de données d'où il provient), match_type (exact, partial, fallback, unknown), precision (point, street, locality, region, unknown) et, quand la correspondance n'est pas exacte, match_reasons. Voir métadonnées de résultat; la règle à retenir est qu'une rue ou une ville qui tient lieu d'adresse est toujours fallback, jamais exact.

Un résultat peut aussi porter distance (en mètres), category, address, legal_land, uwi, licence, operator, status, pid, bbox et geometry, selon ce qui a correspondu.

Aussi 400 q manquant, une valeur layers ou region inconnue, un focus mal formé, ou une requête faite de termes de livraison sans collectivité · 403 module requis pour les grammaires LSD, UWI ou PID.

Une analyse réussie sans fiche correspondante retourne []. Jamais un centroïde inventé, et jamais un repli silencieux sur le classement des adresses.

`GET /geocode/structured`

Paramètre	Où	Notes
`address`	requête	Ligne de rue : numéro civique et nom de rue.
`city`	requête	Nom de la municipalité.
`region`	requête	Province ou territoire, n'importe quelle graphie, normalisée en code.
`postalcode`	requête	Avec ou sans l'espace. Ce n'est pas une validation de distribution.
`country`	requête	`CA` uniquement.
`lang`, `limit`, `bbox`, `layers`, `focus`	requête	Comme pour la recherche.

Au moins un de address, city ou postalcode est requis. address et city récupèrent et classent; region et postalcode restreignent, en excluant les fiches qui les contredisent et en conservant celles qui n'en disent rien. Civique seulement : les grammaires de terre légale, de parcelle et d'énergie sont des formes de chaîne plein texte et ne sont pas détectées ici.

Retourne le même tableau de lieux que la recherche.

Aussi 400 aucun champ d'ancrage, une province inconnue, un code postal mal formé, un pays autre que CA, ou un address qui est un numéro civique sans nom de rue.

`GET /geocode/autocomplete`

Saisie assistée, même acheminement que la recherche. q obligatoire; lang en par défaut; limit 1 à 50, 8 par défaut. Retourne le même tableau.

`GET /geocode/nearby`

Lieux d'une catégorie autour d'un point.

Paramètre	Où	Notes
`category`	requête, obligatoire	De une à huit, séparées par des virgules. Un identifiant de taxonomie (`health.pharmacy`) ou un mot courant en français ou en anglais (`pharmacie`, `pharmacy`). Casse, accents et traits d'union ignorés.
`near`	requête	`lng,lat`. Exactement un de `near` et `bbox` est requis.
`bbox`	requête	Ancre au centre du cadre avec un rayon qui le couvre. « Dans les environs », pas un rectangle de découpe.
`radius`	requête	Mètres, 50 à 50000, 5000 par défaut. Un rayon explicite l'emporte sur celui déduit du `bbox`.
`limit`	requête	1 à 50, 10 par défaut.
`lang`	requête	`en` par défaut.

Retourne le même tableau, avec distance en mètres.

Aussi 400 une catégorie inconnue, nommée dans le message, ou les deux ou aucun de near et bbox.

`GET /geocode/reverse`

Ce qui se trouve près d'une coordonnée, trié par distance géodésique réelle. lon et lat sont tous deux obligatoires, en paramètres séparés. lang en par défaut; limit 1 à 50, 5 par défaut.

`POST /geocode/batch`

Jusqu'à 100 recherches directes en une requête. Contrôles partagés seulement.

Paramètre	Où	Notes
`queries`	corps, obligatoire	Tableau de 1 à 100 chaînes, ordre conservé. Les entrées vides deviennent `[]` et ne sont pas facturées.
`lang`, `limit`, `layers`, `focus`, `region`, `bbox`	corps	Comme pour la recherche.

Retourne un tableau de tableaux de lieux, aligné sur queries. L'index i est ce que GET /geocode/search retournerait pour cette chaîne. Chaque requête non vide compte pour un incrément geocode.

Aussi 400 queries manquant ou vide, ou contrôles partagés invalides · 413 plus de 100 requêtes · 429 allocation restante inférieure au nombre de requêtes non vides.

Voir Géocodage par lots et l'exemple.

Routage

`GET /route`

D'un point à un autre sur le graphe canadien.

Paramètre	Où	Notes
`from`	requête, obligatoire	`lng,lat`. Un seul paramètre, contrairement à `/isochrone`.
`to`	requête, obligatoire	`lng,lat`.
`mode`	requête	`auto`, `car`, `bicycle`, `pedestrian` ou `truck`, `auto` par défaut. `car` et `auto` sont le même profil. Toute autre valeur est un `400`; rien ne retombe silencieusement.
`use_highways`	requête	0 à 1, 0,5 par défaut. 0 évite autoroutes et voies rapides, 1 les privilégie. Modes motorisés seulement.
`use_hills`	requête	0 à 1. 0 évite les montées même si le trajet s'allonge, 1 y est indifférent. Omise, c'est la valeur par défaut de Valhalla qui s'applique, et elle varie selon le mode : 0,25 sur `bicycle`, 0,5 sur `pedestrian`. Vélo et marche seulement ; la conduite n'a aucun terme de pente.

Les paramètres de camion ne s'appliquent qu'avec mode=truck. En envoyer un sur un autre mode est un 400, pas un oubli silencieux.

Paramètre	Défaut	Plage	Unité
`height`	4,11	jusqu'à 10	mètres
`width`	2,6	jusqu'à 6	mètres
`length`	21,64	jusqu'à 50	mètres
`weight`	21,77	jusqu'à 100	tonnes brutes
`axle_load`	9,07	0 à 40	tonnes par essieu
`axle_count`	5	2 à 20	essieux
`hazmat`	false	booléen	évite les routes qui l'interdisent
`use_truck_route`	0	0 à 1	privilégier les routes de camionnage

Retourne application/json : { "distanceMeters": 42731, "durationSeconds": 2184, "geometry": { … } }.

Aussi 400 mode inconnu, ou une option de camion sur un autre mode · 422 le graphe ne peut pas relier ces deux points.

`GET /isochrone`

Plages de temps de trajet depuis un point. Prend lon et lat en deux paramètres séparés, pas from.

minutes est obligatoire : plages séparées par des virgules, fractions acceptées, au plus quatre plages d'au plus 120 minutes chacune. Mêmes mode, use_highways, use_hills et paramètres de camion que /route.

Retourne application/geo+json, une FeatureCollection avec un polygone par plage.

Aussi 400 plus de quatre plages, ou une plage de plus de 120 minutes, avec la règle nommée.

Vos propres données

Dix superpositions par compte, 5 Mo chacune. Voir Vos propres données.

Route	Fait
`POST /byod`	Téléverse `application/geo+json`, `application/vnd.pmtiles`, ou `multipart/form-data` avec un champ `file`. `?name=` fixe le nom affiché quand le corps n'est pas multipart. Retourne `201`.
`GET /byod`	Vos superpositions et le quota courant.
`GET /byod/{id}`	Les métadonnées d'une superposition.
`GET /byod/{id}/data`	Les octets stockés.
`GET /byod/{id}/{z}/{x}/{y}`	Tuiles, pour un téléversement PMTiles. Exige `?key=`.
`DELETE /byod/{id}`	La supprime. `204`, sans corps.

Une superposition est { id, name, kind, bytes, createdAt, url, overlay }, où overlay est le jeton byod:<id> que vous passez à ?overlays=.

Aussi 400 corps manquant, mauvais type, plus de 5 Mo, ou un onzième fichier · 404 identifiant inconnu, ou appartenant à un autre compte.

Supprimer une superposition qu'un style nomme encore laisse ce ?overlays=byod:<id> en 404 : mettez le style à jour d'abord.

Codes de statut

Code	Signifie
`200`	Succès.
`201`	Créé, sur `POST /byod`.
`204`	Pas une erreur. Une requête de tuile dans l'archive, sans donnée à cette tuile. Une archive manquante est un `404`, et les deux restent distincts pour qu'une mauvaise configuration ne se lise pas comme un terrain vide.
`400`	Paramètre invalide. Le message nomme la règle.
`401`	Pas de clé, ou une clé inconnue ou désactivée. Retourné aussi pour un chemin inconnu, l'authentification précédant le routage.
`413`	`POST /geocode/batch` seulement : plus de 100 requêtes.
`403`	La clé est valide mais n'a pas le module requis. Le corps le nomme.
`404`	La couche est cataloguée mais son archive n'est pas téléversée, ou le nom du style ne résout pas.
`422`	`/route` seulement : le graphe ne peut pas relier ces deux points.
`429`	Limite de débit atteinte. Lisez `Retry-After`.
`501`	`/data/query` seulement : la couche existe mais n'est offerte qu'en tuiles. Le message liste les identifiants interrogeables.
`502`, `503`	Un service est injoignable ou en train de démarrer. Réessayez.

Chaque corps d'erreur est { "error": "…" }, avec code et addon le cas échéant. Voir Erreurs pour la liste complète.

Prochaines étapes

Couches pour le catalogue et l'achat d'un module.
Erreurs pour la signification de chaque code.
MCP pour atteindre les mêmes capacités depuis un agent IA.