Developer

Tile

Service version: 2
Last edit: 2023.08.01

Public Preview Notice

This API is in Public Preview. Go to the Public Preview - what is it? page to see what this means.

We welcome your contribution to the development of this version. Please share your observations and suggestions on our forum or send an email to our software engineers.

We appreciate your feedback, and we will keep you posted on how it's used.

Purpose

Similar to the Map Display API Raster Tile service , the Map Display API Vector Tile service serves data on zoom levels ranging from 0 to 22.

  • For zoom level 0, the entire earth is displayed on a single tile.
  • At zoom level 22, the world is divided into 244 tiles. See: Zoom Levels and Tile Grid.

The Maps Vector Service delivers geographic map data packaged in a vector representation of squared sections called vector tiles.

  • Each tile includes pre-defined collections of map features (points, lines, road shapes, water polygons, building footprints, etc.) delivered in one of the specified vector formats.
  • The format of the tile is formally described using the protobuf schema.
  • The content of the tiles and meaning of each tile layer is described in the tile layers description.

Tiles Layers and Styles

The Vector Maps Service supports the following tile layers: basic, hybrid, labels, and poi. Unlike raster tiles there is no difference in data served between main and night styles. The vector data consists of layers with their own names and geometry. The client determines how to present this data to the end user, for example which colors to use for which features.

  • The basic vector tiles contain mapping data such as polygons, road shapes, borders, basic POIs, labels, and road icons.
  • The labels vector tiles provide the same label information as the basic vector tiles. The labels are precisely placed to align with the labels on the basic vector tiles.
  • The hybrid vector tiles provide all of the features from the basic layer except geographic polygons. It contains borders, road networks, labels, and road icons.
  • The poi vector tiles provide all of the Points of Interest features.

Tiles Resolution

Visible geometry is stored as coordinates in the range 0-4095. Coordinate 0,0 is defined as the top-left corner of the tile.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Request data

HTTPS method: GET

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets {} must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for these values. The generic URL format is as follows.

URL format

get
Request URL
https://{baseURL}/map/{versionNumber}/tile/{layer}/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}&view={view}&include={include_list}&travelMode={travelMode}&vehicleWeight={vehicleWeight}&vehicleAxleWeight={vehicleAxleWeight}&numberOfAxles={numberOfAxles}&vehicleLength={vehicleLength}&vehicleWidth={vehicleWidth}&vehicleHeight={vehicleHeight}&generalLoadType={generalLoadType}&dangerousGoodsLoadType={dangerousGoodsLoadType}&adrCategory={adrCategory}&travelModeProfile={travelModeProfile}&commercialVehicle={commercialVehicle}

curl command format

get
Request curl command
curl 'https://{baseURL}/map/{versionNumber}/tile/{layer}/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}&view={view}&include={include_list}&travelMode={travelMode}&vehicleWeight={vehicleWeight}&vehicleAxleWeight={vehicleAxleWeight}&numberOfAxles={numberOfAxles}&vehicleLength={vehicleLength}&vehicleWidth={vehicleWidth}&vehicleHeight={vehicleHeight}&generalLoadType={generalLoadType}&dangerousGoodsLoadType={dangerousGoodsLoadType}&adrCategory={adrCategory}&travelModeProfile={travelModeProfile}&commercialVehicle={commercialVehicle}&emissionClass={emissionClass}&engineType={engineType}'

Request parameters

The following elements are used in calls to generate all vector tile layers.

Required parameters

Description

baseURL


string

The base URL for calling TomTom services.


Values:

versionNumber


string

The version of the service to call.


Value: The current version is 2.

layer


string

Layer of the tile to be rendered.


Values:

  • basic

  • hybrid

  • labels

  • poi

zoom


integer

Zoom level of the tile to be rendered.


Value: 0..22

X


integer

The x coordinate of the tile on a zoom grid.


Value: 0..2 zoom -1

Y


integer

The y coordinate of the tile on a zoom grid.


Value: 0..2 zoom -1

format


string

The format of the Response.


Value: pbf

key


string

An API Key valid for the requested service.


Value: Your valid API Key.

Optional parameters

Description

view


string

A geopolitical view.


Default value: See the following Default view mapping section.
Other values:

  • Unified

  • IL

  • IN

  • MA

  • PK

  • AR

  • Arabic

  • RU

  • TR

  • CN

  • KR *

