API reference

A reference for the gateway data APIs. The pages before this one explain each service; this one is the table you keep open while you write the call.

Maps, the catalog, geocoding, routing and BYOD have a full entry below with every parameter. The services Places, Transit, Elevation, Road events and the routing expansion, are listed with their purpose and their parameters in Other APIs and documented in full on their own pages.

The machine-readable version is /openapi.json (OpenAPI 3.1), discoverable from /.well-known/api-catalog. Generate a client from that rather than transcribing this page.

Conventions

Most routes are a GET with query parameters and no request body. The exceptions are POST /byod, DELETE /byod/{id}, POST /geocode/batch, POST /matrix, POST /match, POST /optimized-route, POST /optimize and its GMPRO paths, POST /feedback, POST /places/{id}/feedback, and the body forms of POST /route and POST /isochrone, which exist only because avoid_areas is a polygon and a polygon cannot ride a query string. Responses are JSON except tiles (Mapbox Vector Tile bytes), terrain (WebP or PNG), glyphs and sprites.

Coordinates are longitude,latitude, in that order, in WGS84 degrees. Bounding boxes are minlng,minlat,maxlng,maxlat.

One point is near=lng,lat. That spelling works on /places/nearby, /geocode/nearby, /transit/stops, /incidents, /elevation, /geocode/reverse and /isochrone, and in the body of POST /isochrone. /route names its two ends from and to, each a lng,lat pair. In JSON request bodies, coordinate pairs are arrays, so POST /isochrone uses "near": [lng, lat].

Two HTTP exceptions use separate names: /timezone takes lat and lon, while /identify takes at=lng,lat. The SDK still accepts [lng, lat] pairs for both.

Authentication is one key in any of four places, checked in this order:

On protected data paths, auth runs before routing, so an unauthenticated request returns 401, including a path that does not exist. Discovery documents and /coverage.json are public exceptions. See Authentication.

Add-ons gate the industry layers and grammars: legal-land, energy, agriculture, remote, mining. A key without the one a request needs gets 403 with the add-on named. See Layers for how to buy one.

Maps

GET /styles/{style}.json

A MapLibre style document. The one URL most applications need.

Returns application/json: a complete style with sources, layers, glyphs, sprite and metadata. Cache-Control: private, no-store: the document contains the API key and the tile template for this deploy.

Also 400 invalid_theme for a theme code that does not decode, with a detail array · 400 bad_request for an unknown overlay id or profile · 404 the style name does not resolve · 503 plain text basemap release is misconfigured when the active release is not an eight-digit id or its object is missing, with Cache-Control: private, no-store. The previous archive is not served.

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

The worldwide basemap, as Mapbox Vector Tile bytes. Range-read from object storage, never through compute, which is why it is the fastest thing here.

z, x, y are path integers. Authentication is required; use Authorization: Bearer <key>, X-API-Key: <key>, or ?key=<key>. Style-generated URLs use the query form so MapLibre can fetch tiles and assets automatically. Direct callers can use either header.

Returns application/x-protobuf.

Also 204 the request is inside the archive but there is no tile there. That response is not written to the Worker cache · 400 plain text invalid tile coordinates for a non-integer, or for a column outside 0 .. 2^z-1 · 503 plain text basemap release is misconfigured when the active release is not an eight-digit id or its object is missing, Cache-Control: private, no-store, and the previous archive is not served.

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

The same tile, pinned to an 8-digit basemap release. The undated path follows whichever archive is active. The default is the September 22, 2026 planet release. An eight-digit id that was never copied is plain text 404 basemap release not found with Cache-Control: private, no-store. An id that is not eight digits is that same body without the cache header. If the active archive was switched to a release that is not on the server, the style and the undated path answer 503 basemap release is misconfigured, also private, no-store, and do not serve the Canada extract. Retrying does not restore it.

Returns application/x-protobuf. Also 204 no tile, not written to the Worker cache · 400 plain text invalid tile coordinates for a non-integer, or for a column outside 0 .. 2^z-1.

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

Terrarium/512 relief, z0–12. /terrain/6/{z}/{x}/{y}.webp serves global Mapterhorn. /terrain/4/{z}/{x}/{y}.png serves Canadian MRDEM. /coverage.json reports the active release. Versioned URLs identify their own archive; unknown releases or mismatched suffixes return JSON 404 not_found. XYZ outside the tile grid returns plain-text 400 invalid tile coordinates.

