Événements routiers

Chaque requête nécessite une clé API; voir Authentification.

Trois points d'accès sur un même ensemble de données :

Colombie-Britannique et Alberta. Voir Couverture pour ce que cela inclut et n'inclut pas.

curl "https://api.unmap.dev/closures?key=$UNMAP_API_KEY&limit=3"

{
  "data": [
    {
      "id": "um:road:ca-bc:drivebc.ca%2FRIDE-101916",
      "source_id": "drivebc.ca/RIDE-101916",
      "jurisdiction": "CA-BC",
      "type": "closure",
      "severity": "major",
      "condition": "closed",
      "description": "Bridge construction at Kicking Horse Drive. Starting Fri Sep 25. All day, every day. Closed for repairs.",
      "roads": [
        { "name": "Other Roads", "direction": "both", "closed": true, "from": "Kicking Horse Drive", "condition": "closed" }
      ],
      "geometry": { "type": "Point", "coordinates": [-116.96, 51.29] },
      "source_updated_at": "2026-09-17T08:06:31-07:00",
      "unmap_updated_at": "2026-09-17T15:55:16.508Z",
      "source": "roads.drivebc-open511"
    }
  ],
  "meta": {
    "source": "Government of British Columbia, DriveBC: DriveBC Open511 events",
    "status": "current",
    "attribution": "Contains information licensed under the Open Government Licence - British Columbia"
  }
}

La description reste dans la langue du producteur : DriveBC ne publie qu'en anglais, et traduire le texte d'un organisme routier reviendrait à réécrire un avis de sécurité.

import { Unmap } from "@unmap/sdk";
const unmap = new Unmap({ key: process.env.UNMAP_API_KEY! });
 
const { data, meta } = await unmap.roads.closures({ jurisdiction: "CA-BC" });
if (meta.unavailable?.length) {
  // Une province n'a pas pu être jointe. Une liste `data` vide n'est PAS « rien n'est fermé ».
  console.warn(meta.unavailable);
}

unmap.roads.incidents(), .closures() et .conditions() acceptent la même requête que les points d'accès.

Paramètres

Les trois points d'accès prennent les mêmes.

Les résultats sont triés du plus grave au moins grave, puis du plus récemment modifié.

Quatre décisions à connaître

Une fermeture signifie que le producteur a dit « fermé ». Elle est lue depuis l'état de route en amont et de nulle part ailleurs. La catégorie de l'événement dit pourquoi une route est touchée, jamais si elle est fermée : le jour de la livraison, les 16 fermetures de la Colombie-Britannique se répartissaient entre des événements de type chantier et incident, et plusieurs événements de chantier décrivaient de brèves fermetures en prose tout en déclarant toutes les voies ouvertes. Ceux-là n'apparaissent pas dans /closures.

La description du producteur est retournée mot pour mot. Nos catégories sont une projection avec perte de la taxonomie d'autrui, et la phrase dont un conducteur a réellement besoin se trouve dans la prose. Si notre catégorie et la description se contredisent, croyez la description et signalez-le-nous.

Une valeur amont non reconnue devient unknown, jamais une supposition. Un flux qui inventerait SNOW_SQUALL ressort en unknown avec sa description intacte plutôt que d'être arrondi vers weather parce que le mot évoque la météo.

/road-conditions est maigre, et dry est rare. L'état de route d'Open511 décrit la disponibilité des voies, pas la surface. Des voies ouvertes ne prouvent pas une chaussée sèche : unmap répond unknown plutôt que d'inventer une mesure que personne n'a prise.

Ces données sont interrogées en direct, non ingérées selon un calendrier. Un événement routier vieux d'une heure ne vaut rien. La Colombie-Britannique est interrogée à chaque requête derrière un cache de 60 secondes. L'Alberta est plutôt interrogée toutes les cinq minutes, car sa clé d'API permet dix appels par minute pour tout unmap : le trafic des clients ne doit pas l'atteindre. La réponse indique l'âge de chaque flux albertain :

{ "meta": { "polled": [{ "jurisdiction": "CA-AB", "feed": "events", "polled_at": "2026-10-09T17:05:00.000Z", "age_seconds": 140, "max_age_seconds": 900 }] } }

