Create a KPI - PTV Flows

How to create a KPI

When you create a KPI, you are creating a "location" associated to a "shape".

The building of a shape is based on the format Well Known Text (WKT).

Each WKT object follows a fixed structure. The most common structures are:

Point: POINT(20 40) — Represents a single X and Y position separated by a space.
Line: LINESTRING(0 0, 20 30, 20 60) — A series of connected points, separated by commas.
Polygon: POLYGON((0 0, 20 0, 20 20, 0 20, 0 0)) — A closed area. Note that the first and last points must coincide to close the figure.

For additional details on the WKT format, see here.

You can create a KPI based on different templates.

If you want to know which are the available templates, you can use the endpoint:

GET
https://api.ptvgroup.tech/kpieng/v1/template/all

Now we are going to create a KPI instance base on the template EXPECTED_TRAVEL_TIME.

POST
https://api.staging.ptvgroup.tech/kpieng/v1/instance?template=EXPECTED_TRAVEL_TIME

An example of payload:

{
  "name": "ETT_+0_on_test location",
  "notes": "",
  "kpiInstanceParameters": {
    "parameters": {
      "timetostart": 0
    }
  },
  "location": {
    "name": "test location",
    "entities": [
      {
        "strt": 80595,
        "fsnd": 6056,
        "order": 0,
        "startProgressive": 0.3492652088236855,
        "endProgressive": 1
      },
      {
        "strt": 63967,
        "fsnd": 114130,
        "order": 1,
        "startProgressive": 0,
        "endProgressive": 1
      },
      {
        "strt": 63968,
        "fsnd": 89902,
        "order": 2,
        "startProgressive": 0,
        "endProgressive": 1
      },
      {
        "strt": 80594,
        "fsnd": 125293,
        "order": 3,
        "startProgressive": 0,
        "endProgressive": 1
      },
      {
        "strt": 55646,
        "fsnd": 10877,
        "order": 4,
        "startProgressive": 0,
        "endProgressive": 1
      },
      {
        "strt": 31184,
        "fsnd": 59249,
        "order": 5,
        "startProgressive": 0,
        "endProgressive": 0.8042797774757235
      }
    ],
    "shape": "LINESTRING(12.460116 41.973983, 12.460410 41.973840, 12.460510 41.973660, 12.460450 41.973420, 12.459890 41.973060, 12.459570 41.972960, 12.457820 41.972460, 12.457000 41.972740, 12.456440 41.972700, 12.456340 41.972730, 12.455900 41.973070, 12.455450 41.973230, 12.454480 41.972670, 12.453880 41.972190, 12.453770 41.971620, 12.453370 41.971500, 12.452830 41.971720, 12.452670 41.972100, 12.452870 41.972480, 12.453010 41.972850, 12.452770 41.972980)",
    "locationId": null,
    "locationType": "PATH"
  },
  "kpiId": null,
  "thresholdsDefinition": {
    "thresholdsValues": {
      "warningThreshold": 140,
      "criticalThreshold": 180
    },
    "kpiThresholdsReference": "FREE_FLOW"
  }
}

In the payload you can recognize these main blocks:

The name of the KPI:
"name": "ETT_+0_on_test location"
The name of the location:
"name": "test location"
The identifier of the KPI (kpiId) and of the location (locationId): in the creation payload, must be both set to null.
A sequence of streets, that are the elements of the location, where any street is described by this structure:
{
"strt": 80595,
"fsnd": 6056,
"order": 0,
"startProgressive": 0.3492652088236855,
"endProgressive": 1
}
The shape associated to the location

The response is shown below:

{
  "name": "ETT_+0_on_test location",
  "notes": "",
  "kpiInstanceParameters": {
    "parameters": {
      "timetostart": 0
    }
  },
  "location": {
    "name": "test location",
    "shape": "LINESTRING (12.460116 41.973983, 12.46041 41.97384, 12.46051 41.97366, 12.46045 41.97342, 12.45989 41.97306, 12.45957 41.97296, 12.45782 41.97246, 12.457 41.97274, 12.45644 41.9727, 12.45634 41.97273, 12.4559 41.97307, 12.45545 41.97323, 12.45448 41.97267, 12.45388 41.97219, 12.45377 41.97162, 12.45337 41.9715, 12.45283 41.97172, 12.45267 41.9721, 12.45287 41.97248, 12.45301 41.97285, 12.45277 41.97298)",
    "locationId": "f492cbfc-8d90-4001-a853-dece6e102764",
    "locationType": "PATH"
  },
  "kpiId": "7b4b6966-5057-4f12-8452-246dced43eaa",
  "thresholdsDefinition": {
    "thresholdsValues": {
      "warningThreshold": 140,
      "criticalThreshold": 180
    },
    "kpiThresholdsReference": "FREE_FLOW"
  },
  "template": "EXPECTED_TRAVEL_TIME",
  "direction": "DECREASING",
  "visualizationModes": [
    "HISTORICAL_PROFILE",
    "MULTIPLE_HISTORICAL_PROFILE",
    "GAUGE",
    "CARPET"
  ],
  "unitOfMeasure": "MINUTES"
}

The description of all elements involved in the payload and in the response (both in JSON format) can be found in API Reference.

The KPI instance just created is completely identified by these main elements:

name
kpiId
template
locationId
shape

Use Case

How to create a KPI