Layers overview

The data in the HERE Traffic Vector Tile API is organized in layers according to the definitions specified by the Tilezen open-source project started by Mapzen.

The sections below include all the information necessary to understand the traffic layers structure.

The HERE Traffic Vector Tile API uses the same structure as the original layer definition to make it easier to find the changes, and follows the same SEMANTIC VERSIONING statement as originally formulated by Tilezen.

Overview

Data sources and attribution

The HERE Traffic Vector Tile API uses data from HERE. For more information, see Required Copyright Notice.

Source property usage in tiles

The property source is generally omitted in all tiles. Assume that the value is here.com unless stated otherwise.

However, for some regions of the world within the core layer parameter (for example, Japan), this property is present, and the property value indicates the data source provider. In case of Japan, the value is ipc.

Definition of terms

• common - These layers, properties, and kinds are generally available across all features in a response.
  • Establishes basic selection of features and their arrangement into specific named layers.
  • Core properties needed for display and labeling of features:
    • Special bits that make traffic vector tile content interoperable, including kind, kind_detail, landuse_kind, min_zoom, and sort_rank.
    • Fundamental properties like name (including localized names) that are included in almost every feature.
• common-optional - These are meant to be part of a common set but may not be present because they aren't relevant or because we don't have the data (primarily feature properties, but could also be layers).
  • Used to refine feature selection.
  • Lightly transformed interoperable properties based on original data values.
  • Fundamental properties like sort_rank.
• optional - These are properties of a specific, less important kind, or generally present across kinds, but only in exceptional cases.
  • Often used to "decorate" features already selected for display.

Feature names

Most features in a traffic vector tile include a basic name property in the common list of properties, such as:

• name - Generally the name the locals call the feature, in the local language script.

Geometry types

A traffic tile geometry can be one of two types:

• point - point, multipoint
• line - linestring, multilinestring

Data updates

Due to the highly dynamic nature of traffic data, traffic tiles should be updated around every minute.

Changelog

The current version of the HERE traffic vector tile layer definition is v1.0.0.

Data model promises are listed in the SEMANTIC VERSIONING statement.

Read the full details in the changes section.

Feature ordering

The ordering of features, which determines which features are rendered "on top of" other features, can be an important issue when rendering maps. To assist map rendering, there is a sort_rank property on some features that suggests in what order the features should appear. Lower numbers indicate that features should appear "towards the back" and higher numbers indicate "towards the front". These numbers are consistent across traffic layers.

Road properties (common-optional)

The following common properties are used to define additional information about a road in traffic tile features.

Road transportation kind values

• aerialway
• ferry
• hgv_restriction
• highway
• major_road
• minor_road
• path
• rail
• piste

Road transportation kinddetail values

• ferry - for ferry kind
• motorway - for highway kind
• trunk - for highway kind
• primary - for major_road kind
• secondary - for major_road kind
• tertiary - for major_road kind
• residential - for minor_road kind
• service - for minor_road kind
• unclassified - for minor_road kind
• pedestrian - for path kind
• footway - for path kind
• rail - for rail kind
• chair_lift - for aerialway kind
• downhill - for piste kind

Traffic layers

The HERE Traffic Vector Tile API includes following layers:

• traffic_flow
• traffic_incidents
• incident_icons

Due to the highly dynamic nature of traffic data, these layers should be updated around every minute.

The following figure illustrates an example of rendered all traffic layers (traffic_flow, traffic_incidents, incident_icons).

Traffic flow

The following figure illustrates an example of traffic flow rendered from the data.

The layer content is defined as follows.

• Layer name: traffic_flow
• Geometry types: line

Traffic flow properties (common)

• id - A unique traffic event ID. Can be referenced when checking for updated traffic information for the specified event.
• kind - The severity of the flow information as seen by the traffic provider to indicate the traffic "color". For possible values, see below.
• min_zoom - A float value as a suggestion which zoom you use when drawing a feature. The value is derived from a combination of the road_kind, kind, and kind_detail values described below.

Traffic flow kind values

