Tracestrack API

read this first

Tracestrack APIs

A handful of geodata APIs provided by Tracestrack, under one set of keys: raster map tiles, vector map tiles, point elevation lookups, and a passthrough to a self-hosted Overpass API mirror of OpenStreetMap. Where the key goes, and whether an endpoint is auth-gated at all, differs by endpoint — read the auth section before wiring anything up.

Base URL https://tile.tracestrack.com or https://api.tracestrack.com

https://api.tracestrack.com and https://tile.tracestrack.com are the same production service under two hostnames — use whichever you prefer.

authentication

Where the key goes

Every request is checked against the key's plan, block status, and (if configured) an allowed-referer list before it's forwarded upstream. Need a key? Get one from the Tracestrack Console.

Endpoint	Key location	Referer check
`POST /elevation`	query string — `?key=`	enforced if the key has an allow-list
`/overpass/{key}/interpreter`	path segment	enforced if the key has an allow-list
`GET /{mapname}/{z}/{x}/{y}.{ext}`	query string — `?key=`	enforced if the key has an allow-list
`GET /vt/{name}/{z}/{x}/{y}.pbf`	query string — `?key=`	enforced if the key has an allow-list
`GET /terrain-rgb/{z}/{x}/{y}.webp`	query string — `?key=`	enforced if the key has an allow-list

The rest of the endpoints below aren't auth-gated at all — key, where accepted, is only there to get embedded into generated URLs.

Rejected requests return one of these bodies, shared across every gated endpoint:

Status	Body	Cause
403	`Key is empty.`	no key supplied
403	`Invalid key.`	key not recognized
403	`Key is blocked. Please check whether quota is reached.`	key blocked or over quota
403	`Referrer mismatch.`	Referer header doesn't match the key's allow-list
404	`Error proxying request`	Tile coordinate out of range for this zoom level, or an unknown map name.
429	`Rate limit exceeded`	Rate limit exceeded for this key.
502	`Error proxying request`	The tile origin failed to respond.

Raster maps

Fetch a combined raster map tile

GET /{mapname}/{z}/{x}/{y}.{ext}?key=…

Renders one base+label raster tile. Only combined (base and label merged) tile names are supported — see the callout below.

Parameters

Name	In	Required	Description
`mapname`	path	yes	Combined map name: a language code (or `_` for language-neutral, `auto` to pick a language from `Accept-Language`, `auto-en` to do the same but default to English) on the standard base style, or the same set prefixed with `topo_` for the topographic base style. `_` `auto` `auto-en` `ar` `de` `en` `es` `fi` `fr` `hu` `he` `it` `ja` `ko` `nl` `uk` `pl` `pt` `ru` `th` `sv` `tr` `zh-hans` `zh-hant` `topo_` `topo_auto` `topo_auto-en` `topo_ar` `topo_de` `topo_en` `topo_es` `topo_fi` `topo_fr` `topo_hu` `topo_he` `topo_it` `topo_ja` `topo_ko` `topo_nl` `topo_uk` `topo_pl` `topo_pt` `topo_ru` `topo_th` `topo_sv` `topo_tr` `topo_zh-hans` `topo_zh-hant`
`z`	path	yes	Zoom level.
`x`	path	yes	Tile column. Must be within the valid grid for the given zoom.
`y`	path	yes	Tile row. Must be within the valid grid for the given zoom. Append `@2x` right before the extension for a higher-density tile (e.g. `/en/10/1/2@2x.webp`), or `@1x` to force a 256×256 downscale — omit entirely for the default size.
`ext`	path	yes	Image format. webp is recommended. `webp` `png`
`key`	query	yes	Tracestrack API key.
`style`	query	no	Optional color filter. Omit for the default look. `dark2` `dark3` `outrun` `contrast-` `contrast+` `grayscale` `lavender` `tangerine` `pink`
`Referer`	header	no	Must match the key's allow-list, if it has one.

Response — 200

Content-Type: image/webp or image/png (binary).

Status codes

200	The rendered tile image.
403	Key missing, invalid, blocked, or referer mismatch.
404	Tile coordinate out of range for this zoom level, or an unknown map name.
429	Rate limit exceeded for this key.
502	The tile origin failed to respond.

