Create a KPI instance

This endpoint creates a KPI instance from a specific template (see → Optima KPI methodology).

According to the specific KPI Template, you need to set some dynamic attributes (see → Dynamic attributes associated to KPI Templates).

Authentication phase

Before using the endpoint, you must run the authentication phase (→ Login).

After the authentication, a session opens and a valid session token persists until:

Request

POST 

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-kpi/kpi/api/instance

Request resource

Not applicable.

Request parameters

Not applicable.

Request content-type

application/JSON

Request body (payload)

JSON object describing all necessary information to create an instance.

For a description of the JSON object attributes, please see → JSON structure for a KPI.

Response status

HTTP status Description

200 OK

The KPI instance is created.

400 Bad request

Several conditions can be classified under this code.

Main examples:

  • The JSON object is not valid (not well formed).
  • Missing or not existing template; not valid or not consistent attribute with the template.
  • The KPI ID is present in the request.

Generally present where the API has been called with wrong arguments.

404 Not found

The instance ID does not exists.

Response content-type

application/JSON

Response output

A JSON object with a KPI instance identifier added to all elements indicated in the request.

In case of error 400, the output is formatted as a couple:

<parameter_name>: <error description>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-kpi/kpi/api/instance

Request body (payload)

{
    "templateId": <templateId>,
    "name": "<name>",
    "editable": <true/false>,
    "enabled": <true/false>,
    "description": "<description>",
    "category": "<category>",
    "tags": "<tags>",
    "range": {
        "min": <min>,
        "max": <max>
    },
    "schedule": <schedule>,
    "durablePoints": <true/false>,
    "pointDuration": <point_duration>,
    "templateId": <template_id>,
    "computationTypeCode": "<TRIGGERED/SCHEDULED>",
    "dynamicAttributes": [
        {
            "code": "<dynamic_attribute_code>",
            "value": "<dynamic_attribute_value>"
        },
        {
            "code": "<dynamic_attribute_code>",
            "value": "<dynamic_attribute_value>"
        },
        {...other element...}
    ],
    "affectedLinks": [
        {
            "tail": <link_tail>,
            "idno": <link_idno>,
            "order": <link_order>
        },
        {
            "tail": <link_tail>,
            "idno": <link_idno>,
            "order": <link_order>
        },
        {...other element...}
    ],
    "affectedStreets": [
        {
            "tail": <strt_tail>,
            "idno": <strt_idno>,
            "order": <strt_order>
        },
        {
            "tail": <strt_tail>,
            "idno": <strt_idno>,
            "order": <strt_order>
        },
        {...other element...}
    ],
    "affectedLines": [
        {
            "idno": <line_idno>,
            "order": <line_order>
        },
        {
            "idno": <line_idno>,
            "order": <line_order>
        },
        {...other element...}
    ],
    "affectedStops": [
        {
            "idno": <stop_idno>,
            "order": <stop_order>
        },
        {
            "idno": <stop_idno>,
            "order": <stop_order>
        },
        {...other element...}
    ]
}

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-kpi/kpi/api/instance

Request body (payload)

{
    "templateId": 11,
    "name": "Test KPI instance",
    "description": "Number of Vehicles on the Network",
    "durablePoints": false, 
    "editable": true,
    "enabled": true,
    "category": "Category TEST",
    "tags": "asa",
    "range": {
        "min": 0,
        "max": 30
    },
    "pointDuration": 3000,
    "schedule": 60,
    "computationTypeCode":"TRIGGERED",
    "dynamicAttributes": [
        {
            "code": "fore",
            "value": "1800"
        },
        {
            "code": "onlyQueue",
            "value": "nveh"
        },
        {
            "code": "shortTermForecastKpi",
            "value": "true"
        }
    ],
    "affectedLinks":[
        {
            "tail":3119676,
            "idno":3503373,
            "order":1
        },
        {
            "tail":2788659,
            "idno":3503359,
            "order":2
        }
    ]
}

Additional Notes

The instance is:

  • Editable ("editable": true) and ready to be calculated ("enabled": true).
  • Built on three dynamic attributes and two specific links of the network.