Some data that is produced by Telraam is not directly available on 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 be accessed using the Telraam API (Application Programming Interface). You will find all necessary information via the following links: FAQ article "Understanding the Telraam API"and Telraam API.
The latest version of the Telraam API (version 1.2) first went live in February 2021, and it was given a more modern documentation in June 2024.
API token required
The Telraam v1 API (documentation version 1.2 and above) uses an API key (otherwise called an API token) that the client (for example Postman) needs to provide when making API calls. We use the "X-Api-Key", a custom header convention for passing your API key and its light form of authentication.
How to get access to the API?
You can create your personal token through your online Telraam dashboard. First register as a normal user on https://telraam.net/ - even if you do not intend to register a Telraam camera itself. Then click on the button next to your name in the bottom left, and select "API Tokens". Now in the upper right corner you can find "Request new token".
It's possible to use multiple API tokens, e.g., for each project you're running you can create a token. A maximum of three tokens is allowed.
Limits to the usage of our API
The following limits apply to the usage of the API:
Rate: 1 request per second
Burst: 1 request
Quota: 1000 requests per day (10000 for Advanced API users)
How to work with the API?
Swaggerhub, start here if you've never used an API
With our interactive, machine and human-readable API documentation you can try (and use) all of our API endpoints (that you have access to) simply from a browser! Select an API, click Try it out, provide your API Token in the X-Api-Key field, and have fun!
Using Postman
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/en/location/9000001463/2024-06-12/2024-06-18 -> the segment ID is then 9000001463), and the start and end date and time (in UTC) of the interval you are interested in (maximum 3 months 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 two links (API Introduction and Documentation) that were already linked above.
Use programming language for interaction with REST API
Otherwise you can use many programming languages to interact with our REST API. The following Python snippet should teach you how to get a pandas data frame, or even just a plain text .csv file from our popular traffic API endpoint:
import pandas as pd
import requests
import json
url = "https://telraam-api.net/v1/reports/traffic"
body = {
"id":"9000001463",
"time_start":"2022-10-01 00:00:00Z",
"time_end":"2022-10-02 00:00:00Z",
"level":"segments",
"format":"per-hour"
}
headers = {'X-Api-Key': 'Your personal API key comes here'}
payload = str(body)
response = requests.request("POST", url, headers=headers, data=payload)
json = response.json()
dataframe = pd.DataFrame(json['report'])
dataframe.to_csv('test.csv')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.
