Alle gebruikers van de Telraam API moeten zich vertrouwd maken met de concepten en definities in dit artikel voordat ze de Telraam API gebruiken, of de gegevens die via de Telraam API worden geraadpleegd.
Enkele basisdefinities
Telraam gegevens: Telraam toestellen tellen weggebruikers die voor hen langs komen. Telraam registreert geen beelden of video's van de weggebruikers, alleen telgegevens (samen met basis objecteigenschappen zoals grootte en duur van zichtbaarheid in het geval van Telraam V1-toestellen) worden geüpload naar de servers. Weggebruikers worden geclassificeerd in klassen (ofwel door de server, of direct door de edge-toestellen, in het geval van respectievelijk Telraam V1 en Telraam S2 gegevens), en worden geaggregeerd in kwartier- en uurperioden. Geaggregeerde tellingen zijn beschikbaar via de API. |
Camera-instantie: Een camera-instantie - of, zoals vaak wordt genoemd, gewoon een instantie - is het concept van een fysiek Telraam apparaat (met zijn mac/apparaat ID, dat de hardware identificeert), geïnstalleerd aan één kant van een bepaald wegsegment (dat de locatie van de hardware identificeert), door een specifieke gebruiker (die de persoon identificeert die de hardware bezit of huisvest). Eén specifieke combinatie van een mac/apparaat ID, een segment ID en een gebruiker ID definieert een instantie, die vervolgens wordt geïdentificeerd door een specifieke instantie ID. Als een van deze drie eigenschappen verandert (een nieuwe hardware wordt geïnstalleerd, de Telraam wordt verplaatst naar een ander segment, of simpelweg overgedragen aan een andere gebruiker), betekent dat het einde van de oorspronkelijke instantie (ID) en de creatie van een nieuwe instantie (ID). |
Wegsegment: Alle Telraam eenheden zijn geïnstalleerd aan (een specifieke kant van) een wegsegment - meestal gewoon segmenten genoemd. Deze segmenten worden typisch gedefinieerd tussen twee hoeken van een straat, dus een langere straat zal waarschijnlijk bestaan uit meerdere wegsegmenten. In de praktijk worden wegsegmenten beschreven door een set van geografische coördinatenparen, een keten van (of minstens twee) lengte- en breedtegraadparen. Het eerste coördinatenpaar definieert het begin van het wegsegment (punt A op onze mini-kaarten op de Telraam website), en het laatste paar definieert het einde van het segment (punt B op de Telraam website). Gegevens op de Telraam website worden altijd op segmentniveau weergegeven, maar bijvoorbeeld het is mogelijk om meerdere instanties op hetzelfde segment te hebben (twee mensen aan weerszijden van de weg, of twee buren die een Telraam installeren), dan wordt het gemiddelde van deze twee instanties genomen als segmentniveau gegevens. |
Verkeersmodi - Telraam V1: Weggebruikers worden geclassificeerd in vier categorieën op basis van hun waargenomen eigenschappen (zie FAQ voor een meer gedetailleerde technische uitleg): aanvankelijk auto's, tweewielers (inclusief voornamelijk fietsers en motorfietsen), en voetgangers, daarna worden in een tweede stap auto's verdeeld in personenauto's en zware voertuigen (alles wat groter is dan een personenauto, inclusief vrachtwagens, bussen, etc.). De grens (in grootte) tussen auto's en zware voertuigen wordt afgeleid (automatisch) alleen wanneer genoeg gegevens beschikbaar zijn van een gegeven instantie, daarom zullen nieuwe Telraam V1 eenheden geen zware voertuigen tellen in de eerste week (of twee) van hun werking. |
Verkeersmodi - Telraam S2: Telraam S2 toestellen classificeren de gedetecteerde objecten direct, dus we hoeven dit niet meer als een nabewerking stap op de Telraam servers te doen. Objectdetectie en classificatie gebeurt nu tegelijkertijd en wordt uitgevoerd door een kunstmatige intelligentie (AI) chip. Onze Telraam S2 sensor kan tien verschillende weggebruikers categorieën onderscheiden: fiets, bus, auto, lichte vrachtwagen, motorfiets, voetganger, kinderwagen, tractor, aanhangwagen en vrachtwagen. Deze worden ook geaggregeerd in de vier klassieke Telraam klassen: voetgangers (voetgangers + kinderwagens), tweewielers (fietsen en motorfietsen), auto's, en zware voertuigen (alle overige klassen) om ervoor te zorgen dat gegevens van verschillende typen toestellen nog steeds gemakkelijk te vergelijken en te visualiseren zijn met behulp van de oude API's en tools. Telraam S2 toestellen kunnen ook 's nachts objecten tellen (sinds medio juni 2024). We kunnen alleen objecten detecteren die zichtbare lichten hebben: voornamelijk gemotoriseerde voertuigen, maar ook sommige fietsen met sterkere koplampen. 's Nachts kunnen we niet op dezelfde manier als overdag onderscheid maken tussen de 10 weggebruikers types, dus alle weggebruikers die we in het donker weten te tellen worden geaggregeerd onder de algemene nacht categorie. Deze nachtcategorie kan worden beschouwd als een 11e Telraam S2 klasse en een 5e klassieke Telraam klasse. |
Uptime: Door de technische opzet van de Telraam V1 eenheden tellen ze niet 100% van de tijd objecten, maar besteden ze ongeveer 20% van hun tijd aan het berekenen van een typische achtergrond (dit gebeurt elke paar minuten en bepaalt hoe de straat eruit zou zien zonder auto's die erop bewegen), en afhankelijk van de hoeveelheid objecten die ze waarnemen, een paar procent van de tijd aan het verwerken van de gegevens voordat deze naar de servers worden geüpload. Wanneer we de tijd aftrekken die niet actief wordt besteed aan het tellen van de 100%, dan krijgen we de uptime. Dus als we aannemen dat 20% wordt besteed aan achtergrondberekening, en 5% aan verwerking in een gegeven uur, dan zal de uptime voor dat uur 100% - (20% + 5%) = 75% zijn, wat wordt gegeven als 0.75 in de API. De gegevens die via de API worden verstrekt (en op de website worden weergegeven) zijn al gecorrigeerd voor deze uptime, wat betekent dat we de aantallen geven die zouden zijn geteld als de camera 100% van de tijd actief had geteld. Er zijn hier twee belangrijke dingen op te merken. Ten eerste, wanneer de uptime 0 is, dan was de camera niet actief aan het tellen, dit gebeurt bijvoorbeeld tijdens nachtelijke uren. Ten tweede, wanneer bijvoorbeeld de zonsopgang om 6:55 is, heeft Telraam nog maar 5 minuten over in het uur om te tellen, dus zelfs zonder tijdverlies voor achtergrondberekeningen en verwerking, zou de uptime onder de 0.1 zijn, waardoor nogal wat onzekerheid wordt geïntroduceerd in de gecorrigeerde gegevens van dat uur (om gemakkelijk te begrijpen statistische redenen). Om deze reden moet je altijd de uptime waarden in de gaten houden en deze gebruiken, bijvoorbeeld als gewichten bij het berekenen van gemiddelden over meerdere dagen, of als kwaliteitsindicatoren. Een hoge uptime van 0.7-0.8 betekent altijd zeer goede gegevens. Het eerste en laatste daglichtuur van de dag zullen altijd lagere uptimes hebben om de bovengenoemde reden, maar als de uptimes gedurende de dag onder de 0.5 zijn, is dat meestal een duidelijk teken dat er waarschijnlijk iets mis is met de instantie. De uptime voor Telraam S2 eenheden is bijna altijd 1. |
Verkeersrichting begrijpen
Op de Telraam website maken we onderscheid tussen verkeer dat in de richting A->B en B->A stroomt op een bepaald segment. In de API worden richtingen gegeven als lft en rgt. Hieronder leggen we uit waarom het verschil, en hoe gebruikers kunnen converteren tussen deze twee notaties.
De oorsprong van lft en rgt - linker- en rechterrichting op instantieniveau
Wanneer iemand een Telraam koopt, zijn ze geïnteresseerd in het verkeer gezien vanuit hun raam, dus voor hen is het logisch om te denken in termen van verkeer dat naar links en rechts gaat. Dit betekent dat in instantieniveau verkeersgegevens (verstrekt door een instantieniveau POST verkeers-API oproep) lft eigenlijk betekent dat verkeer naar links beweegt vanuit het oogpunt van de camera, en rgt betekent verkeer dat naar rechts beweegt. Instantieniveau gegevens hebben ook een richtingwaarde (1 of 0, afhankelijk van aan welke kant van het straatsegment de Telraam is geïnstalleerd - zie mode uitleg hieronder) in de gegevens, maar dit is niet relevant in termen van verkeersstroom vanuit het oogpunt van de camera.
Problemen met praten over linker- en rechterrichting op straatsegmentniveau
Wanneer je nadenkt over verkeer dat langs een straatsegment stroomt, zijn linker- en rechterrichtingen niet meer logisch, want terwijl je op een West-Oost georiënteerde straat nog steeds kunt praten over linker- en rechterstroomrichtingen, is dat onmogelijk te doen op een Noord-Zuid georiënteerde straat. Bovendien, wat als er een Telraam is geïnstalleerd aan de noordkant van een West-Oost georiënteerde straat (kijkend naar het zuiden), dan zou verkeer dat naar links beweegt vanuit het oogpunt van de Telraam naar rechts bewegen vanuit het oogpunt van iemand die naar de kaart kijkt.
Richtingen op straatsegmentniveau
Om dit op te lossen hebben we ervoor gekozen om straatsegmenten in onze database te vertegenwoordigen met een virtuele Telraam (instantie) die consistent is geplaatst aan de richting = 1 kant (die we ook de True kant noemen) van een straatsegment. De gegevens die worden weergegeven voor de straatsegmenten op de website, of verstrekt door de segmentniveau POST verkeers-API oproepen, zijn gegevens die zijn geaggregeerd naar deze virtuele camera's (vandaar dat alle segmentniveau API oproepen een richting = 1 vlag zullen retourneren). Dus bijvoorbeeld als een gegeven straatsegment slechts één instantie heeft, en dat is eigenlijk geplaatst aan de richting = 0 kant van het straatsegment, dan zullen de lft en rgt verkeersaantallen worden omgewisseld tussen de instantieniveau rapport en het segmentniveau rapport, aangezien we voor het segmentniveau rapport deze moesten veranderen omdat de virtuele camera die het segment vertegenwoordigt kijkt naar de straat vanaf de tegenovergestelde kant van de weg als de werkelijke instantie. Evenzo, als er op een straatsegment slechts één instantie is, en deze is geïnstalleerd aan de richting = 1 kant van de weg, dan zullen de segment- en instantieniveau gegevens hetzelfde zijn voor deze instantie en dit segment, aangezien de virtuele camera die het segment vertegenwoordigt zich aan dezelfde kant van de weg bevindt als de werkelijke instantie. Dit maakt het ook gemakkelijk om om te gaan met straatsegmenten die meerdere instanties bevatten, bijvoorbeeld één instantie aan de richting = 1 kant en een andere aan de richting = 0 kant van de weg, omdat wanneer we de instantieniveau gegevens aggregeren (gemiddeld) naar de virtuele camera die het straatsegment vertegenwoordigt, we simpelweg de lft en rgt waarden van het richting = 0 segment omdraaien voordat we de tellingen middelen.
Conversie van lft/rgt naar A->B en B->A
Om de segmentniveau gegevens van de verkeers-API om te zetten in richtingen die overeenkomen met een straat op een kaart, gebruik je de volgende sleutel:
True side (direction = 1)
A ---------------------- B
False side (direction = 0)**A -> B verkeersstroom gezien vanuit de True kant (richting = 1) is de lft richting (verkeer stroomt naar links vanuit het oogpunt van de camera). Aangezien segmenten altijd worden weergegeven door een richting = 1 virtuele camera, is deze sleutel altijd geldig voor segmentniveau gegevens.** Voor instantieniveau gegevens blijven lft en rgt de verkeersstroomrichting vertegenwoordigen vanuit het oogpunt van de werkelijke instantie, dus als je dat wilt omzetten naar de A->B notatie, dan als de instantie richting = 1 heeft, blijft dezelfde conversie gelden, als de richting = 0 is dan is de conversie het tegenovergestelde (en wordt rgt A->B op het overeenkomstige segment).
API-token vereist
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)
Opmerking over legacy API
Sommige van onze oude v0 API (tot documentatieversie 1.1) werkt nog steeds, maar is verbonden met een oudere (in niet alle aspecten live) versie van onze database, daarom raden we sterk aan om de meest recente API-eindpunten te gebruiken. We hebben ook betere versies gemaakt voor sommige van de originele v1 API's in de tussentijd, die parallel beschikbaar zijn met hun legacy-versies. We raden sterk aan om geen API te gebruiken die het legacy-versietag in hun naam had in onze oude Postman documentatie (deze zijn niet meer zichtbaar in onze nieuwe Swagger documentatie), omdat hun ondersteuning niet gegarandeerd is.
Opmerking over privé-installaties
Tegen een extra kost is het mogelijk om niet-publieke camerainstallaties te maken op gevoelige locaties (bijv. op privé-eigendommen). Deze camera-instanties dragen niet bij aan de segmentgegevens (dus als een segment een privé- en twee publieke camerainstanties bevat, worden de segmentgegevens berekend als een gewogen gemiddelde van de twee publieke instanties). Hun instellingsdetails en telgegevens zijn verborgen voor de openbare API-eindpunten (en de Telraam-website). Deze gegevens zijn alleen toegankelijk voor personen met specifieke toegangsrechten (meestal de eigenaren van deze instanties) via specifieke geavanceerde API-methoden.
Voor verdere vragen over hoe je de API kan gebruiken, neem een kijkje in het FAQ artikel "Wens je meer data and statistieken? Telraam API gebruiken"