Supported languages

Language	Code	Labels shown through
Global	`_`	0–19
English	`en`	0–19
Auto	`auto`	resolved from Accept-Language, then 0–12 unless it resolves to en
Auto (English default)	`auto-en`	resolved from Accept-Language (defaults to en), then 0–12 unless it resolves to en
Arabic	`ar`	0–12
German	`de`	0–12
Spanish	`es`	0–12
Finnish	`fi`	0–12
French	`fr`	0–12
Hungarian	`hu`	0–12
Hebrew	`he`	0–12
Italian	`it`	0–12
Japanese	`ja`	0–12
Korean	`ko`	0–12
Dutch	`nl`	0–12
Ukrainian	`uk`	0–12
Polish	`pl`	0–12
Portuguese	`pt`	0–12
Russian	`ru`	0–12
Thai	`th`	0–12
Swedish	`sv`	0–12
Turkish	`tr`	0–12
Simplified Chinese	`zh-hans`	0–12
Traditional Chinese	`zh-hant`	0–12

Try it — builds a request, doesn't send one

Map name

Zoom

Format

Style

Vector maps

Vector tiles, styles, and static assets

Nine endpoints under one umbrella: protobuf tiles, terrain-RGB elevation tiles, TileJSON metadata, MapLibre GL style documents, the sprite/font assets those styles reference, and a version-metadata lookup for each dataset. Only the two tile endpoints are auth-gated — the JSON/static ones aren't, though key is still worth passing so the URLs they embed work.

Vector tiles

GET /vt/{name}/{z}/{x}/{y}.pbf?key=…

Serves protobuf-encoded vector tiles, brotli-compressed at the origin and re-transcoded at the edge for clients that don't accept brotli. The compact alias /vt{name}/{z}/{x}/{y}.pbf (no slash after vt) is equivalent.

Parameters

