Some data 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). These additional data can, however, be accessed using the Telraam Application Programming Interface (API).
How do I access 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. 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 do I work with the API?
In our experience, people are mainly interested in downloading the data 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).
-
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 to also add the entry “Content-Type” and “application/json” 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., for this segment, the segment ID is 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”
Speed per hour is one of the statistics often requested by Telraam users, as they cannot view the data per hour via the website, the dashboard or the excel in their dashboard. 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”.