Swarco Aineisto rajapintapalvelu tarjoaa avoimen JSON REST -rajapinnan, jonka dokumentaatio löytyy tämän artikkelin lisäksi osoitteesta https://aineisto.swarco.fi/docs.
# Omnia WEB API Documentation [14.04.2021]
# Introduction
What does your API do?
Omnia WEB API are RESTFUL web api. It exposes information from Omnia system about controllers, detectors & their traffic and occupany measurements.
HTTP method GET are supported for Omnia WEB API endpoint. The response data representation are in JSON format.
# Overview
How to start using the Omnia WEB API's?
1) Get you authorization token from https://aineisto.swarco.fi/authorization .
2) Set authorization into header request. (see # Authorization section for example) .
3) Your preferred way for accessing; start from https://aineisto.swarco.fi/api/help .
4) If you are reading this document you already are fimiliar with https://aineisto.swarco.fi/docs .
Ok I can see some api routes from https://aineisto.swarco.fi/api/help now what ?
Here below is given short example and description from each api routes:
◼ "https://aineisto.swarco.fi/api/help/" -> GET list of all available routes.
"/api/": [
"/api/help/",
"/api/cities/",
"/api/omniacode/controller/",
"/api/omniacode/:omniacode?/controller/",
"/api/omniacode/:omniacode?/controller/:id?.:starttime?.:endtime?",
"/api/omniacode/:omniacode?/controller/:id?/:detectorid?.:starttime?.:endtime?"
]
◼ "https://aineisto.swarco.fi/api/cities/" -> GET list of availble cities with omnia code e.g. below
{
"OmniaName": "Lahti",
"OmniaCode": 2
}
◼ "https://aineisto.swarco.fi/api/omniacode/controller/" -> GET list of all controllers e.g. below.
{
"OmniaCode": 2,
"OmniaName": "Lahti",
"ControllerId": 100030,
"ControllerDescription": "Hämeenlinnantie - Ala-Okeroistentie",
"ControllerExternalCode": "R702"
},
{
"OmniaCode": 2,
"OmniaName": "Lahti",
"ControllerId": 100031,
"ControllerDescription": "Hämeenlinnantie - Messiläntie",
"ControllerExternalCode": "R703"
},
{
"OmniaCode": 2,
"OmniaName": "Lahti",
"ControllerId": 100041,
"ControllerDescription": "Saksalankatu - Luhdan Liittymä",
"ControllerExternalCode": "R606"
}, .....
◼ "https://aineisto.swarco.fi/api/omniacode/:omniacode?/controllerstatus/:id?" -> GET current status of traffic light controller e.g. below.
Parameters values example:
:omniacode? = 5
:id? = 64
{
"IntersectionId": 64,
"ControllerId": 64,
"MeasurementTime": "2021-04-13T23:45:00.000Z",
"IntersectionCode": "097",
"ControllerProgramNumber": 9,
"ControllerprogramDescription": "COORDINATED MODE, SITUATION 12",
"ControllerStatus": "ON",
"StartTime": "2021-04-14 02:30:00",
"EndTime": "2021-04-14 02:45:00"
}
◼ "https://aineisto.swarco.fi/api/omniacode/:omniacode?/controller/" -> GET list of controller under specified omnia code e.g. below.
Parameters values example:
:omniacode? = 2
{
"OmniaCode": 2,
"OmniaName": "Lahti",
"ControllerId": 100041,
"ControllerDescription": "Saksalankatu - Luhdan Liittymä",
"ControllerExternalCode": "R606"
},
{
"OmniaCode": 2,
"OmniaName": "Lahti",
"ControllerId": 100043,
"ControllerDescription": "Uudenmaankatu - Ajokatu",
"ControllerExternalCode": "R653"
},.....
◼ "https://aineisto.swarco.fi/api/omniacode/:omniacode?/controller/:id?.:starttime?.:endtime?" -> GET list of specified omnia code, controller(id) all detectors based on given start & end time.
Parameters values example:
:omniacode? = 2
::id?? = 100020
.:starttime = [ISO 8601 Notation starttime/endtime should be in format of yyyy-mm-ddThh:mm:ss]
.:endtime = [ISO 8601 Notation starttime/endtime should be in format of yyyy-mm-ddThh:mm:ss]
An example request on -> /api/omniacode/2/controller/100020.2019-10-20T00:00:00.2019-10-22T00:00:00 gives result as below.
{
"ControllerId": 100020,
"DetectorId": 762,
"DetectorExternalCode": "762",
"SumOfTraffic": 6990,
"MeanOccupancyPercent": 3.000166678552826
},
{
"ControllerId": 100020,
"DetectorId": 763,
"DetectorExternalCode": "763",
"SumOfTraffic": 5427,
"MeanOccupancyPercent": 2.17199998728724
},.....
◼ "https://aineisto.swarco.fi/api/omniacode/:omniacode?/controller/:id?/:detectorid?.:starttime?.:endtime?" -> GET list of specified omnia code, controller(id) indiviual detector based on given start & end time.
Parameters values example:
:omniacode? = 2
::id?? = 100020
:detectorid? = 105
.:starttime = [ISO 8601 Notation starttime/endtime should be in format of yyyy-mm-ddThh:mm:ss]
.:endtime = [ISO 8601 Notation starttime/endtime should be in format of yyyy-mm-ddThh:mm:ss]
An example request on /api/omniacode/2/controller/100020/764.2019-10-20T00:00:00.2019-10-22T00:00:00 gives result as below.
{
"ControllerId": 100020,
"DetectorId": 764,
"DetectorExternalCode": "764",
"SumOfTraffic": 7169,
"MeanOccupancyPercent": 2.3368888923277455
}
❔ If no start & end time is given it will give result from latest data recorded. As in example below:
◼ "https://aineisto.swarco.fi/api/omniacode/2/controller/100020"
{
"ControllerId": 100020,
"DetectorId": 777,
"DetectorExternalCode": "777",
"SumOfTraffic": 14,
"MeanOccupancyPercent": 20.6850004196167
},
{
"ControllerId": 100020,
"DetectorId": 778,
"DetectorExternalCode": "778",
"SumOfTraffic": 16,
"MeanOccupancyPercent": 0.32499999925494194
}
],
"starttime": "2019-10-22 07:25:22",
"endtime": "2019-10-22 08:25:22"
◼ "https://aineisto.swarco.fi/api/omniacode/2/controller/100020/764"
{
"ControllerId": 100020,
"DetectorId": 764,
"DetectorExternalCode": "764",
"SumOfTraffic": 449,
"MeanOccupancyPercent": 11.452500104904175
}
],
"starttime": "2019-10-22 07:29:49",
"endtime": "2019-10-22 08:29:49"
# Authorization
What is the preferred way of using the API?
All /api/ request should contain Authorization with Bearer token into header request.
Example for none browser request e.g. curl -k -H "Authorization: Bearer TOKEN_KEY" -i https://aineisto.swarco.fi/api/help
# Error Codes
What errors and status codes can a user expect?
Credential missing / required - if authorization header not sent in request.
Credential missing / incorrect - if authorization header were not correct.
Error 404 🤔 use /api/help given references for correct route request - if api route is not correct.
# Documentation revision history.
[13.09.2019] - initial version.
[22.10.2019] - changes affecting api authorization.
[14.04.2021] - added new function to get controller status information, can only be used with omnivue systems