Time series data for a specific network element

How to get a specific data time series for a specific network element

The use case is focused on getting a speed time series for a single network segment, over a specific time range. This endpoint can be used to monitor the performance on that segment to identify typical temporal patterns.

First step

The endpoint is:

GET /time-series/get

Path parameter

Not applicable.

Query parameters

For additional details, see API Reference.

Parameter	Required	Note	Example
streetIdno	NO	streetIdno is a model base street identifier (to be used with streetFromNode).	239600
streetFromNode	NO	streetFromNode is a model base street from node identifier (to be used with streetIdno).	198070
streetCode	NO	Internal street code identifier.
openLrCode	NO	OpenLR street code identifier.
fromTime	NO	Start of the time interval.	2025-01-02T08:06:00Z
toTime	NO	End of the time interval.	2025-01-07T08:06:00Z
timeAggregation	NO	Possible values: MINUTES_5 MINUTES_15 MINUTES_30 HOURS_1 DAYS_1	HOURS_1

One of the listed street identifiers is required:

(streetIdno, streetFromNode)
openLrCode
streetCode

Example of request

GET https://api.ptvgroup.tech/hda/v1/time-series/get?streetIdno=239600&streetFromNode=198070&fromTime=2025-01-02T08:06:00Z&toTime=2025-01-07T08:06:00Z&timeAggregation=HOURS_1 HTTP/1.1

Host: api.ptvgroup.tech

Authorization: apiKey YOUR_API_KEY

Accept: application/json

Example of response

{
    "metaData": {
        "networkData": [
            {
                "idno": 239600,
                "fromNode": 198070,
                "openLr": "Cwi0eR203iOOAAAN/+UjHg==",
                "functionalRoadClass": 4,
                "name": "Viale di Coccia di Morto",
                "mapVersion": "20241112133222"
            }
        ],
        "requestInfo": {
            "streetCode": "1029074164319670",
            "retrievedAt": "2025-01-15T18:06:00.721228400Z",
            "interval": "01:00:00",
            "valueType": "speed"
        }
    },
    "timeSeries": {
        "speed": [
            28.384615,
            25.916666,
            ... other values
            24.083334
        ],
        "fdat": [
            "2025-01-02T08:06:00Z",
            "2025-01-02T09:06:00Z",
            ... other values
            "2025-01-07T07:06:00Z"
        ]
    }
}

Second step

On the basis of the response, you can:

Plot the speed or flow over time to visualize trends.
Identify peak traffic hours, recurring patterns, or anomalies.
Compare data across different time periods for comparative analysis.

Best practices

About time constraints:

Use shorter intervals for detailed analyses during specific events.
Use longer intervals to observe general trends over weeks or months.
Adjust the aggregation to match the granularity needed for your analysis.

Use Case