Returns image/webp or image/png, matching the representation. Also 204 no data, not cached · 404 terrain archive not configured · 503 unavailable selected release, without automatic fallback · 502 tile read failure.

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

Canadian contour lines from MRDEM-30, z9 to z13, with no 0 m line. The version is currently 4, cached public, max-age=86400. A version that is not a small integer is plain text 400 invalid tile coordinates.

Returns application/x-protobuf. Also 204 no tile inside a configured archive, not written to the Worker cache · 404 JSON not_found, contour archive not configured.

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

Font glyphs, for example Noto Sans Regular/0-255.pbf. Includes the faces that draw syllabics. The version is currently 2. A successful response is cached public, max-age=31536000, immutable. Not metered.

Returns application/x-protobuf. Also 400 plain text invalid fontstack, invalid range, or invalid asset version · 404 plain text not found when that object is absent, without that cache header.

GET /sprite/{version}/{file}

Sprite sheet, .json or .png, with @2x variants. The sheets are light, dark, muted-light, and muted-dark. The version is currently 2, cached public, max-age=31536000, immutable. Not metered.

Returns application/json or image/png. Also 400 plain text invalid sprite, or invalid asset version · 404 plain text not found, without that cache header.

GET /layers

The whole catalog. Raw storage object keys are never exposed; incomplete coverage always is.

Returns application/json, an array of:

{
  "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"
}

An archive holding more than one vector layer also carries source_layers, the full list. The survey grids use it: survey.dls stacks sixteen levels in one file and survey.nts four, each with its own zoom range, so a client can add exactly the level it wants as its own map layer. See Layers.

Read known_gaps before you promise coverage to a user. It is written to be accurate rather than flattering: several layers cover one province, not the country.

GET /layers/{id}

One catalog row, same shape. Also 404 JSON not_found unknown layer.

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

Overlay tiles for one catalog layer. ?key= is required.

Returns application/x-protobuf.

Also 204 outside the layer's zoom band, or no tile there. That response is not written to the Worker cache · 403 add-on required · 404 JSON not_found: unknown layer when the id is not in the catalog, or layer archive not configured when the object is not in the bucket.

GET /identify

Which catalog features contain a point. This is the click handler for a map, and it is not reverse geocoding: /geocode/reverse finds the nearest named places, identify returns the polygons the point falls inside.

Returns application/json:

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

A result carries the fields its layer has: unit and survey_system on survey cells, uwi, licence, operator and status on energy rows, pid on parcels, geometry when asked for.

Also 400 bad point or unknown layer · 403 add-on required · 502 / 503 the backing service is unreachable or still waking.

GET /data/query

Every feature of one layer inside a bounding box. One layer per call, by design.

Returns application/json: { "layer": …, "bbox": [4], "results": [ … ] }, the results in the same shape as /identify.

Also 400 unknown layer id or malformed bbox · 403 add-on required · 501 the layer is real but tile-only, with the queryable ids named in the message.

One URL reads the shape of your query and routes it. You do not pick a backend, and profile= has no effect here: it composes maps, not searches.

GET /geocode/search

Returns application/json, an array of places:

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

Every result also carries source and source_id (which dataset it came from), match_type (exact, partial, fallback, unknown), precision (point, street, locality, region, unknown) and, when the match is not exact, match_reasons. See result metadata; the rule worth knowing is that a street or city standing in for an address is always fallback, never exact.

A result may also carry distance (metres, on nearby and reverse), category, address, legal_land, uwi, licence, operator, status, pid, bbox and geometry, depending on what matched.

Also 400 q missing, an unknown layers or region value, a malformed focus, or a query that is Canada Post delivery terms and no community · 403 add-on required for the LSD, UWI or PID grammars.

GET /geocode/structured

At least one of address, city or postalcode is required. address and city retrieve and rank; region and postalcode narrow, excluding records that contradict them and keeping records that are silent about them. Civic only: the legal-land, parcel and energy grammars are shapes of a free-text string and are not detected here.

Returns the same array of places as search.

Also 400 no anchor field, an unknown province, a malformed postal code, a country other than CA, or an address that is a civic number with no street name.

A successful parse with no matching row returns []. Never a guessed centroid, and never a silent fall-through to address ranking.

