Omnia WEB API

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