More data and statistics - using the Telraam API
Some data that is produced by Telraam is not directly available on www.telraam.net (neither on the standard pages of the site, nor via the personal and network dashboards). However, just like any other data product, these can also be accessed using the Telraam API (Application Programming Interface). You will find all necessary information via the following link: Telraam API.
The latest version of the Telraam API (version 1.2) went live in February 2021.
How to get access to the API?
The API works with tokens to manage the load, and to control data-access permissions to specific data products on our servers. A basic token can be obtained free of charge via your Telraam account dashboard. (You can alway make a Telraam account even without owning a Telraam!) In the menu bar on the left, click on the "Token" section under “API”, then you can request your personal token by clicking on the top right button of the screen.
How to work with the API?
In our experience most people are mainly interested in downloading the data that is presented on the web page of each specific road segment, so they can play around with the numbers themselves. Taking this example, this is how you would do it using the API:
- Download and install the Postman app (it is a simple, free, cross-platform app for developing and using API calls) from: https://www.getpostman.com/
- Open Postman, and in the empty workspace, click on the "+" tab (to the left of the "..." tab)
- Make a POST call (change GET to POST in front of the empty input field), and then write the URL of the selected API call (in our case the “Traffic API” call) in the input field as: “https://telraam-api.net/v1/reports/traffic” (without the quotation marks).
- Under the address click the “Headers” tab and in the “Key” field write “X-Api-Key”. Then enter your personal API token in the “Value” field. If not yet present by default, make sure also the entry "Content-Type" and "application/json" is also added in a similar way. After this step your postman window should look like this (but with your API Token):
- Finally you can specify the parameters of your API request in the “Body” tab (next to the “Headers” tab). Here following the format specified below, you can enter the identifier of the segment you are interested in (in the “id” field, where the identifier - or segment ID - can be found in the web address of each segment on the Telraam website, e.g., https://telraam.net/nl/location/347295/2019-11-26/2019-12-10 -> the segment ID is then 347295), and the start and end date and time (in UTC) of the interval you are interested in (maximum 1 year at once). Make sure “raw” is selected as format above the entry field.
- Then by clicking on the big blue “Send” button, you can send your request, and depending on how much data there is on the Telraam server for your requested period, within a few seconds you will receive a response with the data.
- To fully understand all the returned data fields, please consult the full Telraam API documentation already linked above.
Example: Data "Speed per hour"
This is one of the statistics that is often requested by our customers.
Via the website, via the dashboard, and via the excel in your dashboard you cannot view the data per hour.
That is only possible via the API with the POST traffic method. You will then receive an answer including car_speed_hist_0to70plus and car_speed_hist_0to120plus. These fields contain the speed histograms with a resolution of 5 km/h and 10 km/h, respectively. To find out more about this API method, have a look at the following link: API Documentation Data "Speed per hour".