Certaines données produites par Telraam ne sont pas directement disponibles sur www.telraam.net (ni sur les pages standard du site, ni via les tableaux de bord personnels et de réseau). Cependant, comme tout autre produit de données, elles sont également accessibles via l'API (Application Programming Interface) Telraam. Vous trouverez toutes les informations nécessaires via le lien suivant: l'article FAQ "Compréhension de l'API Telraam" Telraam API.
La dernière version de l'API Telraam (version 1.2) a été mise en ligne pour la première fois en février 2021, et une documentation plus moderne lui a été attribuée en juin 2024.
Comment accéder à l'API
L'API Telraam v1 (version de la documentation 1.2 et plus) utilise une clé API (également appelée un token API) que le client (par exemple Postman) doit fournir lors des appels API. Nous utilisons la "X-Api-Key", une convention d'en-tête personnalisée pour transmettre votre clé API et une forme légère d'authentification.
Comment accéder à l'API ?
Vous pouvez créer votre token personnel via votre tableau de bord Telraam en ligne. Inscrivez-vous d'abord en tant qu'utilisateur normal sur https://telraam.net/ - même si vous n'avez pas l'intention d'enregistrer une caméra Telraam. Ensuite, cliquez sur le bouton à côté de votre nom en bas à gauche et sélectionnez "API Tokens". Vous pouvez maintenant trouver "Request new token" dans le coin supérieur droit.
Il est possible d'utiliser plusieurs tokens API, par exemple, pour chaque projet que vous exécutez, vous pouvez créer un token. Un maximum de trois tokens est autorisé.
Limites d'utilisation de notre API
Les limites suivantes s'appliquent à l'utilisation de l'API :
Taux : 1 requête par seconde
Rafale : 1 requête
Quota : 1000 requêtes par jour (10000 pour les utilisateurs de l'API avancée)
Comment travailler avec l'API ?
L'utilisation de Postman
D'après notre expérience, la plupart des gens sont principalement intéressés par le téléchargement des données présentées sur la page web de chaque segment de route spécifique, afin de pouvoir jouer avec les chiffres eux-mêmes. Dans cet exemple, voici comment vous pouvez utiliser l'API :
Téléchargez et installez l'application Postman (il s'agit d'une application simple, gratuite et multiplateforme permettant de développer et d'utiliser des appels d'API) à l'adresse suivante : https://www.getpostman.com/.
Ouvrez Postman et, dans l'espace de travail vide, cliquez sur l'onglet "+" (à gauche de l'onglet "...").
Effectuez un appel POST (changez GET en POST devant le champ de saisie vide), puis écrivez l'URL de l'appel API sélectionné (dans notre cas, l'appel "Traffic API") dans le champ de saisie sous la forme suivante : "https://telraam-api.net/v1/reports/traffic" (sans les guillemets).Sous l'adresse, cliquez sur l'onglet "Headers" et dans le champ "Key", écrivez "X-Api-Key". Saisissez ensuite votre jeton API personnel dans le champ "Value". Si elles ne sont pas encore présentes par défaut, assurez-vous que les entrées "Content-Type" et "application/json" sont également ajoutées de manière similaire. Après cette étape, votre fenêtre postman devrait ressembler à ceci (mais avec votre jeton d'API)
Enfin, vous pouvez spécifier les paramètres de votre requête API dans l'onglet "Body" (à côté de l'onglet "Headers"). Ici, en suivant le format spécifié ci-dessous, vous pouvez saisir l'identifiant du segment qui vous intéresse (dans le champ "id", où l'identifiant - ou ID du segment - peut être trouvé dans l'adresse web de chaque segment sur le site web de Telraam, par exemple, https://telraam.net/fr/location/347295/2019-11-26/2019-12-10 -> l'ID du segment est alors 347295), et la date et l'heure de début et de fin (en UTC / Temps Universel Coordonné) de l'intervalle qui vous intéresse (maximum 1 an à la fois). Assurez-vous que "raw" est sélectionné comme format au-dessus du champ de saisie.
Ensuite, en cliquant sur le gros bouton bleu "Send", vous pouvez envoyer votre demande. En fonction de la quantité de données présentes sur le serveur Telraam pour la période demandée, vous recevrez en quelques secondes une réponse contenant les données.
Pour bien comprendre tous les champs de données renvoyés, veuillez consulter les deux liens (" et Documentation) qui ont déjà été mis en lien ci-dessus: "Compréhension de l'API Telraam" et "Documentation"
La programmation c'est pour les geeks et vous avez juste besoin de quelques données ?
Avec notre documentation API interactive, lisible par les machines et les humains, vous pouvez essayer (et utiliser) tous nos points de terminaison API (auxquels vous avez accès) simplement depuis un navigateur ! Sélectionnez une API, cliquez sur Try it out, fournissez votre token API dans le champ X-Api-Key et amusez-vous !
Utiliser un langage de programmation pour interagir avec l'API REST
Sinon, vous pouvez utiliser de nombreux langages de programmation pour interagir avec notre API REST. Le snippet Python suivant devrait vous apprendre comment obtenir un DataFrame pandas, ou même juste un fichier .csv en texte brut depuis notre point de terminaison API de trafic populaire :
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')Exemple : Données "Vitesse par heure"
C'est une des statistiques qui est souvent demandée par nos utilisateurs.
Via le site web, via le tableau de bord, et via l'excel dans votre tableau de bord vous ne pouvez pas voir les données par heure.
Cela n'est possible que via l'API avec la méthode POST traffic. Vous recevrez alors une réponse comprenant car_speed_hist_0to70plus et car_speed_hist_0to120plus. Ces champs contiennent les histogrammes de vitesse avec une résolution de 5 km/h et 10 km/h, respectivement. Pour en savoir plus sur cette méthode API, consultez le lien suivant : API Documentation Data "Speed per hour".
