Tous les utilisateurs de l'API Telraam doivent se familiariser avec les concepts et définitions de cet article avant d'utiliser l'API Telraam ou les données accessibles via Telraam API.
Quelques définitions de base
Données Telraam : Les appareils Telraam comptent les usagers de la route qui passent devant eux. Telraam n'enregistre pas d'images ou de vidéos des usagers de la route, seules les données de comptage (avec des propriétés d'objet de base telles que la taille et la durée de visibilité dans le cas des appareils Telraam V1) sont téléchargées sur les serveurs. Les usagers de la route sont classés en catégories (soit par le serveur, soit directement par les appareils de périphérie, dans le cas des données Telraam V1 et Telraam S2, respectivement), et sont agrégés en périodes de quart d'heure et d'heure. Les comptes agrégés sont disponibles via l'API. |
Instance de caméra : Une instance de caméra - ou, comme souvent appelé, simplement une instance - est le concept d'un appareil Telraam physique (avec son identifiant mac/appareil, qui identifie le matériel), installé sur un côté d'un segment de route distinct (qui identifie l'emplacement du matériel), par un utilisateur spécifique (qui identifie la personne qui possède ou héberge le matériel). Une combinaison spécifique d'un identifiant mac/appareil, d'un identifiant de segment et d'un identifiant d'utilisateur définit une instance, qui est ensuite identifiée par un identifiant d'instance spécifique. Si l'une de ces trois propriétés change (un nouveau matériel est installé, le Telraam est déplacé vers un autre segment ou simplement transféré à un autre utilisateur), cela signifie la fin de l'instance originale (ID) et la création d'une nouvelle instance (ID). |
Segment de route : Toutes les unités Telraam sont installées sur (un côté spécifique d') un segment de route - souvent simplement appelés segments. Ces segments sont typiquement définis entre deux coins de rue, donc une rue plus longue comprendra probablement plusieurs segments de route. En pratique, les segments de route sont décrits par un ensemble de paires de coordonnées géographiques, une chaîne de (ou au moins deux) paires de longitude-latitude. La première paire de coordonnées définit le début du segment de route (point A sur nos mini-cartes sur le site Telraam), et la dernière paire définit la fin du segment (point B sur le site Telraam). Les données sur le site Telraam sont toujours affichées au niveau du segment, mais par exemple, il est possible d'avoir plusieurs instances sur le même segment (deux personnes de chaque côté de la route, ou deux voisins installant un Telraam), alors la moyenne de ces deux instances sera prise comme données au niveau du segment. |
Modes de trafic - Telraam V1 : Les usagers de la route sont classés en quatre catégories en fonction de leurs propriétés observées (voir la FAQ pour une explication technique plus détaillée) : initialement les voitures, les deux-roues (y compris principalement les cyclistes et les motocyclistes), et les piétons, puis dans une deuxième étape, les voitures sont divisées en voitures particulières et véhicules lourds (tout ce qui est plus grand qu'une voiture particulière, y compris les camions, les bus, etc.). La coupure (en taille) entre les voitures et les véhicules lourds est dérivée (automatiquement) seulement lorsqu'il y a suffisamment de données disponibles d'une instance donnée, donc les nouvelles unités Telraam V1 n'auront pas de comptages de véhicules lourds dans la première semaine (ou deux) de leur fonctionnement. |
Modes de trafic - Telraam S2 : Les appareils Telraam S2 classifient les objets détectés à la volée, nous n'avons donc plus besoin de le faire comme une étape de post-traitement sur les serveurs Telraam. En réalité, la détection et la classification des objets se font maintenant simultanément et sont effectuées par une puce d'intelligence artificielle (IA). Notre capteur Telraam S2 peut différencier dix catégories différentes d'usagers de la route : vélo, bus, voiture, camion léger, motocyclette, piéton, poussette, tracteur, remorque et camion. Ceux-ci sont également agrégés dans les quatre catégories classiques de Telraam : piétons (piétons + poussettes), deux-roues (vélos et motocyclettes), voitures et véhicules lourds (toutes les autres catégories) pour s'assurer que les données des différents types d'appareils sont toujours faciles à comparer et à visualiser à l'aide des anciennes API et outils. Les appareils Telraam S2 peuvent également compter les objets la nuit (depuis mi-juin 2024). Nous ne pouvons détecter que les objets qui ont des lumières visibles : principalement les véhicules motorisés, mais aussi certains vélos avec des phares plus puissants. La nuit, nous ne pouvons pas différencier les 10 types d'usagers de la route de la même manière que nous le faisons à la lumière du jour, donc tous les usagers de la route que nous parvenons à compter dans l'obscurité sont agrégés sous la catégorie générale de nuit. Cette catégorie de nuit peut être considérée comme une 11ème catégorie Telraam S2 et une 5ème catégorie Telraam classique. |
Temps de disponibilité (uptime) : En raison de la configuration technique des unités Telraam V1, elles ne comptent pas les objets 100 % du temps, mais passent environ 20 % de leur temps à calculer un arrière-plan typique (cela se produit toutes les quelques minutes et définit comment la rue apparaîtrait sans voitures en mouvement dessus), et en fonction du nombre d'objets qu'elles observent, quelques pour cent du temps à traiter les données avant qu'elles ne soient téléchargées sur les serveurs. Lorsque nous soustrayons le temps qui n'est pas passé activement à compter des 100 %, nous obtenons le temps de disponibilité. Donc, si nous supposons que 20 % est consacré au calcul de l'arrière-plan et 5 % au traitement dans une heure donnée, alors le temps de disponibilité pour cette heure sera de 100 % - (20 % + 5 %) = 75 %, ce qui est donné comme 0,75 dans l'API. Les données fournies via l'API (et affichées sur le site web) sont déjà corrigées pour ce temps de disponibilité, ce qui signifie que nous fournissons les chiffres qui auraient été comptés si la caméra avait été activement en train de compter 100 % du temps. Il y a deux choses importantes à noter ici. Premièrement, lorsque le temps de disponibilité est de 0, cela signifie que la caméra n'était pas activement en train de compter, cela se produit, par exemple, pendant les heures de nuit. Deuxièmement, lorsque par exemple le lever du soleil est à 6h55, Telraam n'a plus que 5 minutes dans l'heure pour compter, donc même sans perte de temps pour les calculs d'arrière-plan et le traitement, le temps de disponibilité serait inférieur à 0,1, introduisant ainsi une certaine incertitude dans les données corrigées de cette heure (pour des raisons statistiques faciles à comprendre). Pour cette raison, gardez toujours un œil sur les valeurs de temps de disponibilité et utilisez-les, par exemple, comme poids lors du calcul des moyennes sur plusieurs jours, ou comme indicateurs de qualité. Un temps de disponibilité élevé de 0,7 à 0,8 signifiera toujours des données de très bonne qualité. La première et la dernière heure de lumière du jour de la journée auront toujours des temps de disponibilité plus faibles pour les raisons mentionnées ci-dessus, mais si les temps de disponibilité pendant la journée sont inférieurs à 0,5, c'est généralement un signe clair que quelque chose ne va probablement pas avec l'instance. Le temps de disponibilité pour les unités Telraam S2 est presque toujours de 1. |
Comprendre la direction du trafic
Sur le site Telraam, nous différencions le trafic circulant dans les directions A->B et B->A sur un segment donné. Dans l'API, les directions sont données sous forme de lft et rgt. Ci-dessous, nous expliquerons pourquoi la différence, et comment les utilisateurs peuvent convertir entre ces deux notations.
L'origine de lft et rgt - direction gauche et droite au niveau de l'instance
Lorsque quelqu'un achète un Telraam, il s'intéresse au trafic vu de sa fenêtre, donc pour lui, il est logique de penser en termes de trafic allant à gauche et à droite. Cela signifie que dans les données de trafic au niveau de l'instance (fournies par un appel API de trafic POST au niveau de l'instance), lft signifie en fait le trafic se déplaçant vers la gauche du point de vue de la caméra, et rgt signifie le trafic se déplaçant vers la droite. Les données au niveau de l'instance ont également une valeur de direction (1 ou 0, selon le côté du segment de rue où le Telraam est installé - voir l'explication du mode ci-dessous) dans les données, mais cela n'est pas pertinent en termes de flux de trafic du point de vue de la caméra.
Problèmes pour parler de direction gauche et droite au niveau du segment de rue
Lorsque l'on pense au trafic circulant le long d'un segment de rue, les directions gauche et droite n'ont plus de sens, car tandis que sur une rue orientée Ouest-Est, nous pourrions encore parler de directions de flux gauche et droite, c'est impossible à faire sur une rue orientée Nord-Sud. De plus, que se passe-t-il s'il y a un Telraam installé sur le côté nord d'une rue orientée Ouest-Est (regardant vers le sud), alors ce qui est le trafic se déplaçant vers la gauche du point de vue du Telraam se déplacerait vers la droite du point de vue de quelqu'un qui regarde la carte.
Directions au niveau du segment de rue
Pour résoudre ce problème, nous avons choisi de représenter les segments de rue dans notre base de données avec un Telraam virtuel (instance) placé de manière cohérente du côté direction = 1 (que nous appelons également le côté True) d'un segment de rue. Les données affichées pour les segments de rue sur le site web, ou fournies par les appels API de trafic POST au niveau du segment, sont des données agrégées à ces caméras virtuelles (d'où tous les appels API au niveau du segment renverront un drapeau direction = 1). Donc, par exemple, si un segment de rue donné n'a qu'une seule instance, et qu'elle est en fait placée du côté direction = 0 du segment de rue, alors les comptes de trafic lft et rgt seront échangés entre le rapport au niveau de l'instance et le rapport au niveau du segment, car pour le rapport au niveau du segment, nous devions changer cela car la caméra virtuelle représentant le segment regarde la rue du côté opposé de la route par rapport à l'instance réelle. De même, si un segment de rue n'a qu'une seule instance et qu'elle est installée du côté direction = 1 de la route, alors les données au niveau du segment et de l'instance seront les mêmes pour cette instance et ce segment, car la caméra virtuelle représentant le segment est placée du même côté de la route que l'instance réelle. Cela rend également facile de gérer les segments de rue contenant plusieurs instances, par exemple, une instance du côté direction = 1 et une autre du côté direction = 0 de la route, car lorsque nous agrégeons (moyennons) les données au niveau de l'instance à la caméra virtuelle représentant le segment de rue, nous retournons simplement les valeurs lft et rgt du segment direction = 0 avant de moyenner les comptes.
Conversion de lft/rgt à A->B et B->A
Pour convertir les données au niveau du segment de l'API de trafic en directions qui peuvent être mises en correspondance avec une rue sur une carte, utilisez la clé suivante:
True side (direction = 1)
A ---------------------- B
False side (direction = 0)**Le flux de trafic A -> B vu du côté True (direction = 1) est la direction lft (le trafic se déplace vers la gauche du point de vue de la caméra). Étant donné que les segments sont toujours représentés par une caméra virtuelle direction = 1, cette clé est toujours valable pour les données au niveau du segment.** Pour les données au niveau de l'instance, lft et rgt continuent de représenter la direction du flux de trafic du point de vue de l'instance réelle, donc si vous voulez convertir cela en notation A->B, alors si l'instance a direction = 1, la même conversion est valable, si la direction = 0, la conversion est l'opposée (et rgt devient A->B sur le segment correspondant).
Remarque sur l'API Legacy
Certaines de nos anciennes API v0 (jusqu'à la version de la documentation 1.1) fonctionnent toujours, mais elles sont connectées à une version plus ancienne (pas entièrement active) de notre base de données. Nous vous recommandons donc fortement d'utiliser les points de terminaison API les plus récents. Nous avons également créé de meilleures versions pour certaines des API v1 originales entre-temps, qui sont disponibles parallèlement à leurs versions héritées. Nous vous recommandons fortement de ne pas utiliser d'API qui avait le tag de version héritée dans leur nom dans notre ancienne documentation Postman (celles-ci ne sont plus visibles dans notre nouvelle documentation Swagger), car leur support n'est pas garanti.
Pour des questions sur l'utilisation de l'API, visitez l'article de la FAQ "Je souhaite obtenir plus de données et de statistiques - L'utilisation du Telraam API"
