getSpatialExtent

Last edit: 2026.11.04

Returns the spatial extent of the service: the area its tiles cover. Use it to check whether a service covers the area your map data component needs before you request tiles.

Request data

HTTP method: `POST`

URL request format

1
https://{serviceURL}/getSpatialExtent?apiKey={Your_API_Key}

serviceURL is your Smart Layer Tile Service endpoint, without /openapi.json.
Your_API_Key is a My.TomTom API key with NDS.Live services enabled.

Request body

This method takes no request body.

HTTP request headers

Header	Description
`If-None-Match`	Optional. The entity tag for conditional requests.

Conditional requests

To send a conditional request:

Store the entity tag from the ETag response header, quotation marks included.
On the next request for the same resource, send it in If-None-Match.
If nothing changed, the service returns 304 with an empty body, and you keep using your cached copy. For a method that redirects to a file, the service answers 304 itself, without redirecting.

Send the entity tag in If-None-Match, not in an ETag request header. The ETag request header is deprecated.

Response data

Response body

TomTom’s Smart Layer Tile Service redirects the request to a file on a TomTom content delivery network, which holds the spatial extent. Make sure your HTTP client follows redirects. Most clients do this by default. The Location URL carries a short-lived access token, so don’t cache it or write it to logs.

The file is a zserio-encoded SpatialExtentList object. Its extents list holds one or more SpatialExtent objects, which don’t overlap:

Field	Description
`boundingBox`	A rectangle that roughly describes the area, given by its `southWestPosition` and `northEastPosition`.
`boundingPolygon`	Optional. A polygon that describes the area in more detail. It lies inside the bounding box.

Each position has a longitude and a latitude in NDS coordinates: WGS 84 degrees, stored as 32-bit integers in which the full range covers 360 degrees. To convert a value to degrees, multiply it by 360 / 2³².

For example, the ADAS Road Model evaluation service returns one bounding box, without a polygon, from latitude −55.15° to 82.55° and longitude −180° to 180°.

HTTP response headers

Header	Description
`Location`	The URL of the file that holds the spatial extent.
`ETag`	The entity tag of the spatial extent, for conditional requests. If you send it in `If-None-Match` and the spatial extent hasn’t changed, the service answers `304` without redirecting.

HTTP status codes

Besides the codes below, any method can return the common errors, for example 401 for a missing API key.

Code	Meaning
`200`	OK. The response body holds the `SpatialExtentList`.
`303`	See other. The spatial extent is at the URL in the `Location` response header.
`304`	Not modified since the version identified in `If-None-Match`.
`404`	Not found.
`410`	Gone. The Smart Layer Tile Service is decommissioned. Ask the NDS.Live Registry for another service.
`500`	Internal server error.