With the Sentinel service you can get the congestions detected on your Flows instance.
Follow the steps on this page to get started with Sentinel API.
API endpoint
You can use this endpoint to get the traffic congestions currently detected for your product instance.
https://api.ptvgroup.tech/flows/realtime-congestions/v1/realtime/get-congestions
Request
In this case, the request matches the endpoint shown above.
Alternatively, you can choose one of the following options to send your request.
cURL
curl.exe -i "https://api.ptvgroup.tech/flows/realtime-congestions/v1/realtime/get-congestions" -H "ApiKey: YOUR_API_KEY" -H "Accept: application/json"PowerShell
$headers = @{ "ApiKey" = "YOUR_API_KEY" }
$uri = "https://api.ptvgroup.tech/flows/realtime-congestions/v1/realtime/get-congestions"
$response = Invoke-RestMethod -Uri $uri -Method Get -Headers $headers
$response | ConvertTo-Json -Depth 10
Response
The response contains the congestions associated with your product instance:
...
{
"congestions": [
{
"uuId": "3f6c2a9e-1b7d-4c55-9a0e-2d8f4b1c7e01",
"parentUuIds": [],
"id": 1,
"startingTimestampEpoch": 1759305300,
"timestampEpoch": 1759305600,
"type": "Congestion",
"shape": "MULTILINESTRING ((12.5432 41.8711, 12.5448 41.8702), (12.5448 41.8702, 12.5461 41.8695))",
"speedDistributionByStreet": [],
"usualityByStreet": [0.25, 0.43],
"severityByStreet": [0.7, 0.54],
"ffSpeedByStreet": [50.0, 50.0],
"edges": [[123456, 789], [123457, 790]],
"description": null,
"severity": 0.65,
"usuality": 0.31,
"lengthM": 1270.5,
"lengthByHierarchy": { "2": 850.0, "4": 420.5 },
"usualityByHierarchy": { "2": 0.25, "4": 0.43 },
"name": "Via Tuscolana",
"severityTrend": null,
"sizeTrend": null,
"piid": "my-product-instance"
}
]
}
...
Main elements of the response:
- ETag (header): Version of this detection result. Keep it and send it back in If-None-Match. See also relevant terms LINK.
- congestions: The congestions detected in the latest detection cycle. See also relevant terms LINK.
- id, uuId: Identify a congestion, reassigned at every detection cycle.
- timestampEpoch: Time of the traffic snapshot associated to the detection (Unix epoch, seconds). Same value for all congestions.
- startingTimestampEpoch: Start of the detection window (Unix epoch, seconds).
- type: Always set to "Congestion".
- shape: Geometry as WKT `MULTILINESTRING`, WGS84 (EPSG:4326), longitude latitude order. null value if no geometry can be resolved.
- edges: Road-network edges as [streetId, fromNodeId] pairs.
- name: Street or location name for display. null value if no edge has a name.
- severity: Overall severity, 0 (free flow) to 1 (high congestion). See also relevant terms LINK.
- usuality: How expected the congestion is, 0 (highly unusual) to 1 (fully usual). Below 0.5 is commonly considered as unusual. See also relevant terms LINK.
- lengthM: Total length in meters.
- severityByStreet, usualityByStreet, ffSpeedByStreet: Per-edge values (severity 0–1, usuality 0–1, free-flow speed in km/h).
- lengthByHierarchy, usualityByHierarchy: Length (meters) and usuality per functional road class; keys are road class codes.
- piid: The product instance associated with your credentials.
- parentUuIds, speedDistributionByStreet, description, severityTrend, sizeTrend: Reserved for a future use; not populated yet.
Additional main notes
If you are not enabled to use the Sentinel service, every endpoint call returns 403 GENERAL_FORBIDDEN. In this case you must contact PTV to purchase the Sentinel service.
The rate limit of the Sentinel service is 60 requests per minute per API key.
Results older than 15 minutes (900 seconds) are not served. If detection has stopped, the call returns 503 GENERAL_SERVICE_UNAVAILABLE.
The endpoint works in read only mode; it takes no parameters except the optional If-None-Match header parameter.
You need to get a Demo or Real instance of PTV Flows before using the API Key.
In order to request a PTV Flows instance, please use the contact form.
Once you have access to the instance, click the API Key button.