API reference - Tiles

Just need a link? For the XYZ / slippymap URL format use

https://api.gpxz.io/v1/elevation/tile/{z}/{x}/{y}.png?api_key=XXX

and for TileJSON use

https://api.gpxz.io/v1/elevation/tiles.json?api_key=XXX

The GPXZ tiles API returns RGB-encoded terrain tiles. Client software can use these tiles to provide hillshading, contours, and heatmaps.

The /v1/elevation/tile endpoint returns individual tiles.

There's also a TileJSON endpoint at /v1/elevation/tiles.json.

Authenticating map tiles

An API key is required to access GPXZ terrain tiles. Because map tiles are often used in web or mobile applications, where it's possible to extract the API key, we strongly recommend restricting your API keys.

A good first step is to make a new API key just for map use, with only the TILES scope. More options for limiting API keys can be found in Securing GPXZ API keys in webapps.

/v1/elevation/tile/{z}/{x}/{y}{ratio}.{extension}

A map tile at the specified x,y coordinates and zoom level.

Typically, you would provide this as a full url with your API key, like

https://api.gpxz.io/v1/elevation/tile/{z}/{x}/{y}.png?api_key=XXX

Tiles are 512 px by 512 px by default. You can get 256 px tiles with tile_size=256 for compatibility, but you'll use 4x the number of requests to cover the same area. You can get 1024 px tiles with tile_size=1024, but you can't combine this with @2x.

Use a @2x suffix to get a double-resolution tile for more detailed on high-DPI devices (which are very common these days!). Some mapping engines support this with a {r} or {ratio} url placeholder tag. Note however that GPXZ only supports @2x, not @3x or fractional ratios.

To add a 1px overread buffer to tiles, add buffer_px=1. Unlike the @2x or tile_size options, this will actually increase the extent of each tile, resulting in a 1 px overlap between tiles. Some map software is able to use this buffer to reduce seams between tiles.

Example HTTP request

GET https://api.gpxz.io/v1/elevation/tile/9/274/[email protected]

URL parameters

Request query parameters

Response

An image.

• The mimetype will be image/png or image/webp.
• For a non-200 status code, a standard json error message will be provided with mimetype application/json.
• Response headers
  • x-data-sources: a comma-separated list of source IDs used to build this raster. You can use these IDs to lookup more details with the /v1/elevation/sources endpoint.
  • The capture date range is returned as x-capture-date-min and x-capture-date-max headers, in ISO 8601 format (like "2020-01-30"). The minimum date may also be the string none if unknown.

/v1/elevation/tile.json

Get a TileJSON file containing the metadata of the GPXZ tile terrain endpoint.

Some mapping clients support TileJSON as an alternative to manually configuring the client with the parameters of each tile server.

All the same query parameters as the tile endpoint are supported.

Because of inconsistent {ratio} support accross mapping clients, the ratio placeholder isn't inlcuded in the TileJSON file. To get high-DPI @2x tiles you'll need to use the /v1/elevation/tile/ endpoint directly, or request a larger tile size directly.

The TileJSON file will contain your API key, which is needed to access the terrain tiles endpoint. Even if you autheniticate to this /v1/elevation/tile.json endpoint with an HTTP header, your key will be included as a query parameter in the endpoint URL in the TileJSON response. To avoid misuse of credentials, ensure your key has restricted permissions.

Example HTTP request

GET https://api.gpxz.io/v1/elevation/tiles.json

Request query parameters