Traffic Flow Tiles API

The Traffic Flow Tile API offers current traffic speed data for map display, allowing for either absolute or relative speed information. This includes current speed, free-flow speed, and a quality indicator. It can illustrate both real-time traffic speeds on road segments and the deviation from free-flow speeds on those same segments.

The service delivers traffic flow data in vector tiles, which are squared sections represented in a vector format.

  • Each tile includes a pre-defined collection of road shapes with traffic flow data.
  • The format of the tile is formally described using the protobuf schema.

The data is mapped to a protobuf layer called "Traffic flow". Besides the protobuf layers, the protobuf tags are also used to further describe the traffic. The protobuf tags are split into two categories: default and on-demand.

  1. The default tags are used unless they are filtered out by the tags request parameter.
  2. The on-demand tags are used only if they were added by the tags request parameter.
  3. Read more about these tags and valid values here.

Following is the endpoint to retrieve the traffic flow tile information:

GET

https://api.nextbillion.io/tt/traffic/map/{version_number}/tile/flow/{type}/{z}/{x}/{y}.{format}?key={Your_API_Key}

Path Parameters

NameRequiredFormat & UsageDescription
version_numberYesType: integer

Allowed Values: 4		Specify the version of the API service to be called. The current value is 4.
typeYesType: string

Allowed Values: absolute, relative, relative-delay

Type of traffic flow. It allows for following values:

  • absolute: this reflects the absolute speed.
  • relative: this is the speed relative to free-flow, highlighting areas of congestion.
  • relative-delay: this is the speed relative to free-flow (the same as relative), but it only shows areas of high congestion.
zYesType: integer

Minimum Value: 0 Maximum Value: 22		Zoom level of the tile to be rendered. The values should be in the range of [0,22].
xYesType: integer

Maximum Value: 2z-1		Specify the x-coordinate of the tile or the tile’s column on the zoom grid z. The maximum value should be less than 2z.
yYesType: integer

Maximum Value: 2z-1		Specify the y-coordinate of the tile or the tile’s row on the zoom grid z. The maximum value should be less than 2z.
formatYesType: string

Allowed Values: pbf		The format of the response.

Request Parameters

NameRequiredFormat & UsageDescription
keyYesType: string

Format: 32 character alphanumeric string Example: key=API_KEY		A key is a unique identifier that is required to authenticate a request to the API.
roadTypesNo

Type: string

Format: [roadTypes1, roadTypes2,....]


Allowed Values: [0,8]

  • 0: Motorway
  • 1: International road
  • 2: Major road
  • 3: Secondary road
  • 4: Connecting road
  • 5: Major local road
  • 6: Local road
  • 7: Minor local road
  • 8: Other roads (Non public road, Parking road, etc.)

The list of values representing the road types, which are going to be displayed on a particular zoom level according to the mapping:

Please note that:

  • The list of 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 road types displayed for a particular zoom level.
  • If the array of parameters is empty, an empty tile will be sent.
trafficLevelStepNoType: number

The step value, describing the minimum difference between values of the traffic_level protobuf tag. For example:

  • In the case of the relative traffic type, for trafficLevelStep to equal 0.1, the allowed values of traffic_level are: 0.0, 0.1, 0.2.. 1.0
  • In the case of the absolute traffic type, for trafficLevelStep to equal 10, the allowed values of traffic_level are: 0, 10, 20, etc.

Values:

  • for relative and relative-delay traffic types: 0.0 < trafficLevelStep < 1.0
  • for absolute traffic type: 0 < trafficLevelStep
marginNoType: number

Default value: 0.1 Allowed Values: [0.0, 0.1]		The size of the tile margin, relative to the tile size.
tagsYesType: array

Format: [tags_1, tags_2, …]

Allowed Values: road_type, traffic_level, traffic_road_coverage, left_hand_traffic, road_closure, road_category, road_subcategory		The list of the values representing the available tags in the tile. By default, only the default tags are attached to the tile geometry. See the Vector format for details. The parameter behaves as a filter by narrowing down the list of tags enclosed in each tile. It also allows a decrease in the size of the tile. If the array of parameters is empty, only the geometry will be sent.

Sample Request

1
curl --location --globoff 'https://api.nextbillion.io/tt/traffic/map/4/tile/flow/14/8186/5450.pbf?key=your_api_key&tags=[road_type]'

API Query Limits

  • NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests.
    Note: We can increase the quota if needed, on request. Contact support@nextbillion.ai for more details.

API Error Codes

Response codeDescriptionAdditional notes
200Normal success case.Normal success case.
400Input validation failed.There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.
401APIKEY not supplied or invalidThis error occurs when the wrong API key is passed in the request or the key is missing altogether.
403APIKEY is valid but does not have access to requested resourcesYou might be querying for a geographical region which is not valid for your account or requesting a service which is not enabled for you.
404Requested host/path not foundThis error occurs when a malformed hostname is used.
422Could not process the requestA feasible solution could not be generated for the given set of locations or parameter configuration.
429Too many requestsQPM reached or API request count quota reached.
500Internal Service error.There was an internal issue with NextBillion.ai services. You can reach out to support@nextbillion.ai for an explanation.