All Telraam API users should familiarise themselves with the concepts and definitions in this article before using the Telraam API, or the data accessed through the Telraam API.
Some basic definitions
Telraam data: Telraam devices count road users passing in front of them. Telraam does not record images or movies of the road users, only count data (along with basic object properties such as size and duration of visibility in the case of Telraam V1 devices) is uploaded to the servers. Road users are classified into classes (either by the server, or directly by the edge devices, in the case of Telraam V1 and Telraam S2 data, respectively), and are aggregated into quarterly and hourly periods. Aggregate counts are available through the API. |
Camera instance: A camera instance - or, as often referred to, simply an instance - is the concept of a physical Telraam device (with its mac/device id, that identifies the hardware), installed on one side of a distinct road segment (which identifies the location of the hardware), by a specific user (that identifies the person who owns or houses the hardware). One specific combination of a mac/device ID, a segment ID, and a user ID defines an instance, which is then identified by a specific instance ID. If any of these three properties changes (a new hardware is installed, the Telraam is moved to another segment, or simply it is transferred to a different user), that will mean the end of the original instance (ID) and the creation of a new instance (ID). |
Road segment: All Telraam units are installed on (a specific side of) a road segment - most often simply referred to as segments. These segments are defined typically between two corners of a street, so a longer street will most likely consist of multiple road segments. In practice, road segments are described by a set of geographical coordinate pairs, a chain of (or at least two) longitude-latitude pairs. The first coordinate pair defines the beginning of the road segment (point A on our mini maps on the Telraam website), and the last pair defines the end of the segment (point B on the Telraam website). Data on the Telraam website is always displayed on a segment level, but for example it is possible to have multiple instances on the same segment (two people on opposite sides of the road, or two neighbours installing a Telraam), then the average of these two instances will be taken as segment-level data. |
Traffic modes - Telraam V1: Road users are classified into four categories based on their observed properties (see FAQ for a more detailed technical explanation): initially cars, two-wheelers (including mainly cyclists and motorbikes), and pedestrians, then in a second step, cars are divided into passenger cars and heavy vehicles (anything that is larger than a passenger car, including lorries, trucks, buses, etc.). The cut-off (in size) between cars and heavy vehicles is derived (automatically) only when enough data is available from a given instance, therefore new Telraam V1 units will not have heavy vehicles counts in the first week (or two) of their operation. |
Traffic modes - Telraam S2: Telraam S2 devices classify the detected objects on the fly, so we do not need to do this as a post-processing step on the Telraam servers anymore. Actually object detection and classification happens at the same time now and it is done by an artificial intelligence (AI) chip. Our Telraam S2 sensor can differentiate between ten different road user categories: bicycle, bus, car, light truck, motorcycle, pedestrian, stroller, tractor, trailer, and truck. These are also aggregated into the four classical Telraam classes: pedestrians (pedestrians + strollers), two wheelers (bicycles and motorcycles), cars, and heavy vehicles (all the remaining classes) to make sure that data across different types of devices is still easy to compare and visualise using the legacy APIs and tools. Telraam S2 devices can also count objects at night (since mid June 2024). We can only detect objects which have visible lights: mainly motorised vehicles, but also some bicycles with stronger headlights. At night we cannot differentiate between the 10 road user types the same way as we can in daylight, so all road users that we manage to count in the dark are aggregated under the general night category. This night class can be thought of as an 11th Telraam S2 class and a 5th classical Telraam class. |
Uptime: Due to the technical setup of the Telraam V1 units, they do not count objects 100% of the time, but spend ~20% of their time calculating a typical background this happens every few minutes and it defines how the street would look without cars moving on it), and depending on the amount of object that they observe, a few % of time doing processing on the data before it is uploaded to the servers. When we subtract the time that is not spent actively counting from the 100%, then we get the uptime. So if we assume 20% is spent on background calculation, and 5% on processing in a given hour, then the uptime for that hour will be 100% - (20% + 5%) = 75%, which is given as 0.75 in the API. The data provided through the API (an displayed on the website) is already corrected for this uptime, meaning that we provide the numbers that would have been counted if the camera had been actively counting 100% of the time. There are two important things to note here. First, when uptime is 0, then the camera was not actively counting, this happens, e.g., during night hours. Second, when for example sunrise is a 6:55, Telraam has only 5 minutes left in the hour to count, so even without time lost for background calculations and processing, the uptime would be below 0.1, therefore quite some uncertainty is introduced into the corrected data of that hour (for easy to understand statistical reasons). For this reason always keep an eye on the uptime values, and use them, e.g., as weights when calculating averages over multiple days, or as quality markers. A high 0.7-0.8 uptime will always mean very good data. The first and last daylight hour of the day will always have lower uptimes for the aforementioned reason, but if uptimes during the day are below 0.5, that is usually a clear sign that something is probably wrong with the instance. Uptime for Telraam S2 units is almost always 1. |
Understanding traffic direction
On the Telraam website we differentiate between traffic flowing in directions A->B and B->A on a given segment. In the API directions are given as lft and rgt. Below we will explain why the difference, and how users can convert between these two notations.
The origin of lft and rgt - left and right direction on instance level
When someone buys a Telraam, they are interested in the traffic viewed from their window, so for them it makes sense to think in terms of traffic going left and right. This means that in instance level traffic data (provided by an instance level POST traffic API call) lft actually means traffic moving to the left from the point of the view of the camera, and rgt means traffic moving to the right. Instance level data also has a direction value (1 or 0, depending on which side of the street segment the Telraam is installed - see mode explanation below) in the data, but it is not relevant in terms of traffic flow from the point of the camera.
Problems with talking about left and right direction on street segment level
When thinking about traffic flowing along a street segment, left and right directions do not make sense anymore, because while on an West-East oriented street we could still talk about left and right flow directions, that is impossible to do on a North-south oriented street. Moreover what if there is a Telraam that is installed on the North side of a West-East oriented street (looking South), then what is traffic moving to the left from the point of view of the Telraam would be moving right from the point of the view of somebody who is looking at the map.
Directions on street segment level
To solve this we have chosen to represent street segments in our database with a virtual Telraam (instance) that is placed consistently on the direction = 1 side (that we also refer to as the True side) of a street segment. The data that is displayed for the street segments on the website, or given by the segment level POST traffic API calls, is data aggregated to these virtual cameras (hence all segment level API calls will return a direction = 1 flag). So for example if a given street segment has only one instance, and that is actually placed on the direction = 0 side of the street segment, then the lft and rgt traffic counts will be switched up between the instance level report and the segment level report, since for the segment level report we had to change these as the virtual camera that represent the segments is looking at the street from the opposite side of the road as the actual instance. Similarly if on a street segment there is only one instance, and it is installed on the direction = 1 side of the road, then the segment and instance level data will be the same for this instance and this segment, since the virtual camera representing the segment is placed on the same side of the road as the actual instance. This also makes it easy to deal with street segments that contain multiple instances, e.g., one instance on the direction = 1 and another on the direction = 0 side of the road, because when we aggregate (average) the instance level data to the virtual camera that represents the street segment, then we simply flip the lft and rgt values of the direction = 0 segment before we average the counts.
Conversion from _lft/_rgt to A->B and B->A
To convert the segment level data from the traffic API onto directions that can be matched with a street on a map, use the following key:
True side (direction = 1)
A ---------------------- B
False side (direction = 0)**A -> B traffic flow seen from the True side (direction = 1) is the lft direction (traffic flows to the left from the camera’s point of view). Since segments are always represented by a direction = 1 virtual camera, this key is always valid for segment level data.** For instance level data, lft and rgt keep representing the traffic flow direction from the point of view of the actual instance, so if you want to convert that to the A->B notation, then if the instance has direction = 1 then the same conversion hold, if the direction = 0 then the conversion is the opposite (and rgt becomes A->B on the corresponding segment).
Note on legacy API
Some of our old v0 API (up to documentation version 1.1) still works, but it is connected to an older (in not all aspects live) version of our database, therefore we strongly suggest using the most recent API endpoints. We have also made better versions for some of the original v1 APIs in the meantime, which are available parallel with their legacy versions. We strongly recommend not using any API that had the legacy version tag in their name in our old Postman documentation (these are not visible in our new Swagger documentation anymore), as their support is not guaranteed.
Note on private installations
For an extra fee it is possible to create non-public camera installations on sensitive locations (e.g., on private properties). These camera instances do not contribute to segment level data (so if a segment contains a private and two public camera instances, the segment level data will be calculated as a weighted average of the two public instances only), and their instance details and count data are hidden from the Public API endpoints (and the Telraam website). These are accessible only to people who have specific access rights (typically the owners of these instances) using specific Advanced API methods.
For questions on how to use the API, visit the FAQ article "You wish more data and statistics? Using the Telraam API"
