Vector Tiles

Service version: 1

Last edit: 2024.04.26

Automotive only

TomTom Orbis Maps

Important note
This API is unavailable on a Freemium or Pay As You Grow (PAYG) basis.
Click the Request Access button above to contact our Sales team.

Important notes:

This TomTom Orbis API is in public preview.

This API is powered by the TomTom Orbis Maps.

See the TomTom Orbis Maps documentation for more information.

Purpose

The Vector Tiles endpoint provides information about the probability of finding available on-street parking locations, together with their geometry. It also provides data on zoom levels ranging from 0 to 22.

For zoom level 0, the world is displayed on a single tile.
At zoom level 22, the world is divided into 2⁴⁴ tiles. See the Zoom Levels and Tile Grid.

The Vector Tiles endpoint delivers on-street parking data packaged in a vector representation of squared sections called vector tiles. Each tile includes a pre-defined collection of fragments of road shapes with on-street parking data (parking locations). The format of the tile is formally described using the protobuf schema.

Tiles resolution

On-street parking geometry is stored as coordinates in the range of 0-4095. Coordinates (0,0) define the top-left corner of the tile.

Vector format

The Vector format is a binary format created by using Google Protocol Buffers to serialize the data according to this defined vector schema.

The data is mapped to a protobuf layer called &quotOn-street parking".
Besides the protobuf layers, the protobuf tags are also used to further describe the on-street parking.
The protobuf tags are split into two categories: default and on-demand.
- The default tags are used unless they are filtered out by the tags request parameter.
- The on-demand tags are used only if they were added by the tags request parameter.

On-street parking tags

Default tags	Description
`probability` float	It is a probability of finding an available on-street parking location. If the probability is missing in a particular parking location, it means that we have the geometry of this parking location, but currently we don't have any probability associated with it. Values: `0.0..1.0`

Default tags

Description

probability

float

It is a probability of finding an available on-street parking location. If the probability is missing in a particular parking location, it means that we have the geometry of this parking location, but currently we don't have any probability associated with it.

Values: 0.0..1.0

On-demand tags	Description
`id` string	This is a parking location ID, coming directly from our parking data provider, and is used to combine data from different sources. Value: A parking location ID.
`park_and_ride` boolean	Indicates if it is a parking location with public transport connections that allows people to leave their vehicles and transfer to a means of public transport for the remainder of the journey. Value: `true` or `false`.

On-demand tags

Description

id

string

This is a parking location ID, coming directly from our parking data provider, and is used to combine data from different sources.

Value: A parking location ID.

park_and_ride

boolean

Indicates if it is a parking location with public transport connections that allows people to leave their vehicles and transfer to a means of public transport for the remainder of the journey.

Value: true or false.

Request data

HTTPS Method: `GET`

Constants and parameters enclosed in curly brackets {} must be replaced with their values.
See the following Request parameters section with the required and optional parameters tables for these values.

URL format

get

URL format

https://{baseURL}/maps/orbis/on-street-parking/tile/{zoom}/{x}/{y}.{format}?apiVersion=1&key={Your_API_Key}&tags={tags[]}

URL example

get

URL example

https://api.tomtom.com/maps/orbis/on-street-parking/tile/5/4/8.pbf?apiVersion=1&key={Your_API_Key}&tags=[id,probability]

curl command example

get

curl command example

curl 'https://api.tomtom.com/maps/orbis/on-street-parking/1/tile/5/4/8.pbf?apiVersion=1&key={Your_API_Key}&tags=[id,probability]'

Request parameters

The following table describes the parameters that can be used in a request.

Required parameters must be used or the call will fail.
Parameters and values are case-sensitive.
Optional parameters may be used.

Required parameters	Description
`baseURL` string	Base URL for calling the API. Value: api.tomtom.com
`key` string	The authorization key for access to the API. Value: Your valid `API Key`.
`zoom` integer	The zoom level of a tile to be rendered. The actual data is going to appear starting from the `15` zoom level. Below that value, empty tiles are sent. Value: `0`.. `22`
`x` integer	The x coordinate of a tile on the zoom grid. Value: `0..2 zoom -1`
`y` integer	The y coordinate of a tile on the zoom grid. Value: `0..2 zoom -1`
`format` string	The format of the response. Value: pbf ( Protocolbuffer Binary Format )

Required parameters

Description

baseURL

string

Base URL for calling the API.

Value: api.tomtom.com

key

string

The authorization key for access to the API.

Value: Your valid API Key.

zoom

integer

The zoom level of a tile to be rendered.

The actual data is going to appear starting from the 15 zoom level. Below that value, empty tiles are sent.

Value: 0.. 22

x

integer

The x coordinate of a tile on the zoom grid.

Value: 0..2 zoom -1

y

integer

The y coordinate of a tile on the zoom grid.

Value: 0..2 zoom -1

format

string

The format of the response.

Value: pbf ( Protocolbuffer Binary Format )

