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

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.

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.

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.

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.

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.

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.

GET /geocode/search

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": "ᐃᖃᓗᐃᑦ" }
  }
]

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, 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/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.

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.

Routage

GET /route

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

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.

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

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

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.