Name	In	Required	Description
`name`	path	yes	Vector dataset. `topo` serves the same tile content as `carto` (they're restyled client-side, not separately rendered) — `routes` and `contours` are distinct thematic layers. `carto` `routes` `contours` `topo`
`z`	path	yes	Zoom level.
`x`	path	yes	Tile column.
`y`	path	yes	Tile row.
`key`	query	yes	Tracestrack API key.
`Referer`	header	no	Must match the key's allow-list, if it has one.

Response — 200

Content-Type: application/x-protobuf (binary).

Status codes

200	The vector tile.
403	Key missing, invalid, blocked, or referer mismatch.
404	Tile not found. The origin's status is passed through verbatim, with an empty body.
429	Rate limit exceeded for this key.

Try it — builds a request, doesn't send one

Dataset

Zoom

Terrain-RGB tiles

GET /terrain-rgb/{z}/{x}/{y}.webp?key=…

Conventionally encodes elevation as RGB pixel values (the widely-used "Terrain-RGB" convention) for client-side hillshading/3D terrain. Always authenticated as if requesting the topo map, regardless of which raster style you're pairing it with.

Parameters

Name	In	Required	Description
`z`	path	yes	Zoom level.
`x`	path	yes	Tile column.
`y`	path	yes	Tile row.
`key`	query	yes	Tracestrack API key.
`Referer`	header	no	Must match the key's allow-list, if it has one.

Response — 200

Content-Type: image/webp (binary).

Status codes

200	The terrain-RGB tile.
403	Key missing, invalid, blocked, or referer mismatch.
404	Tile not found. The origin's status is passed through verbatim, with an empty body.
429	Rate limit exceeded for this key.

Try it — builds a request, doesn't send one

Zoom

TileJSON metadata

GET /v/maps/{type}/tilejson.json

Not auth-gated — key is optional and only used to embed a working tile URL in the response's tiles field (/vt/{name}/{z}/{x}/{y}.pbf?key=...). carto_v2 and topo both resolve to the carto tile source — they share the same underlying vector data and are only styled differently client-side.

Parameters

Name	In	Required	Description
`type`	path	yes	Vector dataset / style family. `carto` `carto_v2` `routes` `contours` `topo`
`key`	query	no	Embedded into the response's tile URL template.

Response — 200

Field	Type	Required	Notes
`tilejson`	string	no	—
`name`	string	no	—
`tiles`	string[]	no	—
`minzoom`	integer	no	—
`maxzoom`	integer	no	—
`vector_layers`	object[]	no	—

Status codes

200	TileJSON document.
500	Unrecognized `type`/`mapName` — a missing static object throws before any 404 can be returned, so an unhandled error becomes a generic 500 instead.

/v/maps/topo/terrain-rgb-tilejson.json returns the same shape for the terrain-RGB dataset (no type path param — it's a fixed path).

Try it — builds a request, doesn't send one

Dataset

Style documents

GET /v/maps/{mapName}/style.json

Not auth-gated. Rewrites embedded source/sprite/glyph URLs to point back at this API, with key (if supplied) embedded into them. Language-specific variants are available at /v/maps/{mapName}/style-{lang}.json for lang in en, de, es, fr, hu, it, nl, zh-Hans, zh-Hant.

Parameters

Name	In	Required	Description
`mapName`	path	yes	Style family. `carto` `carto_v2` `dark` `darklite` `lite` `topo` `transport`
`key`	query	no	Embedded into the rewritten source/tile URLs.

Response — 200

Standard MapLibre GL style spec.

Status codes

200	MapLibre GL style document, with tracestrack-proxy URLs substituted in.
500	Unrecognized `type`/`mapName` — a missing static object throws before any 404 can be returned, so an unhandled error becomes a generic 500 instead.

Try it — builds a request, doesn't send one

Style

Routes overlay

GET /v/maps/routes/{type}.json

Not auth-gated. Same URL-rewriting behavior as the style.json endpoint above.

Parameters

Name	In	Required	Description
`type`	path	yes	Route type. `bus` `bicycle` `train` `subway`
`key`	query	no	Embedded into the rewritten source URLs.

Response — 200

JSON document.

Status codes

200	Routes overlay style document.
500	Unrecognized `type`/`mapName` — a missing static object throws before any 404 can be returned, so an unhandled error becomes a generic 500 instead.

Try it — builds a request, doesn't send one

Route type

Sprites

GET /v/maps/{mapName}/sprites/{file}

Not auth-gated, served from static storage.

Parameters

Name	In	Required	Description
`mapName`	path	yes	Style family — see style.json's `mapName` above.
`file`	path	yes	— `sprite.json` `sprite.png` `sprite@2x.json` `sprite@2x.png`

Response — 200

JSON document.

Status codes

200	Sprite sheet image or index.
404	Not found.

Fonts (glyphs)

GET /v/fonts/{fontstack}/{range}.pbf

Not auth-gated. fontstack may be a comma-separated, percent-encoded list of font names (e.g. Open%20Sans%20Regular,Noto%20Sans%20Regular) for CJK/fallback coverage — pre-composited stacks are tried first, falling back to trying each font individually.

Parameters

Name	In	Required	Description
`fontstack`	path	yes	Percent-encoded font name(s), e.g. `Open Sans Regular` or `Noto Sans Bold`.
`range`	path	yes	256-codepoint glyph range, e.g. `0-255`.

Response — 200

Content-Type: application/x-protobuf (binary).

Status codes

200	Glyph range PBF.
404	Not found.

Map version

GET /v/maps/{mapname}/version.json

Not auth-gated — served as a static JSON object from the same R2-backed static tree as style.json/sprites (see the "not auth-gated" note on style.json above), rather than generated per-request. Reports which build of the underlying map data mapname is currently serving, independent of the API's own version.

Parameters

Name	In	Required	Description
`mapname`	path	yes	Map dataset name, e.g. carto, topo, routes, contours.

Response — 200

Field	Type	Required	Notes
`map_version`	string	no	Version identifier for the underlying map data build.
`map_date`	string	no	Date the map data itself was generated/extracted.
`release_date`	string	no	Date this build was published/released.

Status codes

200	Version metadata for the given map dataset.
404	Unknown mapname, or no version.json published for it.

Try it — builds a request, doesn't send one

Map name

Elevation

Look up elevation for a list of coordinates

POST /elevation?key=…

Authenticated elevation lookup. Requires an API key (query param) and, if the key is restricted to specific referers, a matching Referer header. Returns a ground elevation value for each coordinate in the request, in order.

Parameters

Name	In	Required	Description
`key`	query	yes	Tracestrack API key.
`Referer`	header	no	Must start with one of the key's allowed referers, if the key has any configured. Otherwise any (or no) referer is accepted.

Request body

Field	Type	Required	Notes
`lat`	number	yes	—
`lon`	number	yes	—

Response — 200

Field	Type	Required	Notes
`count`	integer	no	Number of coordinates successfully resolved.
`results`	object[]	no	Each input coordinate, augmented with an elevation `value` (meters, or null if unresolved).

Status codes

200	Elevation values for each input coordinate, in request order.
400	Request body is not an array of coordinates.
403	Key missing, invalid, blocked, or referer mismatch.
429	Rate limit exceeded for this key.
500	Elevation origin failed to process the request.

Try it — builds a request, doesn't send one

Coordinates (JSON array)

Elevation values for each input coordinate, in request order.

{
  "count": 2,
  "results": [
    {
      "lat": 42.7957187,
      "lon": 13.5690032,
      "value": 1247
    },
    {
      "lat": 37.7858845,
      "lon": -122.4133559,
      "value": 15
    }
  ]
}

Overpass

Query OpenStreetMap via Overpass QL

GET POST OPTIONS /overpass/{key}/interpreter

Proxies the request to the Overpass interpreter upstream, forwarding all query-string parameters as-is (typically just data). Authenticated via the key path parameter above (OpenAPI's apiKey security scheme doesn't support in: path, so it's documented as a plain path parameter instead of a security requirement).

overpass-turbo / JOSM

These tools append interpreter themselves, so the server URL you configure must stop one segment short of it. Set the Overpass API server field to:

https://tile.tracestrack.com/overpass/APIKEY/

not the full …/interpreter path — pointing either tool at the full URL (or at this proxy as a general OSM API server) will 404 on requests it makes to other paths, like /0.6/capabilities.

Parameters

Name	In	Required	Description
`key`	path	yes	Tracestrack API key, embedded in the path.
`data`	query	yes	Overpass QL (or XML) query.
`Referer`	header	no	—

Response — 200

Field	Type	Required	Notes
`version`	number	no	Overpass API protocol version.
`generator`	string	no	Overpass server build identifier.
`osm3s`	object	no	Query timestamp and data license/copyright.
`elements`	object[]	no	An OSM node/way/relation, shape depends on the query's `out` clause.

Status codes

200	Result from the Overpass interpreter. Content-Type mirrors the upstream response and depends on the query's `[out:...]` setting (json, xml, csv, ...).
204	No content. CORS headers only.
403	Key missing, invalid, blocked, or referer mismatch.
429	Rate limit exceeded for this key.

Try it — builds a request, doesn't send one

Method

Overpass QL

quick reference

Status codes at a glance

Status	Raster maps	Vector maps	Elevation	Overpass
200	The rendered tile image.	The vector tile.	Elevation values for each input coordinate, in request order.	Result from the Overpass interpreter. Content-Type mirrors the upstream response and depends on the query's `[out:...]` setting (json, xml, csv, ...).
204	—	—	—	No content. CORS headers only.
400	—	—	Request body is not an array of coordinates.	—
403	Key missing, invalid, blocked, or referer mismatch.	Key missing, invalid, blocked, or referer mismatch.	Key missing, invalid, blocked, or referer mismatch.	Key missing, invalid, blocked, or referer mismatch.
404	Tile coordinate out of range for this zoom level, or an unknown map name.	Tile not found. The origin's status is passed through verbatim, with an empty body.	—	—
429	Rate limit exceeded for this key.	Rate limit exceeded for this key.	Rate limit exceeded for this key.	Rate limit exceeded for this key.
500	—	Unrecognized `type`/`mapName` — a missing static object throws before any 404 can be returned, so an unhandled error becomes a generic 500 instead.	Elevation origin failed to process the request.	—
502	The tile origin failed to respond.	—	—	—