Optional parameters	Description
`apiVersion` integer	A version of the API to call. If the parameter is set, it will overwrite the value stored in TomTom-Api-Version header. Value: The current version is `1`.
`tags` array	The list of the values representing the available tags in the tile: `probability` `id` `park_and_ride` If this parameter is not present default tags are used. See the Vector format for details. The list of the values must be enclosed in square brackets `[ ]` , and each value must be separated by a comma. The parameter behaves as a filter, narrowing down the list of tags enclosed in each tile, which allows a decrease in the size of the tile. If the array of parameters is empty, only geometry is sent. Value: Square brackets enclosed list.

Optional parameters

Description

apiVersion integer

A version of the API to call. If the parameter is set, it will overwrite the value stored in TomTom-Api-Version header. Value: The current version is 1.

tags

array

The list of the values representing the available tags in the tile:

probability
id
park_and_ride

If this parameter is not present default tags are used. See the Vector format for details. The list of the values must be enclosed in square brackets [ ] , and each value must be separated by a comma. The parameter behaves as a filter, narrowing down the list of tags enclosed in each tile, which allows a decrease in the size of the tile. If the array of parameters is empty, only geometry is sent.

Value: Square brackets enclosed list.

Request headers

The following data table lists HTTP request headers of particular interest to clients of the Parking Locations endpoint. Note: There are no required headers in this endpoint.

Optional headers	Description
TomTom-Api-Version integer	Contains a version of the API to call. Value: The current version is `1`.
Accept-Encoding	Contains the content encoding (usually a compression algorithm), that the client is able to understand. Value: `gzip`
If-None-Match	Contains an identifier for a specific version of resource. The server will send back the requested resource, with a 200 HTTP status code, only if it doesn't have an ETag matching the given one. Value: `<string>`
Tracking-ID	Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression `'^[a-zA-Z0-9-]{1,100}$'`.An example of the format that matches this regular expression is a UUID (e.g., `9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1` ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: `<string>`

Response data

Successful response

The Vector Tiles endpoint, for a valid single request, returns a binary response body which must be deserialized by client code generated by the Google Protocol Buffers compiler.
The data that appear in a response depend on a value of the {tags} request parameter.

The following examples use a simple textual representation of the serialized binary vector tile data to illustrate the response content.

Response example

Response example
1layer: 0
name: On-street parking
version: 2
extent: 4096
keys:
  0: probability
values:
  0: 0.63 [double]
  1: 0.5
  2: 0.6
  3: 0.62
feature: 0
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=3](-292 1382,-286 1478,-278 1552)
  properties:
    probability=0.63 [double]
feature: 1
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=2](-312 1192,-320 1104)
  properties:
    probability=0.5 [double]
feature: 2
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=3](-320 1100,-330 1012,-334 954)
  properties:
    probability=0.6 [double]
feature: 3
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=2](-324 1060,-312 1178)
  properties:
    probability=0.62 [double]

Error response

The Vector Tiles endpoint, for an invalid single request, returns a response body in JSON format.

Response field structure

Field	Description
`detailedError` object	Main `object` of the error response.
`code` string	One of a server-defined set of error codes.
`message` string	A human-readable description of the error code.

Field

Description

detailedError

object

Main object of the error response.

code

string

One of a server-defined set of error codes.

message

string

A human-readable description of the error code.

Response example

Error response example - JSON
1{
2  "detailedError": {
3    "code": "INVALID_REQUEST",
4    "message": "Unsupported tile format. Allowed format is pbf."
5  }
6}

HTTP response codes

Code	Meaning & possible causes
`200`	OK
`304`	Not modified
`400`	Bad request
`403`	Forbidden: The supplied API Key is not valid for this request.
`405`	Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.
`429`	Too Many requests: Too many requests were sent in a given amount of time for the supplied API Key.
`500`	Internal Server Error
`503`	Service currently unavailable: The service is currently unavailable.
`596`	Service Not Found: Unknown version of the service.

HTTP response headers

The following data table contains response headers sent back from an API server.

Header	Description
Access-Control-Allow-Origin	Indicates that cross-origin resource sharing (CORS) is allowed. Value: `*`
Allow	Lists the set of supported HTTP methods. The header is sent in case a `405` HTTP response code is returned. Value: `GET, HEAD`
Content-Encoding	Indicates which encodings were applied to the response body. Value: `gzip`
Content-Length	Contains information about the size of the response body. Value: `<decimal number>`
Content-Type	Indicates the media type of the resource returned. Value: `image/pbf`
Date	Contains the date and time at which the message was originated. For details check RFC 7231. Value: `<http-date>`
ETag	Contains an identifier for a specific version of resource. Value: `W/"2fdbd61f30456"`
Tracking-ID	An identifier for the request. If the Tracking-ID header was specified in the request, it is replicated in the response. Otherwise, it is generated automatically by the service. For details check RFC 4122. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: `<string>`

Vector Tiles

Important note

Important notes:

Purpose

Tiles resolution

Vector format

On-street parking tags

Request data

HTTPS Method: GET

URL format

URL example

curl command example

Request parameters

Request headers

Response data

Successful response

Response example

Error response

Response field structure

Response example

HTTP response codes

HTTP response headers

HTTPS Method: `GET`