KPI data on a corridor during a specific time range

How to get a KPI for a corridor over a specific time range

The use case is focused on getting KPI data on a specific corridor, over a specific time range, to analyse performance metrics and understand trends and patterns over specific time periods.

First step

The endpoint is:

GET
https://api.myptv.com/kpi/{type}/get

Path parameter

The type parameter specifies the output data type:

overall: returns aggregated results over the entire time interval.
detailed: provides segment-level detailed results.

Query parameters

For additional details, see API Reference.

Parameter	Required	Note	Example
kpid	YES	Identifier of the KPI.	Not applicable
fromTime	NO	Start of the time interval.	2024-12-01T00:00:00Z
toTime	NO	End of the time interval. The maximum interval is: 1 year for overall results (type=overall) 1 day for detailed results (type=detailed)	2024-12-02T23:59:59Z
timeAggregation	NO	Possible values: MINUTES_5 MINUTES_15 MINUTES_30 HOURS_1 DAYS_1	HOURS_1

Example of request

GET https://api.ptvgroup.tech/hda/v1/kpi/overall/get?kpiId=8e144767b57448b69c920f39ec685e1b&fromTime=2025-01-01T00:00:00Z&toTime=2025-01-07T23:59:59Z&timeAggregation=HOURS_1 HTTP/1.1

Host: api.ptvgroup.tech

Authorization: apiKey YOUR_API_KEY

Accept: application/json

Example of response

{
    "meta": {
       "kpiId": "d3377835-aa86-4873-93a8-a7936aff6dcd",
       "minT": "2025-01-03T16:00:00Z",
       "maxT": "2025-01-03T17:00:00Z",
       "result_size": 2,
       "defaultValue": 25.603634,
       "pathLength": 30.454311
    },
    "data": [
        {
           "timestamp": "2025-01-03T16:00:00Z",
           "value": 23.4687476,
           "unusualValue": 56.10981,
           "averageValue": 46.37683,
           "status": "OK"
        },
        {
           "timestamp": "2025-01-03T17:00:00Z",
           "value": 21.816655124999997,
           "unusualValue": 56.088036,
           "averageValue": 43.26787000000001,
           "status": "OK"
        }
    ]
}

Second step

On the basis of the response, you can analyze the KPI data to identify trends and patterns of the corridor over the specified time range.

Best practices

You can choose the aggregation level that fits your analysis needs:

Fine-grained value (MINUTES_5) for detailed analysis.
Coarse-grained value (DAYS_1) for long-term trends.

The available data formats are:

JSON for easy integration and parsing.
Compressed CSV for large datasets to reduce bandwidth and storage.

Use Case