Traffic Incident Tiles API

The Traffic Incident Tiles API offers real-time data on traffic incidents and delays for integration into web and map applications. It delivers comprehensive details, including start and end locations, road names, delay types, delay duration (in time), significance, and distance.

The service responds with traffic incidents data packaged in a vector representation of squared sections called vector tiles. These tiles include a pre-defined collection of road shapes with traffic incidents data. The format of a tile is formally described using the protobuf schema.

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

  1. The mandatory tags are included in every response, regardless of any other filtering criteria.
  2. The default tags are used unless they are filtered out by the tags request parameter (mandatory tags are automatically appended).
  3. The on-demand tags are used only if they were added by the tags request parameter (mandatory tags are automatically appended).
  4. Read more about these tags and valid values here.

Use the following endpoint for retrieving Traffic Vector Incident Tiles:

GET

https://api.nextbillion.io/orbis/traffic/tile/incidents/{z}/{x}/{y}.{format}?key={Your_API_Key}&apiVersion=1

Path Parameters

NameRequiredFormat & UsageDescription
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.
tNoType: string
Default Value: -1		Defines the state of traffic at a given time. Use -1 for the most recent traffic information. See this section and valid Traffic Model IDs for more information.
tagsNoType: array
Format: [tags_1, tags_2, …]
Default value: icon_category, left_hand_traffic, magnitude_of_delay, road_category, road_subcategory

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

  • icon_category (enables both icon_category and icon_category_[idx])
  • description (enables both description and description_[idx])
  • delay
  • road_type
  • left_hand_traffic
  • magnitude
  • traffic_road_coverage
  • clustered
  • probability_of_occurrence
  • number_of_reports
  • last_report_time
  • end_date
  • id
  • road_category
  • road_subcategory

By default, only the default tags are attached to the tile geometry. See 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.
  • Only tags that are used in both of the two protobuf layers can be used as a parameter value.
  • If the array of parameters is empty, only the tags unique for the particular layer are sent.
roadCategoryFilterNoType: string
Default Value: all road categories Allowed Values: motorway, motorway_link, trunk, trunk_link, primary, primary_link, secondary, secondary_link, tertiary, tertiary_link, street, service, track		This filter allows the choice of types of road categories to be included in the response. The filter narrows down the road categories available at particular zoom level. Multiple values are supported and should be separated by a comma.
categoryFilterNoType: string
Default Value: all incident types Allowed Values: 0: Unknown, 1: Accident, 2: Fog, 3: DangerousConditions, 4: Rain, 5: Ice, 6: Jam, 7: LaneClosed, 8: RoadClosed, 9: RoadWorks, 10: Wind, 11: Flooding, 14: BrokenDownVehicle		This filter allows the choice of types of incidents and future incidents to be included in the response. Filtering takes into account the main icon category of the incident. Both value types can be used: numeric and descriptive strings. Multiple values are supported and should be separated by a comma.
timeValidityFilterNoType: string
Default value: present Allowed values: present, future		This filter allows the choice of incidents based on their occurrence in time. Multiple values are supported and they should be separated by a comma.
languageNoType: string
Default value: en-GB Allowed values: List of supported languages.		The language code for the output language. Affects the description fields in the response. When an incident description does not have a translation, an English description is returned.
apiVersionNoType: integer
Allowed Values: 1		Specify the version of the API service to be called. The current value is 1.

Sample Request

1
curl --location 'https://api.nextbillion.io/orbis/traffic/tile/incidents/12/2929/1898.pbf?key=<your_api_key>&apiVersion=1'

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.