Sommige gegevens die door Telraam worden geproduceerd, zijn niet rechtstreeks beschikbaar op www.telraam.net (noch op de standaardpagina's van de site, noch via de persoonlijke en netwerkdashboards). Deze zijn echter, net als alle andere gegevensproducten, ook toegankelijk via de Telraam API (Application Programming Interface). Je vindt alle nodige informatie via de volgende links: FAQ artikel "Het begrijpen van de Telraam API" en Telraam API.
De nieuwste versie van de Telraam API (versie 1.2) ging voor het eerst live in februari 2021, en het kreeg een modernere documentatie in juni 2024.
Hoe krijg ik toegang tot de API
De Telraam v1 API (documentatie versie 1.2 en hoger) gebruikt een API-sleutel (ook wel een API-token genoemd) die de client (bijvoorbeeld Postman) moet verstrekken bij het maken van API-oproepen. We gebruiken de "X-Api-Key", een aangepaste header conventie voor het doorgeven van je API-sleutel en een lichte vorm van authenticatie.
Waar API-token aanmaken
Je kunt je persoonlijke token aanmaken via je online Telraam dashboard. Registreer je eerst als een normale gebruiker op https://telraam.net/ - zelfs als je niet van plan bent om een Telraam camera zelf te registreren. Klik vervolgens op de knop naast je naam in de linkerbenedenhoek en selecteer "API Tokens". Nu kun je in de rechterbovenhoek "Request new token" vinden.
Het is mogelijk om meerdere API tokens te gebruiken, bijvoorbeeld voor elk project dat je uitvoert kun je een token aanmaken. Er zijn maximaal drie tokens toegestaan.
Limieten API gebruik
De volgende limieten gelden voor het gebruik van de API:
Snelheid: 1 verzoek per seconde
Burst: 1 verzoek
Quotum: 1000 verzoeken per dag (10000 voor geavanceerde API-gebruikers)
Hoe werken met de API?
Postman
Onze ervaring is dat de meeste mensen vooral geïnteresseerd zijn in het downloaden van de gegevens die op de webpagina van elk specifiek wegsegment worden gepresenteerd, zodat ze zelf met de cijfers kunnen spelen. Als we dit voorbeeld nemen, is dit hoe je het zou doen met behulp van de API:
Download en installeer de Postman app (het is een eenvoudige, gratis, cross-platform app voor het ontwikkelen en gebruiken van API-oproepen) van: https://www.getpostman.com/
Open Postman, en in de lege werkruimte, klik op de "+" tab (links van de "..." tab)
Doe een POST oproep (verander GET in POST voor het lege invoerveld), en schrijf dan de URL van de geselecteerde API oproep (in ons geval de "Traffic API" oproep) in het invoerveld als: "https://telraam-api.net/v1/reports/traffic" (zonder de aanhalingstekens).
Klik onder het adres op de "Headers" tab en schrijf in het "Key" veld: "X-Api-Key". Voer vervolgens uw persoonlijke API token in het "Value" veld in. Indien nog niet standaard aanwezig, zorg er dan voor dat ook de vermelding "Content-Type" en "application/json" op een soortgelijke manier is toegevoegd. Na deze stap zou je postman venster er als volgt uit moeten zien (maar dan met je API Token):
Tenslotte kun je de parameters van je API verzoek specificeren in het "Body" tabblad (naast het "Headers" tabblad). Hier kun je volgens het hieronder gespecificeerde formaat de identifier van het segment waarin je geïnteresseerd bent invoeren (in het veld "id", waarbij de identifier - of segment ID - te vinden is in het webadres van elk segment op de Telraam website, bijv. https://telraam.net/nl/location/347295/2019-11-26/2019-12-10 -> de segment ID is dan 347295), en de begin- en einddatum en -tijd (in UTC) van het interval waarin je geïnteresseerd bent (maximaal 1 jaar in één keer). Zorg ervoor dat "raw" is geselecteerd als formaat boven het invoerveld.
Door vervolgens op de grote blauwe knop "Verzenden" te klikken, kun je je verzoek verzenden, en afhankelijk van hoeveel gegevens er op de Telraam-server staan voor de door jou gevraagde periode, ontvang je binnen enkele seconden een antwoord met de gegevens. Voor een volledig begrip van alle gegevensvelden, raadpleeg "Begrijpen van de Telraam API".
Coderen is voor nerds en je hebt gewoon wat gegevens nodig?
Met onze interactieve, machine- en mensleesbare API-documentatie kun je alle API-eindpunten (waar je toegang tot hebt) direct vanuit een browser proberen (en gebruiken)! Selecteer een API, klik op Try it out, geef je API Token op in het veld X-Api-Key, veel plezier!
Programmeren voor interactie met REST API
Je kunt anders ook veel programmeertalen gebruiken om te communiceren met onze REST API. Het volgende Python-script zou je moeten leren hoe je een pandas data frame, of zelfs gewoon een platte tekst .csv-bestand kunt krijgen van onze populaire verkeers-API-eindpunt:
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')Voorbeeld: Data "Snelheid per uur"
Dit is één van de datapakketten die vaak door onze gebruikers wordt opgevraagd.
Via de website, via het dashboard, en via de excel in uw dashboard kun je de gegevens per uur niet bekijken.
Dat kan alleen via de API met de POST traffic methode. Je krijgt dan een antwoord met daarin car_speed_hist_0to70plus en car_speed_hist_0to120plus. Deze velden bevatten de snelheidshistogrammen met een resolutie van respectievelijk 5 km/h en 10 km/h.
