Parking API

Vector Tile Structure

Request access

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

Vector Tiles are served in binary format, which uses Google Protocol Buffers as the method of serializing structured data. The serializing algorithm is very effective and as a result Vector Tiles are light-weight.

Vector Tile structure

Vector Tile diagram

The following diagram shows dependencies between the properties of vector tile.

vector tile property dependencies

Legend

Tile

Represents a vector tile as a whole entity. It consists of at least one TileLayer. If the tile does not contain any relevant data, it contains one layer named empty. Tiles below zoom level 15 are always empty.


TileLayer

Part of a Tile, representing one of the layers that can be rendered later. In the On-Street Parking API, a tile has one layer, named On-street parking, which holds all of the on-street parking locations in the tile.

Every TileLayer contains the following fields:

  • name

  • version

  • extent

It may also contain the following fields:

  • keys are an array of unique strings.

  • values are an array of unique TileValues.

  • features are an array of unique TileFeatures.

Arrays of keys and values contain the mapping for tags of TileFeature.


TileFeature

Member of an array of features stored in a TileLayer, containing a geometry representation that can be rendered.
It always contains the following fields:

  • type is a type of geometry. It can be point, linestring, or polygon. In the On-Street Parking API, it is always linestring.

  • geometry is an array of encoded geometry that can be used for rendering. See the Decoding tile geometry section for details.

It may also contain the following fields:

  • tags are an array containing properties of feature.

    • They are a TileFeature's detailed description which can be used for styling and later rendering the geometry.

    • They are encoded into an array of integers.
    • In order to decode them, the arrays of keys and values, from corresponding TileLayer must be used.

    • See the Decoding tile tags section for details.

    • The available tags (id, probability) are described on the Vector Tiles (v1) and Vector Tiles v2 pages.


TileValue

Encoded representation of a string, integer, floating point, or boolean value.

  • It is stored in a values array, in a TileLayer.

  • It is used for decoding tags of a TileFeature
    (together with the members of a keys array).

  • See the Decoding tile tags section for details.

Schema data

Formally, the structure of Vector Tile is described by the protocol buffer schema. It allows the generation of C++, Java, Python, Go, Ruby, Objective-C, and C# code based on proto file.

Schema proto file
package vector_tile
option optimize_for = SPEED;
message Tile {
enum GeomType {
UNKNOWN = 0;
POINT = 1;
LINESTRING = 2;
POLYGON = 3;
}
message Value {
optional string string_value = 1;
optional float float_value = 2;
optional double double_value = 3;
optional int64 int_value = 4;
optional uint64 uint_value = 5;
optional sint64 sint_value = 6;
optional bool bool_value = 7;
extensions 8 to max;
}
message Feature {
optional uint64 id = 1 [ default = 0 ];
repeated uint32 tags = 2 [ packed = true ];
optional GeomType type = 3 [ default = UNKNOWN ];
repeated uint32 geometry = 4 [ packed = true ];
optional bytes raster = 5;
}
message Layer {
required uint32 version = 15 [ default = 1 ];
required string name = 1;
repeated Feature features = 2;
repeated string keys = 3;
repeated Value values = 4;
optional uint32 extent = 5 [ default = 4096 ];
extensions 16 to max;
}
repeated Layer layers = 3;
extensions 16 to 8191;
}

Decoding Vector Tile

Decoding tile geometry

Vector Tile geometry uses the following coordinate system:

  • Coordinates are always integers.
  • The (0,0)point is located in the upper-left corner of the tile.
  • The X axis has positive values to the right of the tile.
  • The Y axis has positive values to the bottom of the tile.
  • The tile has a margin, which is a buffer around the tile in the shape of a square frame.
  • The extent is equal to 4096, so the value range for X and Y coordinates is from 0 to 4095.
  • Because of the margin, the coordinate values range is additionally extended in both directions. This may cause coordinate values for points in the left or upper margin to be negative, or values for points in the right or lower margin to be greater than 4095.

Vector Tile geometry is encoded as an array of 32 bit unsigned integers in the geometry field, belonging to the TileFeature.

Encoded format has the following structure:

[command_and_count][x0][y0]..[xn][yn][command_and_count][x0][y0]..
  • command_and_count contains encoded values of command and count.
  • [x0][y0]..[xn][yn] are encoded coordinate (x,y) pairs.

Command

The value of command is decoded as follows:

