Traffic API Developer's Guide

Requesting Localized Incident Data

A request to the HERE Traffic API can localize the response to a specific time zone, format, or language, instead of relying on the defaults. Note, however, that localized incident descriptions (translations) are available only for the supported languages – for the full list, please see Localization Defaults. All the provided examples are for incidents endpoint "/traffic/6.1/".

Incident Data, [Z]/[X]/[Y] Addressing

User Story

The user wants to obtain traffic incident information for a tile at zoom level 8 representing an area near Frankfurt, Germany. The response is to be localized to the USA and the text it includes translated into English (en). Note that the default incident time zone, date format and language in the response are: timezone - UTC/GMT, date format - DIN ISO 8601:2006-09, and language - German (de). The request is to use the [Z]/[X]/[Y] addressing scheme.

Request Summary

The following list summarizes the elements required to create a request matching the user story and shows, in square brackets, how those elements are used in the request example below. Note that the request example also uses the authentication parameters.

Resource: incidents [incidents]
URL variables: {data_format} [xml], response data format specification, here XML (to indicate that JSON is required, use json)
  {zoom}/{column}/{row} [8/134/86] , the [Z]/[X]/[Y] (tile) addressing scheme, see also The Mercator Projection
Parameters: c [c=US], country to which to localize
  lg [lg=en], localization language
  i18n [i18n=true], a flag indicating if incident messages are to be translated into the localization language
  local_time [local_time=true], a flag indicating whether to use local time
  units [units=metric], measurement unit system being used for translations. Default value is metric. Possibile values are metric and imperial

Request

A request matching the user story is formulated as follows:

https://traffic.cit.api.here.com/traffic/6.1/incidents/xml/8/134/86
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&c=US
&lg=en
&i18n=true
&localtime=true
&units=metric

Response

The following code block shows the response to the request for localized incident data. Note that this response is abbreviated because of space limitations. In reality, the XML may contain a very large number of <TRAFFIC_ITEM> elements.


<?xml version="1.0" encoding="UTF-8"?>
<TRAFFICML_INCIDENTS TIMESTAMP="10/14/2013 14:37:06 GMT" VERSION="5.0">
  <TRAFFIC_ITEMS>
    <TRAFFIC_ITEM>
      <TRAFFIC_ITEM_ID>420872348</TRAFFIC_ITEM_ID>
      <ORIGINAL_TRAFFIC_ITEM_ID>420409397</ORIGINAL_TRAFFIC_ITEM_ID>
      <TRAFFIC_ITEM_STATUS_SHORT_DESC>ACTIVE</TRAFFIC_ITEM_STATUS_SHORT_DESC>
      <TRAFFIC_ITEM_TYPE_DESC>OTHER NEWS</TRAFFIC_ITEM_TYPE_DESC>
      <START_TIME>July 8, 2013 7:20:10 PM CEST</START_TIME>
      <END_TIME>October 31, 2013 1:00:00 PM CET</END_TIME>
      <ENTRY_TIME>July 10, 2013 7:23:21 AM CEST</ENTRY_TIME>
      <CRITICALITY>
        <ID>2</ID>
        <DESCRIPTION>minor</DESCRIPTION>
      </CRITICALITY>
      <VERIFIED>true</VERIFIED>
      <COMMENTS> </COMMENTS>
      <RDS-TMC_LOCATIONS>
        <RDS-TMC>
          <ORIGIN>
            <EBU_COUNTRY_CODE>D</EBU_COUNTRY_CODE>
            <TABLE_ID>1</TABLE_ID>
            <LOCATION_ID>23982</LOCATION_ID>
            <LOCATION_DESC>Wetzlar-Ost</LOCATION_DESC>
            <RDS_DIRECTION>+</RDS_DIRECTION>
          </ORIGIN>
          <DIRECTION>-</DIRECTION>
          <ALERTC>
            <TRAFFIC_CODE>485</TRAFFIC_CODE>
            <DESCRIPTION>connecting carriageway blocked</DESCRIPTION>
            <ALERTC_DURATION>D</ALERTC_DURATION>
            <ALERTC_DIRECTION>1</ALERTC_DIRECTION>
            <URGENCY>U</URGENCY>
            <UPDATE_CLASS>7</UPDATE_CLASS>
            <PHRASE_CODE>C24</PHRASE_CODE>
            <EXTENT>0</EXTENT>
            <DURATION>0</DURATION>
          </ALERTC>
        </RDS-TMC>
      </RDS-TMC_LOCATIONS>
      <LOCATION>
        <DEFINED>
          <ORIGIN>
            <ROADWAY ID="50396"></ROADWAY>
            <POINT ID="23982"></POINT>
            <DIRECTION ID="0"></DIRECTION>
            <PROXIMITY></PROXIMITY>
          </ORIGIN>
          <TO>
            <ROADWAY ID="50396"></ROADWAY>
            <POINT ID="23982"></POINT>
            <DIRECTION ID="0"></DIRECTION>
            <PROXIMITY></PROXIMITY>
          </TO>
        </DEFINED>
        <GEOLOC></GEOLOC>
        <NAVTECH></NAVTECH>
      </LOCATION>
      <TRAFFIC_ITEM_DETAIL>
        <ROAD_CLOSED>false</ROAD_CLOSED>
        <NEWS></NEWS>
      </TRAFFIC_ITEM_DETAIL>
      <TRAFFIC_ITEM_DESCRIPTION TYPE="short_desc">
        between Wetzlar-Ost and Wetzlar-Ost, connecting carriageway blocked
      </TRAFFIC_ITEM_DESCRIPTION>
      <TRAFFIC_ITEM_DESCRIPTION TYPE="desc">
        between Wetzlar-Ost and Wetzlar-Ost, connecting carriageway blocked
      </TRAFFIC_ITEM_DESCRIPTION>
      <TRAFFIC_ITEM_DESCRIPTION TYPE="no_exit_description">
        connecting carriageway blocked
      </TRAFFIC_ITEM_DESCRIPTION>
    </TRAFFIC_ITEM>
  </TRAFFIC_ITEMS>
</TRAFFICML_INCIDENTS>

Incident Data, Quadkey Addressing

A quadkey version of the same request for traffic incident data is shown below. Further possibilities are to use proximity (prox), bounding box (bbox), or corridor (corridor) in place of the quadkey string parameter-value pair.

User Story

The user wants to obtain traffic incident information for a tile representing an area near Frankfurt, Germany. The response is to be localized to the USA and the text it includes translated into English (en). Note that the default incident time zone, date format and language in the response are: timezone - UTC/GMT, date format - DIN ISO 8601:2006-09, and language - German (de). The request is to use quadkey addressing.

Request Summary

The following list summarizes the elements required to create a request matching the user story and shows, in square brackets, how those elements are used in the request example below. Note that the request example also uses the authentication parameters.

Resource: incidents [incidents.xml], the resource and resource extension indicating the required response data format, here XML (to indicate JSON, use incidents.json)
Parameters: quadkey [quadkey=12020330], map tile location specified as a single value, see also Quadkeys
  c [c=US], country to which to localize
  lg [lg=en], localization language
  i18n [i18n=true], a flag indicating if incident messages are to be translated into the localization language
  local_time [local_time=true], a flag indicating whether to use local time
  units [units=metric], measurement unit system being used for translations. Default value is metric. Possibile values are metric and imperial

Request

A request matching the user story is formulated as follows:

https://traffic.cit.api.here.com/traffic/6.1/incidents.xml
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&quadkey=12020330
&c=US
&lg=en
&i18n=true
&localtime=true
&units=metric

Response

The result of this request is similar to that shown under Response.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.