How to work with the API?
We've learned that most people are interested in downloading all data that is also presented on each segment’s html page, so in most cases people will just need this one API call:
- Download and install the Postman application (this is simply a free cross-platform application to developing and using API calls) from: https://www.getpostman.com/
- Open Postman, and on the empty workspace click the “+” tab (left of the “…” tab)
- Make a POST call (change GET to POST) with, e.g., https://telraam-api.net/v0/reports/421535 address as request URL (the numbers at the end of this web address are specific for each camera (and thus the ‘street segment ID’). Replace the number with the segment ID that you are interested in. (These segment IDs can be found in the web-address of each segment on the Telraam website, e.g.: https://telraam.net/nl/location/347295/2019-11-26/2019-12-10 -> then the segment ID is 347295.)
- Click the “Headers” tab underneath, and to the empty “Key” and “Value” fields fill in “Content-Type” and “application/json”, respectively (without the quotation marks).
- Click the “Body” tab, select “raw” as format, and fill in the following message (change the dates as necessary):
"time_start": "2020-03-03 04:00:00Z",
"time_end": "2020-03-03 23:59:00Z",
- Click the big blue “Send” button
This should result in a structured data reply (a report in JSON format), containing a list of entries like the one below:
"date": "2019-11-05 15:00",
How to understand this API call?
Here is an explanation for the meaning of each entry: these entries are delivered for each hour of the day when the Telraam was active, starting at the given “date” for the given “segment_id”. “pct_up” gives the percentage of time (between 0 and 1 –> 0% to 100%) the Telraam camera was actively counting traffic in the one hour interval. This is almost never 1 (100%), because in standard operation background calculation intervals break the continuous measurements every couple of minutes for a half minute, and during the background calculation no active measurements are being carried out. So a typical good value is around 0.75+/- 0.05. We correct for this typically ~25% downtime by multiplying the actually measured traffic volumes with an appropriate correction factor to estimate the amount of traffic we would have observed given a 100% uptime. These corrected volumes are reported below (rounded to the closest integer). The values “Pedestrian” – “Bike” – “Car” – “Lorry” contain therefore the corrected traffic volumes for this hour.
For a broader description of the classes and the classification procedure we refer to the Telraam White Paper -> https://telraam.zendesk.com/hc/en-be/articles/360033535391-How-does-the-classification-of-Telraam-works- . Here we simply want to stress that everything that is larger than a typical car, starting around small delivery vans (potentially including pickup trucks too), will fall in the “lorry” category, which generally stands for “larger motorized vehicles”. After the totals, we provide numbers for the traffic in both directions through the street, under the “_lft” and “_rgt” variables (these add up to the totals from above). Finally, the “car_speed_histogram” and “car_speed_bucket” arrays together provide the speed distribution in 10 km/h bins between 0 and 70+ km/h in the hour in question. “car_speed_histogram” contains the counts for the corresponding histogram bins, that are listed in “car_speed_bucket”. In the example above all buckets are present (bucket 0 corresponds to 0-10 km/h, bucket 1 is 10-20 km/h, etc., and bucket 7 is 70+ km/h), but in a low traffic street it could happen that only one car is observed that drove by at 55 km/h, then the car_speed_histogram would contain only a 1, and the car_speed_bucke would contain only a 5, which when combined tells us that 1 object was observed in the 50-60 km/h bin.
If necessary, this JSON entry can be converted to a csv format using, e.g., online JSON to CSV converters, e.g., https://json-csv.com/ where one can simply paste the whole JSON text (click into the result window in Postman, then Ctrl+A then Ctrl+C to copy it from the Postman window) and download the converted CSV table that can be opened in EXCEL. In Python we suggest using the https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html function to read in the data using a flexible and convenient format.
What are the technical specifications of the device?
Here we refer to the Telraam White Paper -> https://telraam.zendesk.com/hc/en-be/articles/360035184892-Potential-inaccuracies-in-Telraam. This has the most information available about the classification methods and the different vehicle categories, including potential pitfalls and misclassifications. Beyond what is written in this document, we can always answer specific questions, should there be any.
Do you have any statistics on the accuracy of the vehicle recognition and speed measurements?
For the accuracy of the modal split, we have some validation numbers also in the Telraam White Paper -https://telraam.zendesk.com/hc/en-be/articles/360035184892-Potential-inaccuracies-in-Telraam – in general, in normal conditions (camera far enough and not too close from the road, one the 1st or second floor, so that the camera is looking to the street at an angle of 45+/-15 degrees), our numbers are in a good agreement with other counts. As we develop the system further, accuracy will improve even further.
For the speed estimates we have only the mentioned 10% estimated accuracy. This assumes that all classification is done perfectly and no spurious objects (image recognition artefacts from various sources) have made it through our specific filters. The 10% error will be more or less constant for each camera, but the additional error, especially the term coming from misclassified objects will be different on a camera-by-camera basis, as that depends more on the local specifications (field of view, distance from the road, etc.). Still, outliers and misclassified objects will lead to very inaccurate speed readings, therefore values at the extremes (around 0 and 70+ km/h) should not be trusted, we suggest taking the peak (and general shape) of the speed histogram as an indicative value for the typical speeds on the given road segment.