Un flux albertain qui n'a pas été interrogé depuis 15 minutes n'est pas servi. Il figure plutôt dans meta.unavailable.

meta.status est calculé à partir de ce qui vient d'être récupéré : current normalement, stale quand la source répond mais que rien n'y a bougé depuis plus longtemps que la fenêtre du flux (une heure pour la Colombie-Britannique, six pour le flux albertain, plus lent, et la plus courte des deux quand les deux sont demandées), ce qui signale habituellement un problème chez elle plutôt qu'une province exceptionnellement calme.

Quand une juridiction est injoignable, la réponse le dit au lieu de retourner une liste vide :

{
  "data": [],
  "meta": {
    "status": "partial",
    "unavailable": [{ "jurisdiction": "CA-BC", "reason": "upstream timed out" }]
  }
}

Cette distinction compte surtout sur /closures, où une liste vide se lit comme « rien n'est fermé » pour quelqu'un qui décide de prendre la route. Si toutes les juridictions demandées échouent, le code de statut est 503.

Deux provinces sur treize.

La Colombie-Britannique (DriveBC, Open511) et l'Alberta (511 Alberta) sont couvertes. L'Alberta exige une clé d'API. Si la clé venait à manquer, la juridiction serait écartée avec un motif explicite plutôt qu'interrogée sans elle, et la réponse le dirait :

{ "meta": { "status": "partial", "unavailable": [{ "jurisdiction": "CA-AB", "reason": "ALBERTA_511_KEY is not configured" }] } }

Les deux producteurs ne se ressemblent pas, et les différences apparaissent dans la réponse :

• L'Alberta déclare la fermeture explicitement. IsFullClosure est un booléen que le producteur renseigne. La Colombie-Britannique n'a aucun champ équivalent : la fermeture y est lue depuis l'état de la route et de nulle part ailleurs.
• L'Alberta rapporte l'état de la chaussée; la Colombie-Britannique non. L'état de route d'Open511 décrit la disponibilité des voies : /road-conditions est donc maigre pour la Colombie-Britannique par conception. L'Alberta publie un flux distinct d'état des routes hivernales avec de véritables états de chaussée, ce qui fait que ce point d'accès répond pour l'Alberta.
• La gravité albertaine est généralement absente. 270 des 276 événements n'en portaient aucune à la première mesure. Nous indiquons unknown plutôt que de retomber sur « mineur », car une province non renseignée n'est pas une province calme.

Open511 est une spécification et non l'invention d'une seule province : une autre juridiction qui la sert ouvertement est une entrée de configuration, pas du code nouveau. Les fermetures de l'Ontario sont récupérées toutes les cinq minutes pour la couche de restrictions du routage, mais ne sont pas servies ici.

Le vocabulaire hivernal de l'Alberta n'est pas encore cartographié

Les termes d'état ont été échantillonnés en septembre, quand 1 228 des 1 237 segments indiquaient Bare Dry. Les termes hivernaux de l'Alberta n'étaient pas observables et ne figurent donc pas dans la correspondance : une valeur non reconnue devient unknown plutôt que d'être devinée d'après les mots qu'elle contient. Un nouvel échantillonnage aura lieu en hiver. D'ici là, /road-conditions sous-déclare l'Alberta précisément à la saison où cela compte le plus, ce qui est une lacune annoncée et non silencieuse.

Autres limites :

• Routes provinciales seulement. Les rues municipales ne figurent dans aucun des deux flux.
• La Colombie-Britannique plafonne à 500 événements, sans pagination. Elle en comptait 286 à la mesure : le plafond ne contraint donc pas aujourd'hui.
• Les segments albertains secs sont écartés de /road-conditions plutôt que retournés, quelle que soit leur visibilité, sauf si le producteur l'indique Poor (c'est reduced_visibility). Douze cents enregistrements disant que la route va bien enterreraient la poignée qui ne va pas.
• Le routage n'évite pas les fermetures. Rien dans /route n'est encore affecté. Injecter les fermetures confirmées dans le graphe de routage est une étape distincte et n'est pas faite.

Prochaines étapes

• Couverture pour les provinces couvertes et ce qui manque à chacune.
• L'API d'itinéraires pour ce que le calcul d'itinéraire sait, ou non, des fermetures.
• Erreurs pour le contrat d'échec.