• unknown - traffic status unknown
• free - free flowing, not disturbed, traffic
• minor - minor traffic delays
• slow - slowly moving traffic
• queuing - the traffic is congested but still moves slowly
• stationary - stationary traffic, congestion
• none - no traffic flow due to blockage or closure

Traffic flow properties (common-optional)

• source - The provider of traffic information.
• congestion - The level of traffic flow, where 0.0 represents completely free-flowing traffic, and 1.0 - completely congested traffic.
• speed - Speed in km/h.
• drives_on_left - Set to true when the country drives on the left (for example, in the United Kingdom).
• sort_rank - This property contains a suggestion in which order to render flow features. The value is an integer where smaller numbers suggest that features should be "behind" features with larger numbers.

Traffic flow properties (optional)

• road_kind - See the road kind values above.
• road_kind_detail - See the road kind_detail values above.
• is_bridge - Set to true when the linear is a bridge.
• is_tunnel - Set to true when the linear is a tunnel.
• is_link - Set to true when the linear is a slip-road.
• is_hov_lane - Set to true when the linear is an HOV (High-Occupancy Vechicle) express lane.

Traffic incidents

The following figure illustrates an example of traffic incidents rendered from the data.

The layer content is defined as follows.

• Layer name: traffic_incidents
• Geometry types: line

Traffic incident properties (common)

• id - A unique traffic event ID. Can be referenced when checking for updated traffic information for the specified event.
• kind - A type of the incident. For possible values, see below.
• min_zoom - A float value as a suggestion which zoom you use when drawing a feature. The value is derived from the warning_level value described below.

Traffic incident kind values

• accident - there has been a collision
• congestion - there has been a build up of vehicles
• construction - building or roadworks are taking place
• disabled_vehicle - a vehicle is unable to move and is obstructing the road
• lane_restriction - lane(s) have been closed
• mass_transit - a large number of people are migrating from one location to another
• planned_event - an organised event is taking place, causing disruption
• road_closure - road is closed due to traffic incident, roadworks or public event
• road_hazard - there are dangerous objects on the surface of the road
• weather - weather conditions are causing disruptions
• other - an incident not explainable with the labels above has occurred

Traffic incident properties (common-optional)

• source - The provider of traffic information.
• sort_rank - This property contains a suggestion in which order to draw flow features (for traffic incident line geometries only). The value is an integer where smaller numbers suggest that features should be "behind" features with larger numbers.
• start_time - The time the incident begins/has begun as unix time. At least one of the start_time or stop_time must be set.
• stop_time - The time the incident ends/has ended as unix time. At least one of the start_time or stop_time must be set.
• title - A short description of the incident, localized, such as title:en for English and title:de for German. Could be used for a title of a pop-up shown in the screen.
• description - A potentially long description and comment on the incident. Localized, like title described above.

Traffic incident properties (optional)

• warning_level - The severity of the incident that has occured, with the following possible values: low (least severe), minor, major, and critical (most severe).
• road_kind - See the road kind values above.
• road_kind_detail - See the road kind_detail values above.
• is_bridge - Set to true when the linear is a bridge.
• is_tunnel - Set to true when the linear is a tunnel.
• is_link - Set to true when the linear is a slip-road.
• drives_on_left - Set to true when the country drives on the left (for example, in the United Kingdom).
• is_hov_lane - Set to true when the linear is, or the incident affects, a HOV (High-Occupancy Vechicle) express lane.

Incident icons

The following figure illustrates an example of rendered traffic incident icons from the data.

• Layer name: incident_icons.
• Geometry types: point.

This layer defines information about icons for incidents. It uses the same structure as the traffic_incidents layer. All properties from Traffic Incidents Layer are present in incident_icons layer too. An incident icon can be provided for an incident's primary or secondary locations. Primary location is where the source of the incident (e.g. an accident or congestion) occurs and is located at the end of the road part affected by the incident. Secondary location is the start of the road part affected by the incident.

Incident icons properties (optional)

• is_primary: set to true when the feature represents the icon position of the incident's primary location, false (or option is absent) when the feature represents the icon position of the incindent's secondary location.
• offset_direction: the angle in degrees between the true North and the driving side perpendicular to the direction of the incident. Expressed as an integer in range of 0-359, using a clockwise rotation from North.