Vector Tiles v2

Important note
This API is not available as part of our free evaluation or Pay As You Grow (PAYG) offering. Click the Request Access button above to contact our Sales team.

Important notes:

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 “On-street parking”.
Besides the protobuf layers, the protobuf tags are also used to further describe the on-street parking.

On-street parking tags

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`
`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.

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

1
https://{baseURL}/maps/orbis/on-street-parking/vector/tile/{zoom}/{x}/{y}?apiVersion=2&key={Your_API_Key}

URL example

get

URL example

1
https://api.tomtom.com/maps/orbis/on-street-parking/vector/tile/5/4/8?apiVersion=2&key={Your_API_Key}

curl command example

get

curl command example

1
curl 'https://api.tomtom.com/maps/orbis/on-street-parking/vector/tile/5/4/8?apiVersion=2&key={Your_API_Key}'

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. Please note that using the `TomTom-Api-Key` header is recommended over `apiVersion` query parameters for improved security. 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`

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.
Please note that using the TomTom-Api-Key header is recommended over apiVersion query parameters for improved security.
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

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 `2`.

Request headers

The following data table lists HTTP request headers of particular interest to clients of the Parking Locations endpoint.

Required headers	Description
TomTom-Api-Key string	The authorization key for access to the API. Preferred method for authentication. Using the header is recommended over `apiVersion` query parameters for improved security. Value: Your valid `API Key`.
TomTom-Api-Version integer	Contains a version of the API to call. Value: The current version is `2`.

Optional headers	Description
Accept	Contains the acceptable media types that the client is able to understand. If the preferred media type is not supported, the server will fall back to the default one. Value: `application/vnd.mapbox-vector-tile`
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 following examples use a simple textual representation of the serialized binary vector tile data to illustrate the response content.

Response example

1
layer: 0
2
  name: On-street parking
3
  version: 2
4
  extent: 4096
5
  keys:
6
    0: probability
7
  values:
8
    0: 0.63 [double]
9
    1: 0.5
10
    2: 0.6
11
    3: 0.62
12
  feature: 0
13
    id: (none)
14
    geomtype: linestring
15
    geometry:
16
      LINESTRING[count=3](-292 1382,-286 1478,-278 1552)
17
    properties:
18
      probability=0.63 [double]
19
  feature: 1
20
    id: (none)
21
    geomtype: linestring
22
    geometry:
23
      LINESTRING[count=2](-312 1192,-320 1104)
24
    properties:
25
      probability=0.5 [double]
26
  feature: 2
27
    id: (none)
28
    geomtype: linestring
29
    geometry:
30
      LINESTRING[count=3](-320 1100,-330 1012,-334 954)
31
    properties:
32
      probability=0.6 [double]
33
  feature: 3
34
    id: (none)
35
    geomtype: linestring
36
    geometry:
37
      LINESTRING[count=2](-324 1060,-312 1178)
38
    properties:
39
      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": "Invalid path."
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: `application/vnd.mapbox-vector-tile`
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 v2

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`