include
string

List of additional data types to be included in the tile. Values must be placed between [ and ] and separated by a ,.


Default value: None


Actual supported values:

  • road_restrictions - includes restriction-related data filtered based on the provided vehicle profile.

Example: include=[road_restrictions]

vehicleWeight
integer

Weight of the vehicle in kilograms.


Default value: 0

vehicleAxleWeight
integer

Weight per axle of the vehicle in kilograms.


Default value: 0

numberOfAxles
integer

Number of vehicle axles.


Default value: 0

vehicleLength
float

Length of the vehicle in meters.


Default value: 0

vehicleWidth
float

Width of the vehicle in meters.


Default value: 0

vehicleHeight
float

Height of the vehicle in meters.


Default value: 0

generalLoadType
string

List of the vehicle general load types. Values must be placed between [ and ] and separated by a ,.


Default value: None.


Actual supported values:
  • General_Hazardous_Materials
  • Explosive_Materials
  • Goods_Harmful_To_Water
dangerousGoodsLoadType
string

List of the vehicle dangerous goods load types. Values must be placed between [ and ] and separated by a ,.


Default value: None.


Actual supported values:
  • Explosives
  • Gases
  • Flammable_Liquids
  • Flammable_Solids
  • Oxidizing_And_Organic_Substance
  • Toxic_And_Infectious_Substance
  • Radioactive_Material
  • Corrosives
  • Miscellaneous_Dangerous_Goods
adrCategory
string

Vehicle ADR category.


Default value: None.


Actual supported values:
  • B
  • C
  • D
  • E
commercialVehicle
bool

Indicates a commercial vehicle.


Default value: false


Actual supported values:

  • false - Vehicle is not commercial.

  • true - Vehicle is commercial.

travelMode
string

Travel mode to be included in the restriction data.


Default value: If travelMode is not provided, the default value - Car - will be used.


Actual supported values:
  • Car
  • Truck
  • Taxi
  • Bus
  • Van
  • Motorcycle
  • Bicycle
  • Pedestrian
  • Other
emissionClass
string

List of the emission classes. Values must be placed between [ and ] and separated by a ,.


Default value: None.


Actual supported values:
  • EmissionClass0
  • EmissionClass1
  • EmissionClass2
  • EmissionClass3
  • EmissionClass4
  • EmissionClass5
  • EmissionClass6
  • EmissionClass7
  • EmissionClass8
  • EmissionClass9
  • EmissionClass10
engineType
string

List of the engine types Values must be placed between [ and ] and separated by a ,.


Default value: None.


Actual supported values:
  • LPG
  • CNG
  • LNG
  • Diesel
  • Petrol
  • Hydrogen
  • Electric
  • Hybrid
  • Plugin_Hybrid
travelModeProfile
string

The short version combines vehicle-related parameters with travelMode. Instead of passing all parameters separately, it can be provided in a single parameter.


travelModeProfile=<travelMode>,<vehicleWeight>,<vehicleAxleWeight>,<numberOfAxles>,<vehicleLength>,<vehicleWidth>,<vehicleHeight>,<generalLoadType>,<dangerousGoodsLoadType>,<adrCategory>,<commercialVehicle>,<emissionClass>,<engineType>

Parameter type

Description

travelMode
string

Travel mode to be included in the restriction data. See:

Travel mode mapping section

vehicleWeight
integer

Weight of the vehicle in kilograms.


Default value: 0

vehicleAxleWeight
integer

Weight per axle of the vehicle in kilograms.


Default value: 0

numberOfAxles
integer

Number of vehicle axles.


Default value: 0

vehicleLength
float

Length of the vehicle in meters.


Default value: 0

vehicleWidth
float

Width of the vehicle in meters.


Default value: 0

vehicleHeight
float

Height of the vehicle in meters.


Default value: 0

generalLoadType
string

List of vehicle general load types. Values must be placed between [ and ] and separated by a ,. See:

General load type mapping section

dangerousGoodsLoadType
string

List of vehicle dangerous goods load types. Values must be placed between [ and ] and separated by a ,. See:

Vehicle Dangerous goods load type mapping section

adrCategory
string

Vehicle ADR category See:

Vehicle ADR category type mapping section

commercialVehicle
string

Indicates a commercial vehicle.


Default value: 0.


Actual supported values:

  • 0 - Vehicle is not commercial.

  • 1 - Vehicle is commercial.

emissionClass
string

List of emission classes. Values must be placed between [ and ] and separated by a ,. See:

Emission class mapping section

engineType
string

List of engine types. Values must be placed between [ and ] and separated by a ,. See:

Engine type mapping section


Example:

Travel mode profile value

Description

0,1500,,,5.5,,2.2,,,,,,

Car, weight 1500kg, length 5.5m, height 2.2m.

1,,,3,,3.1,,,,,,,

Truck, 3 axles, width 3.1m.


HTTP request headers

The following table lists HTTP request headers of particular interest to clients of the Map Display API Vector Tile service endpoint. Note: There are no required headers in this endpoint.

Optional headers

Description

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.


Value: <string>

Default view mapping

Default view is recognized based on the country the request came from.

Country

Default view

Argentina

AR


Other available views: Arabic , CN , IN , IL , KR *, MA , PK , RU , TR , Unified

India

IN


Other available views: None

Morocco

MA


Other available views: Arabic , AR , CN , IN , IL , KR *, PK , RU , TR , Unified

Pakistan

PK


Other available views: Arabic , AR , CN , IN , IL , KR *, MA , RU , TR , Unified

Russia

RU


Other available views: Arabic , AR , CN , IN , IL , KR *, MA , PK , TR , Unified

Türkiye

TR


Other available views: Arabic , AR , CN , IN , IL , KR *, MA , PK , RU , Unified

China

CN


Other available views: Arabic , AR , IN , IL , MA , KR *, PK , RU , TR , Unified

Bahrain, Kuwait, Oman, Qatar,


Saudi Arabia, the United Arab Emirates

Arabic


Other available views: AR , CN , IN , IL , KR *, MA , PK , RU , TR , Unified

Others

Unified


Other available views: Arabic , AR , CN , IN , IL , KR *, MA , PK , RU , TR


Travel mode mapping

Travel mode values mapping

Value

Travel mode

0Car
1Truck
2Taxi
3Bus
4Van
5Motorcycle
6Bicycle
7Pedestrian
8Other

General load type mapping

General load type mapping

Value

General load type

0General_Hazardous_Materials
1Explosive_Materials
2Goods_Harmful_To_Water

Dangerous goods load type mapping

Dangerous goods load type mapping

Value

Dangerous goods load type

0Explosives
1Gases
2Flammable_Liquids
3Flammable_Solids
4Oxidizing_And_Organic_Substance
5Toxic_And_Infectious_Substance
6Radioactive_Material
7Corrosives
8Miscellaneous_Dangerous_Goods

Adr category type mapping

ADR category type mapping

Value

ADR category

BADR category B
CADR category C
DADR category D
EADR category E

Emission class mapping

Emission class mapping

Value

Emission class

0EmissionClass0
1EmissionClass1
2EmissionClass2
3EmissionClass3
4EmissionClass4
5EmissionClass5
6EmissionClass6
7EmissionClass7
8EmissionClass8
9EmissionClass9
10EmissionClass10

Engine type mapping

Engine type mapping

Value

Engine type

0LPG
1CNG
2LNG
3Diesel
4Petrol
5Hydrogen
6Electric
7Hybrid
8Plugin_Hybrid

Host Name Cycling

Most web browsers have a default limitation on the number of active connections that can be allowed to each host.

  • This means if map tiles are being loaded via the api.tomtom.com host name, they will be loaded one at a time.
  • A trick that can be used to get around this limitation is to cycle through the hosts we have created as aliases.
    • These host names are:
      • a.api.tomtom.com
      • b.api.tomtom.com
      • c.api.tomtom.com
      • d.api.tomtom.com
  • By cycling through these four different host names, the web browser will be tricked into retrieving four map tiles at a time rather than just one.
  • This will significantly speed up the performance of map rendering.

For instance, if four map tiles are being requested at zoom level one, you would request the first one as:

https://a.api.tomtom.com/map/2/tile/basic/1/0/0.pbf?key={Your_API_Key}

The second would be:

https://b.api.tomtom.com/map/2/tile/basic/1/0/0.pbf?key=Your_API_Key