GET /geocode/autocomplete

Type-ahead, same routing as search. q required; lang default en; limit 1 to 50, default 8. Returns the same array.

GET /geocode/nearby

Places of a category around a point.

Returns the same array, carrying distance in metres.

Also 400 an unknown category token, named in the message, both or neither of near and bbox, or a longitude or latitude outside WGS84 (bad_request) · 422 outside_coverage when the anchor, or the centre of bbox, is outside Canada.

GET /geocode/reverse

What is near a coordinate, ordered by true geodesic distance. near=lng,lat is required. lang default en; limit 1 to 50, default 5.

Also 400 a missing near, or a longitude or latitude outside WGS84 (bad_request) · 422 outside_coverage when the coordinate is outside Canada. The corpus is not queried. An empty array means the point is inside Canada and nothing in the corpus is near it.

POST /geocode/batch

Up to 100 forward searches in one request. Shared controls only.

Returns an array of place arrays, aligned to queries. Index i is what GET /geocode/search would return for that string. Each non-blank query is one geocode increment.

Also 400 missing or empty queries, or invalid shared controls · 413 more than 100 queries · 429 remaining allowance less than the non-blank count.

See Batch geocoding and the example.

Routing

GET /route

Point to point across the Canada graph.

Truck parameters apply only with mode=truck. Sending one on another mode is a 400, not a silent ignore.

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

Also 400 unknown mode, a truck option on another mode, or a coordinate outside WGS84 (invalid_location) · 422 outside_coverage when an end is outside Canada, no_route when the Canadian graph cannot connect those two points.

GET /isochrone

Travel-time bands from a point, given as near=lng,lat.

minutes is required: comma-separated bands, fractions accepted, at most four bands and each 120 minutes or less. Same mode, depart_at, use_highways, use_hills and truck parameters as /route; mode=transit requires depart_at.

Returns application/geo+json, a FeatureCollection with one polygon per band. A transit band can be a MultiPolygon.

Also 400 more than four bands, a band over 120 minutes, or a coordinate outside WGS84 (invalid_location), with the rule named. 422 outside_coverage when the centre is outside Canada, or for mode=transit when no scheduled transit serves it. A Canadian centre the engine refuses is 502.

Your own data

Ten overlays per account, 5 MB each. See Bring your own data.

An overlay is { id, name, kind, bytes, createdAt, url, overlay }, where overlay is the byod:<id> token you pass to ?overlays=.

Also 400 missing body, wrong content type, over 5 MB, or an eleventh file · 404 unknown id, or one belonging to another account.

Deleting an overlay a style still names leaves that ?overlays=byod:<id> a 404, so update the style first.

Other APIs

The rest of the surface, one line each. Each links to the page that documents it properly.

Places · full page

A missing q is 400 { "error": "q is required", "code": "bad_request" }. A bbox corner outside WGS84 is 400 bad_request. On search, a box outside Canada stays a filter. On nearby, an anchor outside Canada, or a bbox whose centre is outside Canada, is 422 outside_coverage.

Transit · full page

Ski

Behind the Ski add-on: a paid key without it gets 403 addon_required, and a dev-plan key gets dev_only from a production origin or usage_limit_reached once its monthly premium calls are spent. The add-on cannot be bought yet, so until it can only development and internal keys reach these.

Elevation · full page

Time zone · full page

Road events · full page

Routing expansion · full page

Optimize · full page

Fleet planning using the Google Route Optimization OptimizeToursRequest format and OptimizeToursResponse format, for supported fields. Errors on these paths are Google's shape, { "error": { "code", "message", "status", "details" } }, with the gateway's code beside it. Per-plan caps limit shipments, vehicles, locations, the solve's timeout (clamped, with a Warning header) and solves at once; warnings ride the X-Unmap-Optimize-Warnings header.

Feedback · full page

Status codes

Most JSON error bodies are { "error": "…", "code": "…" }, with addon and capability where they apply. Optimize uses the structured error object described above. A malformed tile, terrain, contour, glyph, or sprite request answers plain text. An unconfigured terrain or contour archive is JSON not_found. /elevation uses terrain archive not configured for that case. See Errors for the full list of codes.

Next steps

• Layers for the catalog and how to buy an add-on.
• Errors for what each code means and how to handle it.
• MCP to reach the same capabilities from an AI agent.