command = command_and_count & 0x7
  • It can be interpreted as “paint brush movement” during rendering, in relation to point (0.0) and previous commands.
  • In the first TileFeature command “paint brush” starts at point (0,0).

Command types

CommandValueCoordinatesDescription

MoveTo

1

x,y

  • It defines the (x,y) coordinate.

    • In the case of a point type geometry, the coordinate is a new point.

    • In the case of a linestring type geometry, the coordinate is the start vertex of a new line.

    • In the case of a polygon type geometry, the coordinate is the start vertex of new linear ring.

  • It moves “paint brush” to a newly defined coordinate.

LineTo

2

x,y

  • It defines a segment, starting at the current position of the cursor and ending at (x,y) coordinate.

    • In the case of a linestring type geometry, the segment extends the current line.

    • In the case of a polygon type geometry, the segment extends the current linear ring.

  • It moves “paint brush” to a newly defined coordinate.

ClosePath

7

none
  • It closes the current linear ring of a polygon type geometry.

  • It starts and ends at the start vertex of a current linear ring.

  • It does not move “paint brush” to any coordinate, because it has none.

Count

The value of count is decoded as follows:

count = command_and_count >> 0x3
  • It defines the n number of [xn][yn] encoded coordinate pairs following the command_and_count value.
  • These coordinate pairs must be interpreted according to the preceding command type.

Coordinates

Coordinates [x0][y0]..[xn][yn] are encoded in zigzag encoding and are relative to the previous coordinate pair and previous commands. This means that only the first coordinate pair [x0][y0] in first command in every TileFeature stores absolute values.

The coordinates are decoded as follows:

Decoded coordinates values
decode(x0) = ((x0 >> 0x1) ^ (-(x0 & 0x1)))
decode(y0) = ((y0 >> 0x1) ^ (-(y0 & 0x1)))
decode(x1) = decode(x0) + ((x1 >> 0x1) ^ (-(x1 & 0x1)))
decode(y1) = decode(y0) + ((y1 >> 0x1) ^ (-(y1 & 0x1)))
...
decode(xn) = decode(xn-1) + ((xn >> 0x1) ^ (-(xn & 0x1)))
decode(yn) = decode(yn-1) + ((yn >> 0x1) ^ (-(yn & 0x1)))
Example of decoded coordinates
input :
layer : 0 :
feature : 0 :
type : LINESTRING
geometry : [9, 604, 2120, 10, 131, 8]
processing :
geometry :
command_and_count = 9
command = 9 & 0x7 = 1 (MoveTo)
count = 9 >> 0x3 = 1
x0 = 604, y0 = 2120
decode(x0) = ((604 >> 0x1) ^ (-(604 & 0x1))) = 302
decode(y0) = ((2120 >> 0x1) ^ (-(2120 & 0x1))) = 1060
command_and_count = 10
command = 10 & 0x7 = 2 (LineTo)
count = 10 >> 0x3 = 1
x1 = 131, y1 = 8
decode(x1) = 302 + ((131 >> 0x1) ^ (-(131 & 0x1))) = 302 + (-66) = 236
decode(y1) = 1060 + ((8 >> 0x1) ^ (-(8 & 0x1))) = 1060 + 4 = 1064
output :
layer : 0 :
feature : 0
geometry : LINESTRING(302 1060, 236 1064)

Decoding tile tags

In order to reduce tile size, the properties of each feature are encoded in a tags array.

  • The tags array contains integer values which are indexes of keys and values arrays belonging to the corresponding layer.
  • The size of a tags array is always even.
  • The content of a tags array can be grouped into a list of pairs. Each odd element of an array is the first element of a pair, and each even element of an array is the second element of a pair.
  • The first element of each pair should be mapped to a keys array.
  • The second element of each pair should be mapped to a values array.
  • As a result, we get a decoded list of tags where the first element is the tag name and the second element is the tag value in the form of TileValue.
Example
input :
layer : 0 :
"keys" : ["id", "probability"],
"values" : ["00d7835e-06df-3579-a0eb-6660ba3138f3", 0.99, "00d7b990-1219-3ac2-8c66-ceb8eb6162ba"]
feature : 0 :
"tags" : [1,1,0,2]
output :
layer : 0 :
feature : 0 :
properties :
"probability" : 0.99
"id" : "00d7b990-1219-3ac2-8c66-ceb8eb6162ba"