Congestions evaluation on major roads
An alerting service separates routine congestion (such as the daily rush hour) from unexpected events (such as incidents) and gives priority to congestions on higher road classes.
The general workflow is:
The alerting service calls https://api.ptvgroup.tech/flows/realtime-congestions/v1/realtime/get-co….
For each congestion consider:
- Usuality (< 0.5 → unusual).
- Severity.
- lengthByHierarchy / usualityByHierarchy to see which road classes are affected and whether that part is unusual.
- It raises an alert for unusual congestions, ranked by severity and road class, and ignores routine ones.
The endpoint is:
https://api.ptvgroup.tech/flows/realtime-congestions/v1/realtime/get-congestionsPath parameter
Not applicable.
Query parameters
Not applicable.
Example of request
https://api.ptvgroup.tech/flows/realtime-congestions/v1/realtime/get-congestionsHost: api.ptvgroup.tech
Authorization: -H "ApiKey: YOUR_API_KEY"
Accept: application/json
Response
HTTP 200 - OK
...
{
"congestions": [
{
"id": 1,
"uuId": "3f6c2a9e-1b7d-4c55-9a0e-2d8f4b1c7e01",
"type": "Congestion",
"timestampEpoch": 1759305600,
"name": "Via Tuscolana",
"severity": 0.65,
"usuality": 0.31,
"lengthM": 1270.5,
"lengthByHierarchy": { "2": 850.0, "4": 420.5 },
"usualityByHierarchy": { "2": 0.25, "4": 0.43 },
"edges": [[123456, 789], [123457, 790]],
"severityByStreet": [0.7, 0.54],
"usualityByStreet": [0.25, 0.43],
"ffSpeedByStreet": [50.0, 50.0],
"shape": "MULTILINESTRING ((12.5432 41.8711, 12.5448 41.8702), (12.5448 41.8702, 12.5461 41.8695))",
"piid": "my-product-instance"
},
{
"id": 2,
"uuId": "a1d4e7b0-5c28-4f93-8e6a-0b7c2d9f4e15",
"type": "Congestion",
"timestampEpoch": 1759305600,
"name": "Via Appia Nuova",
"severity": 0.48,
"usuality": 0.92,
"lengthM": 640.0,
"lengthByHierarchy": { "5": 640.0 },
"usualityByHierarchy": { "5": 0.92 },
"edges": [[223344, 1201]],
"severityByStreet": [0.48],
"usualityByStreet": [0.92],
"ffSpeedByStreet": [30.0],
"shape": "MULTILINESTRING ((12.5301 41.8655, 12.5352 41.8619))",
"piid": "my-product-instance"
}
]
}
...
In the response are shown two congestions.
The main elements of the response are:
- Usuality:
- Usuality 1 (Id=1): 0.31 → unusual (alert).
- Usuality 2 (Id=2): 0.92 → routine (no alert).
- Severity:
- Severity 1: 0.65 → means traffic moves below free-flow speed.
- Severity 2: 0.48 → can be considered not meaningful.
- lengthByHierarchy: Congested meters per functional road class. Congestion 1 has 850 m on class 2 and 420.5 m on class 4.
This quick analysis identified a single real congestion with Id=1, therefore congestion 1.
The event was detected due to its high severity (Severity 1 = 0.65) and low usuality (Usuality 1 = 0.31), indicating an unusual traffic situation. This combination triggers an alert.