Traffic TPEG API Developer's Guide

Quick Start

This article helps you start using the Traffic TPEG API.

Making your first request

Initializing the session

Before retrieving any traffic information, send the following xml body as an HTTP post request containing an HTTP Content-Type header of application/xml


<?xml version="1.0" encoding="UTF-8"?>
<init-session>
  <tpeg format="TPEGBinary" messagesize="50000" sessionsize="1000" >
    <loc-ref id="TMC" version="1.3" />
    <loc-ref id="ETL" version="1.0" />
    <app id="TEC" version="3.2" />
    <app id="TFP" version="1.0" expiration="17" />
  </tpeg>
  <countries current="DE" destination="FR" />
  <configuration>
    <att name="radius" value="10" />
    <att name="expiration" value="600" />
    <att name="timeout" value="300" />
    <att name="frequency" value="180" />
  </configuration>
</init-session> 

to the initsession resource:


https://tpeg.cit.cc.api.here.com/tpeg/1.0/initsession?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

The XML response contains the URL and encryption key for traffic information requests. Example response:


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<init-session-response 
url="https://tpeg.cit.cc.api.here.com/tpeg/1.0/getmessages?v=5&cfg=1DpmhH-p7ElBonkVviVIDrPP3S.lVqIMc33pfUJ2luIDN58GPGDXo2zkQiizAnE-J-2W-MZbShEADKC6GFvLOO7pTnK41VTt3lRfk5cr7CFsMkXz97WRVx57LnljI-9d" 
key="99a8cd635aa563acaf0c486992d297ad">
  <config name="fcd" value="enabled"/>
  <server-settings>
    <att name="max-vicinity-radius" value="100" />
    <att name="max-corridor-width" value="10" />
    <att name="max-corridor-lenght" value="1000" />
    <att name="update-frequency" value="60" />
  </server-settings>
</init-session-response>


          

Retrieving traffic information

After sending an InitSession request, send an HTTP post request with HTTP header Content-Type of application/octet-stream for traffic information to the URL in the response. This example requests traffic information around a single point:


<?xml version="1.0" encoding="UTF-8" ?>
<get-messages>
  <locations>
    <loc lat="52.55121" lon="13.16565"/>    
  </locations>
</get-messages>
          
Encrypt and compress all traffic information requests:
  1. Compress the XML body using gzip.
  2. Calculate the length in bytes of the gzip file.
  3. Prepend the length of the gzipped data to the compressed body as a little endian 32 bit integer.
  4. Pad the combination of gziped content and length with zeros to make it evenly divisible by 16 bytes.
  5. Using AES 128, encrypt the resultant padded combination of content and length as follows:
    1. Create a random integer 16 bytes long.
    2. AES encrypt the result of step 4, in mode CBC using the integer generated in step 5.a as the initialization vector and the key from the InitSession response. Do not apply additional padding.
  6. Send the resulting block of AES encrypted data as an HTTP POST request, prepended by the integer generated in step 5.a as content type application/octet-stream to the URL in the initsession response:

The presence of app_id or app_code in the getmessages request was an indicator for the service to detect the request source.

Decrypt the response by reversing the encryption procedure:
  1. Extract the first 16 bytes of the response.
  2. Decrypt the remainder of the response with AES, using the session key from step 1.
  3. Extract the length of the gzipped content from the 'first four' bytes of the decrypted data.
  4. Expand the gzipped content into TPEGBinary format.

Packet Structure

Encryption Procedure

Decryption Procedure