📜 # 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?/controllerstatus/:id?", "/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?/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?/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/: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 or 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. [23.10.2019] - changes affecting api authorization. [14.04.2021] - added new function to get controller status information, can only be used with omnivue systems