Référence de l'API

Une référence des API de données de la passerelle. Les pages précédentes expliquent chaque service; celle-ci est le tableau que vous gardez ouvert pendant que vous écrivez l'appel.

Les cartes, le catalogue, le géocodage, les itinéraires et BYOD ont une entrée complète ci-dessous avec chaque paramètre. Les services Lieux, Transport en commun, Altitude, Événements routiers et l'expansion des itinéraires, figurent avec leur rôle et leurs paramètres dans Autres API et sont documentés en entier sur leurs propres pages.

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

La plupart des routes sont un GET avec des paramètres de requête et sans corps. Les exceptions sont POST /byod, DELETE /byod/{id}, POST /geocode/batch, POST /matrix, POST /match, POST /optimized-route, POST /optimize et ses chemins GMPRO, POST /feedback, POST /places/{id}/feedback, ainsi que les formes avec corps de POST /route et POST /isochrone, qui n'existent que parce que avoid_areas est un polygone et qu'un polygone ne tient pas dans une chaîne de requête. Les réponses sont en JSON, sauf les tuiles (octets Mapbox Vector Tile), le relief (WebP ou 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.

Un point s'écrit near=lng,lat. Cette écriture fonctionne sur /places/nearby, /geocode/nearby, /transit/stops, /incidents, /elevation, /geocode/reverse et /isochrone, ainsi que dans le corps de POST /isochrone. /route nomme ses deux extrémités from et to, chacune une paire lng,lat. Dans un corps JSON, les paires sont des tableaux : POST /isochrone utilise donc "near": [lng, lat].

Deux exceptions HTTP ont des noms distincts : /timezone prend lat et lon, et /identify prend at=lng,lat. Le SDK accepte toujours des paires [lng, lat] pour les deux.

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

Sur les chemins de données protégés, l'authentification précède le routage : une requête non authentifiée retourne 401, y compris un chemin qui n'existe pas. Les documents de découverte et /coverage.json sont des exceptions publiques. 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. Cache-Control: private, no-store : le document contient la clé d'API et le modèle d'URL des tuiles de ce déploiement.

Aussi 400 invalid_theme pour un code de thème qui ne se décode pas, avec un tableau detail · 400 bad_request pour un identifiant de superposition ou un profil inconnu · 404 le nom du style ne résout pas · 503 texte brut basemap release is misconfigured lorsque la publication active n'est pas un identifiant à huit chiffres ou que son objet manque, avec Cache-Control: private, no-store. L'archive précédente n'est pas servie.

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

Le fond de carte mondial, 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à. Cette réponse n'est pas écrite dans le cache du Worker · 400 texte brut invalid tile coordinates pour un non-entier, ou pour une colonne hors de 0 .. 2^z-1 · 503 texte brut basemap release is misconfigured lorsque la publication active n'est pas un identifiant à huit chiffres ou que son objet manque, Cache-Control: private, no-store, et l'archive précédente n'est pas servie.

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

La même tuile, épinglée à une publication de fond de carte à 8 chiffres. Le chemin sans date suit l'archive active. Par défaut, il s'agit du planet du 22 septembre 2026. Un identifiant à huit chiffres qui n'a jamais été copié est un 404 en texte brut basemap release not found avec Cache-Control: private, no-store. Un identifiant qui n'a pas huit chiffres a le même corps sans cet en-tête de cache. Si l'archive active a été basculée vers une publication absente du serveur, le style et le chemin sans date répondent 503 basemap release is misconfigured, eux aussi private, no-store, et ne servent pas l'extrait du Canada. Réessayer ne le rétablit pas.

Retourne application/x-protobuf. Aussi 204 pas de tuile, non écrite dans le cache du Worker · 400 texte brut invalid tile coordinates pour un non-entier, ou pour une colonne hors de 0 .. 2^z-1.

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

Relief Terrarium/512 à z0–12. /terrain/6/{z}/{x}/{y}.webp sert Mapterhorn mondial. /terrain/4/{z}/{x}/{y}.png sert le MNEMR canadien. /coverage.json indique la publication active. Les URL versionnées identifient leur propre archive; une publication inconnue ou un suffixe incompatible donne 404 JSON not_found. XYZ hors grille donne 400 texte brut invalid tile coordinates.

Retourne image/webp ou image/png, selon la représentation. Aussi 204 sans données, non mis en cache · 404 terrain archive not configured · 503 publication active indisponible, sans repli automatique · 502 erreur de lecture de tuile.

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

Courbes canadiennes du MNEMR-30, de z9 à z13, sans ligne de 0 m. La version est actuellement 4, en cache public, max-age=86400. Une version qui n'est pas un petit entier est un 400 en texte brut invalid tile coordinates.

Retourne application/x-protobuf. Aussi 204 pas de tuile dans une archive configurée, non écrite dans le cache du Worker · 404 JSON not_found, contour archive not configured.

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

Glyphes de police, par exemple Noto Sans Regular/0-255.pbf. Inclut les fontes qui dessinent les syllabiques. La version est actuellement 2. Une réponse réussie est en cache public, max-age=31536000, immutable. Non facturé.

Retourne application/x-protobuf. Aussi 400 en texte brut invalid fontstack, invalid range, ou invalid asset version · 404 en texte brut not found quand l'objet est absent, sans cet en-tête de cache.

GET /sprite/{version}/{file}

Feuille de sprites, .json ou .png, avec variantes @2x. Les feuilles sont light, dark, muted-light et muted-dark. La version est actuellement 2, en cache public, max-age=31536000, immutable. Non facturé.

Retourne application/json ou image/png. Aussi 400 en texte brut invalid sprite, ou invalid asset version · 404 en texte brut not found, sans cet en-tête de cache.

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 JSON not_found unknown layer.

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. Cette réponse n'est pas écrite dans le cache du Worker · 403 module requis · 404 JSON not_found : unknown layer quand l'identifiant n'est pas au catalogue, ou layer archive not configured quand l'objet n'est pas dans le stockage.

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

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

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.

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

Aussi 400 une catégorie inconnue, nommée dans le message, les deux ou aucun de near et bbox, ou une longitude ou une latitude hors du WGS84 (bad_request) · 422 outside_coverage quand l'ancrage, ou le centre du bbox, est hors du Canada.

GET /geocode/reverse

Ce qui se trouve près d'une coordonnée, trié par distance géodésique réelle. near=lng,lat est obligatoire. lang en par défaut; limit 1 à 50, 5 par défaut.

Aussi 400 un near absent, ou une longitude ou une latitude hors du WGS84 (bad_request) · 422 outside_coverage quand la coordonnée est hors du Canada. Le corpus n'est pas interrogé. Un tableau vide signifie que le point est au Canada et que rien dans le corpus n'est proche.

POST /geocode/batch

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

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.

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, une option de camion sur un autre mode, ou une coordonnée hors du WGS84 (invalid_location) · 422 outside_coverage quand une extrémité est hors du Canada, no_route quand le graphe canadien ne peut pas relier ces deux points.

GET /isochrone

Plages de temps de trajet depuis un point, donné sous la forme near=lng,lat.

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, depart_at, use_highways, use_hills et paramètres de camion que /route; mode=transit exige depart_at.

Retourne application/geo+json, une FeatureCollection avec un polygone par plage. Une plage en transport en commun peut être un MultiPolygon.

Aussi 400 plus de quatre plages, une plage de plus de 120 minutes, ou une coordonnée hors du WGS84 (invalid_location), avec la règle nommée. 422 outside_coverage quand le centre est hors du Canada, ou en mode=transit quand aucun service prévu ne le dessert. Un centre canadien que le moteur refuse donne un 502.

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.

Autres API

Le reste de la surface, une ligne chacun. Chaque entrée pointe vers la page qui la documente correctement.

Lieux · page complète

Un q absent donne un 400 { "error": "q is required", "code": "bad_request" }. Un coin de bbox hors du WGS84 donne un 400 bad_request. En recherche, un cadre hors du Canada reste un filtre. Pour nearby, un ancrage hors du Canada, ou un bbox dont le centre est hors du Canada, donne un 422 outside_coverage.

Transport en commun · page complète

Ski

Derrière le module Ski : une clé payante sans ce module reçoit 403 addon_required, et une clé du forfait dev reçoit dev_only depuis une origine de production ou usage_limit_reached une fois ses appels premium du mois épuisés. Le module ne peut pas encore être acheté; d'ici là, seules les clés de développement et internes y accèdent.

Altitude · page complète

Fuseau horaire · page complète

Événements routiers · page complète

Expansion des itinéraires · page complète

Optimize · page complète

Planification de tournées utilisant les formats OptimizeToursRequest et OptimizeToursResponse de Google Route Optimization, pour les champs pris en charge. Sur ces chemins, les erreurs suivent la forme de Google, { "error": { "code", "message", "status", "details" } }, avec le code de la passerelle à côté. Des plafonds par forfait limitent les envois, les véhicules, les lieux, le timeout de la résolution (ramené au plafond, avec un en-tête Warning) et les résolutions simultanées; les avertissements passent par l'en-tête X-Unmap-Optimize-Warnings.

Signalements · page complète

Codes de statut

La plupart des corps d'erreur JSON sont { "error": "…", "code": "…" }, avec addon et capability le cas échéant. Optimize utilise l'objet error structuré décrit ci-dessus. Une requête mal formée de tuile, de relief, de courbes, de glyphe ou de sprite répond en texte brut. Une archive de relief ou de courbes non configurée est un JSON not_found. /elevation utilise terrain archive not configured dans ce cas. 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.