Predicta API · v1.0.0
Construire avec le trafic de Tana
L'API Predicta expose le trafic temps réel d'Antananarivo en GeoJSON (RFC 7946), converti depuis des tuiles vectorielles. Trois points d'entrée trafic, un catalogue de quartiers, une clé par application. Aucune persistance : chaque appel est un instantané best-effort de la ville.
Démarrage
L'API est accessible à l'URL suivante. Chaque requête (hors /ping) exige une clé API dans l'en-tête X-API-Key.
curl
curl https://api.predicta.mg/ping
Dans cette application, le navigateur ne contacte jamais l'API directement : un proxy Next.js (/api/predicta/*) détient la clé côté serveur et relaie la fraîcheur via les en-têtes X-Predicta-*.
Authentification
Une clé API est attribuée à chaque application enregistrée. Les clés sont des secrets : elles ne doivent jamais être embarquées dans un client public, ni commitées. En cas de clé absente ou invalide, l'API répond 401.
requête authentifiée
curl -H "X-API-Key: pk_live_••••••••" \ https://api.predicta.mg/quartiers?q=ana
Trafic
GET/traffic
État du trafic live de toute la ville (13 tuiles, ~50 Mo en pratique). Réservé aux usages rares : préférez le quartier ou la zone.
Toujours 200 en cas de résultat partiel (en-tête X-Predicta-Partial) ;401 si la clé manque.
PUT/traffic/zone
Trafic autour d'un centroïde (disque, 2 tuiles attendues). Le corps porte le centroïde, nom du lieu au plus proche.
body
{ "name": "Analakely", "lon": 47.52688, "lat": -18.90793 }GET/traffic/quartier/{quartierId}
Trafic précis d'un quartier (grille polygonale, 1 à 4 tuiles). Réponse mise en cache 45 s (stale-while-revalidate).
En-têtes : X-Predicta-Age (ms, si servi du cache), X-Predicta-Fallback (repli disque centroïde non filtré), X-Predicta-Partial.404 si le quartier est inconnu.
Quartiers
GET/quartiers?q=
Recherche de quartiers (insensible à la casse, tri alphabétique). q vide ou absent renvoie les 372 quartiers.
réponse
[ { "name": "Analakely", "lon": 47.52688, "lat": -18.90793 } ]L'identifiant du quartier (clé de /traffic/quartier) n'est pas exposé ici : il est présent sur chaque segment trafic, dans properties.quartierId. Le catalogue complet (avec ids) est embarqué dans l'application.
GeoJSON
Les réponses trafic sont des FeatureCollections. Un segment est une ligne (LineString ou MultiLineString) portant la vitesse observée et le ratio de congestion.
feature
{
"type": "Feature",
"properties": {
"name": "Avenue de l'Indépendance",
"quartierId": "rel_999999",
"speed": 32,
"rate": 0.9
},
"geometry": {
"type": "LineString",
"coordinates": [ [47.526, -18.909], [47.529, -18.907] ]
}
}rate est le ratio vitesse observée / vitesse libre (signal de congestion, non dérivable de la vitesse seule). Les propriétés name et quartierId sont optionnelles : la source peut ne pas les fournir pour certains segments.
Fraîcheur & erreurs
L'API est best-effort : si une tuile échoue, elle est ignorée et la réponse reste un GeoJSON valide, signalé par X-Predicta-Partial. Le cache mémoire du quartier sert la donnée pendant sa revalidation (X-Predicta-Age). L'application traduit ces états en texte — jamais en badges :
- Trafic actualisé il y a 14 s
- Certaines routes manquent en ce moment.
- Connexion au trafic impossible — nouvelle tentative.
Limites & confidentialité
L'API ne persiste rien et ne fournit ni historique, ni ETA, ni prédiction : chaque appel est un instantané. Les géométries proviennent d'OpenStreetMap (© OpenStreetMap contributors). Les clés sont la seule barrière d'authentification — toute logique d'autorisation doit être vérifiée côté serveur.