and so on up until d.api.tomtom.com. When more than four tiles are being requested, start back again at a.api.tomtom.com.

Response data

The Map Display API Vector service endpoint, for a single request, returns a binary response body which must be deserialized by client code generated by the Google Protocol Buffers compiler. The following response examples use a simple textual representation of the serialized binary vector tile data to illustrate the response content.

Response examples

Example 1

Whole world at zoom = 0, basic layer.

RequestResponse

https://api.tomtom.com/map/2/tile/basic/0/0/0.pbf?key={Your_API_Key}

1layers:4
2water:
3  version: 2
4  extent: 4096
5  features: 1069
6  keys: 2
7  values: 3
8land_cover:
9  version: 2
10  extent: 4096
11  features: 2983
12  keys: 2
13  values: 6
14boundaries:
15  version: 2
16  extent: 4096
17  features: 4
18  keys: 4
19  values: 3
20carto_labels:
21  version: 2
22  extent: 4096
23  features: 5
24  keys: 4
25  values: 8

Example 2.

Zoom level = 5, hybrid layer

RequestResponse

https://api.tomtom.com/map/2/tile/hybrid/5/4/8.pbf?key={Your_API_Key}

1layers: 1
2boundaries:
3  version: 2
4  extent: 4096
5  features: 1
6  keys: 1
7  values: 1

Example 3.

Zoom level = 4, labels layer

RequestResponse

https://api.tomtom.com/map/2/tile/labels/4/9/5.pbf?key=Your_API_Key

1layers: 3
2boundaries:
3  version: 2
4  extent: 4096
5  features: 3
6  keys: 2
7  values: 3
8places:
9  version: 2
10  extent: 4096
11  features: 50
12  keys: 10
13  values: 110
14carto_labels:
15  version: 2
16  extent: 4096
17  features: 1
18  keys: 4
19  values: 4

Error Response

The Map Display API Vector service endpoint for an invalid request returns a response body in XML or JSON format. The XML format is returned by default. To have an error response returned in JSON format, application/json has to be specified in the Accept HTTP request header.

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

Error response example

JSON format
1{
2  "detailedError": {
3    "code": "BAD_REQUEST",
4    "message": "Invalid tile position arguments"
5  }
6}
XML format
1<errorResponse description="Invalid tile position arguments" errorCode="400" version="1.0.54-mascoma">
2  <detailedError>
3    <code>BAD_REQUEST</code>
4      <message>Invalid tile position arguments</message>
5  </detailedError>
6</errorResponse>

HTTP response codes

Code

Meaning & possible causes

200

OK

304

Not Modified : The tile has not been modified. This code is returned when the If-None-Match request header is used and its value matches the ETag of the requested tile.

400

Bad request : Probably malformed syntax.

  • The combination of layer and query parameters is not supported.

  • Zoom n is out of range 0 <= zoom <= 22: The requested zoom level is out of the possible range.

  • x n is out of range [0, m ]: The requested x coordinate is out of the possible range (the value of m will vary depending on the zoom level).

  • y n is out of range [0, m ]: The requested y coordinate is out of the possible range (the value of m will vary depending on the zoom level).

  • The requested view is not supported.

403

Forbidden :

  • The supplied API Key is not valid for this request.

  • The requested view is not available in the country from where the request was sent.

429

Too Many Requests : Too many requests were sent in a given amount of time for the supplied API Key.

500

Internal Server Error : There is a problem with the TomTom Maps Vector Tile service.

503

Service currently unavailable.

HTTP response headers

The following data table lists HTTP response headers of particular interest to clients of the Map Display API Vector Tile service.

Header

Description

Access-Control-Allow-Origin

The Map Display API Vector Tile service allows cross-origin resource sharing (CORS).


Value: * Universal.

Cache-Control

Contains directives for a caching mechanism.


Value: max-age=<decimal number>

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.


Value: <http-date>

ETag

Contains an identifier for a specific version of resource.


Value: W/"2fdbd61f30456"

Expires

Contains the date after which the response is considered outdated.


Value: <http-date>

Transfer-Encoding

Specifies the form of encoding used to safely transfer the response to the user. If this header is specified, the Content-Length header will be absent.


Value: chunked

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.
Value: <string>