Een introductie voor ontwikkelaars

Een introductie voor ontwikkelaars versie 10152014

Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

1

2 Inhoudgsopgave Een introductie voor ontwikkelaars 2 Inhoudgsopgave 3 Inleiding 3.1 WEBAPI 3.2 Authenticatie & Autorisatie 3.3 Payload formaten 4 Overzicht van API endpoints 5 Endpoints voor configuratiedata 5.1 Roadsegments API 5.1.1 Record definitie 5.1.2 Operaties 5.1.2.1 GET https://connect.simacan.com/api/v1/roadsegments 5.1.2.1.1 Parameters 5.1.2.1.2 Respons 5.1.2.2 GET https://connect.simacan.com/api/v1/roadsegments/metadata 5.1.3 Record definitie 5.2 Feeds API 5.2.1 Record definitie 5.2.2 Operaties 5.2.2.1 GET https://connect.simacan.com/api/v1/feeds 6 Endpoints voor statusgegevens (weer/verkeer) 6.1 Trafficstate API 6.1.1 Record definitie 6.1.2 Operaties 6.1.2.1 GET https://connect.simacan.com/api/v1/trafficstate/latest 6.1.2.1.1 Parameters: 6.1.2.1.2 Response 6.2 Events API 6.2.1 Record Definitie 6.2.2 Operaties 6.2.2.1 GET https://connect.simacan.com/api/v1/events/latest 6.2.2.1.1 Parameters 6.2.2.1.2 Respons 6.3 Weatherstate 6.3.1 Record Definitie 6.3.2 Operaties 6.3.2.1 GET https://connect.simacan.com/api/v1/weatherstate/latest 6.3.2.1.1 Parameters 6.3.2.1.2 Respons 6.4 Weather forecast Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

2

6.4.1 Record Definitie 6.4.2 Operaties 6.4.2.1 GET https://connect.simacan.com/api/v1/weatherforecast/latest 6.4.2.1.1 Parameters 6.4.2.1.2 Respons 6.5 Roadrestrictions API 6.5.1 Record definitie (response) 6.5.2 Operaties 6.5.2.1 HTTP GET https://connect.simacan.com/api/v1/roadrestrictions 6.5.2.1.1 Parameters 6.5.2.1.2 Respons 7 Endpoints voor openbaar vervoer 7.1 Stops 7.1.1 Record definitie (response) 7.1.2 Operaties 7.1.2.1 Type operaties 7.1.2.2 Parameters 7.1.2.2.1 Respons 7.2 Routes 7.2.1 Record definitie (response) 7.2.2 Operaties 7.2.2.1 Type operaties 7.2.2.2 Parameters 7.2.2.2.1 Respons 7.3 Planning 7.3.1 Record definitie (response) 7.3.2 Operaties 7.3.2.1 Type operaties 7.3.2.2 Parameters 7.3.2.2.1 Respons 7.4 Actuele vertrektijden (departures) 7.4.1 Record definitie (response) 7.4.2 Operaties 7.4.2.1 Type operaties latest 2.4.2.1.1 Parameters 7.4.2.2.1 Respons 7.4.2.3 Type operaties historic 7.4.2.4 Parameters 7.4.2.4.1 Respons 7.5 OV actuele posities 7.5.1 Record definitie (response) 7.5.2 Operaties 7.5.2.1 Type operaties latest Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

3

7.5.2.2 Parameters 7.5.2.2.1 Respons 8 Request en repsonse voorbeelden van de Trafficstate en Events API 8.1 Trafficstate 8.1.1 Request 8.1.2 Response 8.1.2.1 application/json 8.2 Events 8.2.1 Request 8.2.2 Response 8.2.2.1 application/json 9 BIJLAGE: Payload formaten en datatypen 9.1 JSON 9.1.1 Samengestelde types 9.2 Datatypes 9.3 Enumeraties 9.3.1 vehicle_type_enum 9.3.2 locationreference_type_enum 9.3.3 carriageway_enum 9.3.4 lane_enum 9.3.5 segment_state_type_enum 9.3.6 vild_direction_enum 9.3.7 weather_type_enum 9.4 JavatoXML Mapping for BuiltIn Data Types 10 Error status codes

3 Inleiding Het Smart Mobility Platfrom is een initiatief van provincie Utrecht, Economic Board Utrecht en de partners in het Smart Mobility project: Simacan, Technolution, TNO en Royal HaskoningDHV. Voor de technische realisatie van dit platform wordt gebruik gemaakt van het Simacan Connect Platform. Het Simacan Connect Platform is solide data infrastructuur die reeds commercieel wordt ingezet. Sinds kort wordt de functionaliteit in dit platform stap voor stap beschikbaar gemaakt voor andere partijen om zelf diensten of toepassingen te ontwikkelen middels een zgn WEBAPI. Winnaars van de Smart Mobility Challenge krijgen toegang tot deze API inclusief een aantal publieke en private databronnen waarmee zij zelf nieuwe diensten en toepassingen kunnen ontwikkelen. Het grote voordeel van het platform is dat al deze databronnen te raadplegen zijn in een ruimtelijke configuratie die kaart en dataleverancier onafhankelijk werkt. Op deze manier wordt het eenvoudiger en goedkoper om deze databronnen te gebruiken. Dit document geeft een technische beschrijving van deze WEBAPI, welke functionaliteit beschikbaar is incl. een aantal voorbeelden zodat potentiële deelnemers van de Smart Mobilty Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

4

Challenge een goed inhoudelijk beeld krijgen voor het ontwerp van hun toekomstige dienst en/of toepassing. De WEBAPI is beschikbaar maar ook continu in ontwikkeling. Voor vragen raadpleeg het smartmobility forum op http://www.smartmobilityutrecht.nl Op https://status.simacan.com kan realtime de beschikbaarheid van het platform worden bekeken incl meldingen over gepland onderhoud.

3.1 WEB-API Simacan Connect is een WEBAPI ook wel RESTful API. De URL beschrijft de call en data/func die wordt benaderd en een selectie van de data. Alle communicatie verloopt via /HTTPS. bijv:

GET https://connect.simacan.com/api/v1/trafficstate/latest WebserviceAPI's die voldoen aan de REST1 beperkingen worden REST genoemd. REST API's worden gedefinieerd met deze aspecten: ● base URI, zoals http://example.com/resources/ ● een Internet mediatype voor de gegevens. Dit is vaak JSON, maar kan een andere geldige Internet media (bv. XML, CSV, Atom, microformats, afbeeldingen, enz.) zijn ● standaard HTTPmethoden (bijvoorbeeld GET, PUT, POST of DELETE) Wanneer de ontvanger de nieuwste data wil opvragen zal deze zelf het initiatief moeten nemen om een request te doen en op deze wijze nieuwe updates te ontvangen. In de API kan een pull request uitgevoerd worden door een simpel GET request te doen op de gewenst call. Bijvoorbeeld GET https://connect.simacan.com/api/v1/trafficstate/latest.

3.2 Authenticatie & Autorisatie De implementatie ten behoeven van authenticatie en autorisatie geschiedt middels een API_KEY mechaniek. API keys zijn een zeer gangbaar wijze voor authenticatie op het WEB. Het formaat van de API_KEY mag zelf gekozen. Een API_KEY wordt bij ieder request meegezonden als http header. Alle API calls gaan via HTTPS. De API zal geen requests afhandelen via HTTP. 1

In tegenstelling tot SOAP gebaseerde webservices, is er geen "officiële" standaard voor REST webAPI's. Dit komt omdat REST is een architectonische stijl, in tegenstelling tot SOAP, dat is een protocol. Ook al REST is niet een standaard, een REST implementatie zoals het Web bevat standaarden zoals HTTP, URI, XML, etc. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

5

3.3 Payload formaten De API ondersteunt de volgende media types om payloads van de responses in te encoderen. In de onderstaande tabel wordt aangegeven welke response media types beschikbaar zijn tijdens het Smart Mobility Utrecht project. Payload formaat

Accept header

Ondersteund in Smart Mobility Utrecht

csv

application/cvs

nee

json

application/json

ja

xml

application/xml

nee

protobuf (binair)

websockets

nee

In het hoofdstuk “Payload formaten en datatypen” kunt u lezen hoe binnen de verschillende payload formaten datatype worden gepresenteerd (gecodeerd). In het hoofdstuk voorbeelden kunt een een aantal interactie voorbeelden zien hoe u de API kunt gebruiken en hoe data wordt teruggegeven wanneer u een API call uitvoert.


6

4 Overzicht van API endpoints De endpoints zijn onderverdeeld per (functionele) categorie gegevensdata (bijv. trafficstate, weatherstate etc). Statusgegevens zijn altijd gekoppeld aan één of meer wegsegmenten (Simacan Unified Segments). Hieronder volgt een overzicht.

Voor elk categorie data zijn drie endpoints gedefinieerd: ● latest De latest calls zijn bedoeld om de laatst beschikbare data zo snel mogelijk terug te geven. De laatste 5 minuten aan data is beschikbaar via deze endpoints. ● historic Historic calls geven data terug over een tijdsbereik tot maximaal 4 uur in het verleden. Deze calls hebben mogelijk een langere wachttijd dan de latest calls. (niet beschikbaar in de Smart Mobility Challenge) ● realtime Geeft data terug als deze beschikbaar komt via een streaming (Websocket) interface. (niet beschikbaar in de Smart Mobility Challenge) Naast bovenstaande overzicht zullen wegbeperkingen van de RDW (Roadrestrictions API) en OV informatie (publictransport API) beschikbaar worden gesteld.


7

De Segmentstate, VehicleState en historic en realtime streaming endpoints zijn niet beschikbaar tijdens de Smart Mobility Challenge

5 Endpoints voor configuratiedata

5.1 Roadsegments API De kracht van het Connect platform is dat alle beschikbare databronnen 1 en dezelfde ruimtelijke configuratie hanteren. Deze ruimtelijke configuratie van wegen worden uitgedrukt in zgn Unified segments. Dit zijn segmenten van 100 meter waaraan gemeten en afgeleide data is gekoppeld. Deze segmenten worden gebruikt in de segment_id parameter van vrijwel alle API calls binnen het platform. Een wegsegment kan zowel een stukje van een rijbaan als een stukje van een rijstrook beschrijven. De meest voor de hand liggende volgorde is dat u 1 keer per week/maand/kwartaal de configuratie ophaalt deze lokaal opslaat en vervolgens aan de hand van deze segmenten de data gaat bevragen in het platform.

5.1.1 Record definitie Veldnaam

Dataty pe

Eenheid Verplicht

Beschrijving

id

long

Verplicht

Uniek ID van het segment binnen de configuratieversie.

lane

lane_e num

Verplicht

Rijstrook.

max_speed

integer km/h

Verplicht

Wettelijke maximum snelheid.

length

integer m

Verplicht

Lengte van het segment.

location

location referen ce

Verplicht

Locatiereferentie. Dit hangt af van de locationreferencetype parameter die wordt opgegeven aan de GET request.


8

5.1.2 Operaties 5.1.2.1 GET https://connect.simacan.com/api/v1/roadsegments 5.1.2.1.1 Parameters Onderstaand worden de parameters opgesomd, die opgegeven kunnen worden bij het opvragen van wegsegmenten. Als er gebruik wordt gemaakt van een route of locationreference, zullen de roadsegments teruggegeven worden in de volgorde van de route of locationreference. Parameter

Datatype

Verplicht?

Beschrijving

segment_id

long

Optioneel

Segment ID's gescheiden door een komma.

lane

lane_enum

Optioneel

Komma gescheiden lijst van rijstrook types. Indien weggelaten wordt “allLanesCompleteCarriageway” gebruikt.

bounding_box

boundingbox

Optioneel

Geef wegsegmenten terug die vallen binnen de bounding box.

route

coordinate,coo Optioneel rdinate

Geeft de wegsegmenten terug de op de route beschreven door het startcoördinaat en het eindcoördinaat.

locationreferenc locationreferen Optioneel e ce_type_enum :encoding:data

Geeft die wegsegmenten terug die worden beschreven door de locatiereferentie. De data moet zijn gecodeerd volgens de gegeven encoding. Mogelijk waarden voor encoding zijn: "hex" en "b64". Bijvoorbeeld: openlr:hex:a7d3445.

locationreferenc locationreferen Optioneel e_return_type ce_type_enum

Het locatiereferentie mechanisme dat wordt gebruikt om de locatie van de segmenten in het resultaat te beschrijven. Indien niet opgegeven wordt WGS84 gebruikt.

5.1.2.1.2 Respons 0 .. N records, volgens de record definitie


9

5.1.2.2 GET https://connect.simacan.com/api/v1/roadsegments/metadata Bevat metagegevens over de configuratie. Het veld version moet aanwezig zijn. Andere velden kunnen door leveranciers worden toegevoegd.


Dataty pe

Eenheid Verplicht

Beschrijving

version

string

Configuratieversie

Verplicht

5.2 Feeds API Middels deze interface kan worden opgevraagd welke feeds aanwezig zijn en door welke leverancier deze worden geleverd.


Datatype Eenheid

Verplicht Beschrijving

id

integer

Verplicht

ID van feed

name

text

Verplicht

Naam van feed

supplier_name

text

Verplicht

Naam van de leverancier van de feed.

5.2.2 Operaties 5.2.2.1 GET https://connect.simacan.com/api/v1/feeds Haalt alle beschikbare feeds op en geeft deze terug. Deze operatie heeft geen parameters. De response bestaat uit een verzameling met daarin alle records.


10

6 Endpoints voor statusgegevens (weer/verkeer) 6.1 Trafficstate API Levert de gemeten waarden per bron, gekoppeld aan een wegsegment. Voor alle operaties binnen de ‘trafficstate’ endpoint geldt dat op geavanceerde wijze data van verschillende feeds kan worden opgevraagd. Als eerste kunnen feeds expliciet genoemd worden middels de id.. Als als feed_id een ‘*’ wordt opgegeven, dan worden alle beschikbare feeds teruggegeven, voor zover de dataleverancier doorsturen van brondata toestaat.


Datatype

Eenheid

Beschrijving

measurement_time timestamp

Tijdstip van de meting.

segment_id

long

ID van het wegsegment

vehicle_type

vehicle_typ e_enum

Voertuigklasse.

speed

float

km/h

Ruimtelijk gemeten snelheid

max_speed

integer

km/h

Wettelijke maximum snelheid

freeflow_speed

float

km/h

Freeflow snelheid

flow

integer

vtg/h

Intensiteit

traveltime

float

sec

Reistijd. Inverse snelheid

feed_id

integer

ID van de feed waarvan dit record afkomstig is.

De velden measurement_time, source, segment_id en vehicle_type vormen een unique key. Dat wil zeggen voor een combinatie van deze waarden is slechts een instantie van een record beschikbaar. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

11

6.1.2 Operaties 6.1.2.1 GET

https://connect.simacan.com/api/v1/trafficstate/latest

Retourneert de laatst gemeten waardes per wegsegment en per bron. Indien meerdere bronnen en/of wegsegmenten zijn opgegeven wordt een record per bron en wegsegmenten teruggegeven. 6.1.2.1.1 Parameters: Parameter

Datatype

V/O Beschrijving

segment_id

long

O

Wegsegment(en) gescheiden door een komma.

feed_id

integer of ‘*’

O

Databron(nen). Gescheiden door een komma. Indien niet gespecificeerd wordt de gefuseerde trafficstate gebruikt. Wanneer als feed_id parameter een ’*’ wordt opgegeven betekent dat de metingen van alle beschikbare feeds afzonderlijk worden teruggegeven, voor zover de dataleverancier het doorsturen van brondata toestaat.

start_time

timestamp O

vehicle_type text

O

Retourneert de laatste metingen vanaf het gespecificeerde tijdstip. Indien dit zou resulteren in een periode langer dan 5 minuten wordt een foutcode (204, no content) teruggegeven. Als geen waarde is opgegeven wordt de laatste minuut teruggeven. Voertuigklassen, gescheiden door komma. Indien niet gespecificeerd wordt de categorie AnyVehicle gebruikt. * betekent dat de metingen van alle beschikbare categorieën afzonderlijk worden teruggegeven.

6.1.2.1.2 Response 0 .. N records zoals beschreven in de record definitie die voldoen aan het opgegeven filter en max_age.

6.2 Events API Levert journalistieke verkeersdata


12

Records met betrekking tot incidenten worden doorgeleverd, zoals deze van de dataleverancier worden ontvangen. Als bijvoorbeeld in de incidentenfeed van het NDW om 12:00 en om 12:01 melding gemaakt wordt van hetzelfde incident, dan zullen ook twee records doorgeleverd worden. Deze interface geeft geen locatie in WGS84 coordinaten van het incident terug, maar alleen de segmentids. Vervolgens kunnen via de configuratieinterface de locaties van de betreffende segmenten worden opgevraagd in diverse locatiereferenties.

6.2.1 Record Definitie Veldnaam

Datatype

Eenhei d

Beschrijving

event_id

integer

Unieke ID van event. Deze blijft voor de gehele levensduur van het event gelijk.

version

integer

Event versie. Wijzigt per update.

event_code

list

TPEG TEC causeCode

start_time

timestamp

update_time

timestamp

Van deze versie

expected_end_t timestamp ime

segment_id

list

Lijst van id’s van getroffen segmenten

feed_id

integer

ID van de feed waarvan dit record afkomstig is.

6.2.2 Operaties 6.2.2.1 GET https://connect.simacan.com/api/v1/events/latest 6.2.2.1.1 Parameters Parameter

Datatype

Verplicht?

Beschrijving

segment_id

long

Optioneel



13

feed_id

integer

Optioneel

Databron(nen), gescheiden door een komma.

max_age

integer

Optioneel

Maximale leeftijd van een meting in seconden.

6.2.2.1.2 Respons 0 .. N records, volgens de record definitie. Alle incidenten die betrekking hebben op het wegsegment worden teruggegeven.


14

6.3 Weatherstate Levert weergegevens op segmentniveau volgens sectie 3.3.3 van werkgroep 1 specificatie. Er wordt op gewezen dat de specifieke waarschuwingen, zoals gladheid, mist en wind, opgenomen zijn in een apart endpoint: ‘Environmental state’.


Datatype

Eenhe id

Beschrijving

segment_id

long


measurement_ timestamp time

Tijdstip van de meting

weather_type

weather_ty pe_enum

Type weer/neerslag

value

float

*2

Gemeten waarde

feed_id

integer

Bron waar de waarde vandaan komt

6.3.2 Operaties 6.3.2.1 GET https://connect.simacan.com/api/v1/weatherstate/latest 6.3.2.1.1 Parameters

2

Parameter

Datatype

Verplicht?

Beschrijving

segment_id

long

Optioneel


weather_type

weather_type_enum

Optioneel

Weer/neerslag types, gescheiden door komma.

feed_id

integer

Optioneel


Verschilt per weather_type Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

15

max_age

integer

Optioneel

Maximale leeftijd van een meting in seconden.

6.3.2.1.2 Respons 0 .. N records, volgens de record definitie. Alle weermetingen die betrekking hebben op het wegsegment worden teruggegeven.

6.4 Weather forecast Levert weersvoorspellingen op segmentniveau volgens sectie 3.3.3 van werkgroep 1 specificatie. Weersvoorspellingen worden tot 6 uur in de toekomst gegeven en elke 15 minuten ververst.


Datatype

Eenheid Beschrijving

segment_id

long


measuremen t_time

timestamp

Tijdstip van de meting

weather_type weather_ty pe_enum

Type weer/neerslag

value

float

*3

Voorspelde waarde

certainty

float

Zekerheid van de voorspelling

feed_id

integer

Bron waar de waarde vandaan komt

6.4.2 Operaties 6.4.2.1 GET https://connect.simacan.com/api/v1/weatherforecast/latest Retourneert de huidige voorspellingen voor de komende 6 uur voor de bevraagde segmenten en weertypes.

3

Verschilt per weather_type Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

16

6.4.2.1.1 Parameters Parameter

Datatype

Verplicht?

Beschrijving

segment_id

long

Optioneel


weather_type

weather_type_enum

Optioneel

Weer/neerslag types, gescheiden door komma.

feed_id

integer

Optioneel


6.4.2.1.2 Respons 0 .. N records, volgens de record definitie. Alle weersvoorspellingen die betrekking hebben op het wegsegment worden teruggegeven.


17

6.5 Roadrestrictions API Bevat de wegsegmenten waaraan restricties zijn gekoppeld zoals toegekend door de RDW. De data is afkomstig van de RDW en bestaat uit de dataset Beperkingen voor Voertuigen. Informatie zoals de locatie, lengte en rijbaan en rijstrook informatie kan opgevraagd worden via de Roadsegements API in Simacan Connect. Een call gebeurd middels een HTTP GET. Data wordt in de HTTP response teruggestuurd in JSON.

6.5.1 Record definitie (response) Veldnaam

Datatype

Eenheid

Verplicht

Beschrijving

id

long

Verplicht

Uniek ID van het segment binnen de configuratieversie.

maximum_total_w float eight

kilograms Verplicht

Het maximale totale gewicht in kilogram van een voertuig dat op dit segment is toegestaan..

maximum_singlea float xleweight

kilograms Verplicht

Het maximumgewicht in kilogram dat per enkele as van een voertuig op dit segment is toegestaan.

maximum_height

float

meters

Verplicht

De maximale hoogte in meters die is toegestaan voor een voertuig dat onder een ander object (segment) door kan.

maximum_length

float

meters

Verplicht

De maximale voertuiglengte in meters die op dit segment vervoerselement is toegestaan.

maximum_width

float

meters

De maximale voertuigbreedte die op dit segment is toegestaan.

valid_from

timestamp datetime UTC

De datum sinds wanneer de restrictie geldig is

valid_to

timestamp datetime UTC

De datum tot wanneer de restricitie geldig is.


18

6.5.2 Operaties 6.5.2.1 HTTP GET https://connect.simacan.com/api/v1/roadrestrictions 6.5.2.1.1 Parameters Retourneert de waardes per wegsegment. Indien meerdere wegsegmenten zijn opgegeven wordt een record per wegsegment teruggegeven. Request parameter

Datatype

Verplicht

Beschrijving

segment_id

long

Verplicht

Segment ID's gescheiden door een komma.

6.5.2.1.2 Respons 0 .. N records, volgens de record definitie in JSON formaat


19

7 Endpoints voor openbaar vervoer

7.1 Stops Bevat alle geografische informatie van stops, zoals bushaltes, tram/metro stations en trein stations. De data kan opgevraagd worden via de publictransport/stops API in Simacan Connect. Een call gebeurd middels een HTTP GET of HTTP POST. Data wordt in de HTTP response teruggestuurd in JSON.


Datatype

Eenheid

Beschrijving

stop_id

String

Een ID wat de bushalte of station beschrijft

stop_name

String

Naam van de betreffende bushalte of station

stop_lat

float

Coordinaat in WGS84 latitude

stop_lon

float

Coordinaat in WGS84 longitude

segment_id

long

ID van het wegsegment waarop de stop ligt. Of het wegsegment waar de stop het dichtst bij ligt / de ingang ligt.

route_id

list

Lijst van route ID’s die de stop bedienen

7.1.2 Operaties 7.1.2.1 Type operaties HTTP GET https://connect.simacan.com/api/v1/publictransport/stops HTTP POST https://connect.simacan.com/api/v1/publictransport/stops

7.1.2.2 Parameters Onderstaand worden de parameters opgesomd, die opgegeven kunnen worden bij het opvragen van ov stops. Als er gebruik wordt gemaakt van een trip, route of locationreference, zullen de stops teruggegeven worden in de volgorde van de trip, route of locationreference. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

20

Request parameter

Datatype

Beschrijving

route_id

String

Route ID’s gescheiden door een komma. Geef stops terug die bij de route horen

segment_id

long

Segment ID's gescheiden door een komma. Geef stops terug die op een segment liggen.

bounding_box

boundingbox

Geef stops terug die vallen binnen de bounding box.

route

coordinate,coo Geeft de stops terug de op de route beschreven door het rdinate startcoördinaat en het eindcoördinaat.

locationreferen ce

locationreferen Geeft die stops terug die worden beschreven door de ce_type_enum locatiereferentie. De data moet zijn gecodeerd volgens de :encoding:data gegeven encoding. Mogelijk waarden voor encoding zijn: "hex" en "b64". Bijvoorbeeld: openlr:b64:CwOi1SUL6yOVA/7y/6wjBQ==


7.2 Routes Bevat alle geografische informatie van OV routes. Bijvoorbeeld een bus, metro/tram of trein lijn. De data kan opgevraagd worden via de OV routes API in Simacan Connect. Een call gebeurd middels een HTTP GET of HTTP POST. Data wordt in de HTTP response teruggestuurd in JSON.


Datatype

Eenheid

Beschrijving

route_id

String

Een ID wat de route beschrijft

route_type

long

Een ID wat het type transport van de route beschrijft


21

localized_route_ty String pe

Additionele info over het type transport, bijv Buurtbus of Belbus

agency_id

String

Een ID van de maatschappij

stop_id

list

Lijst van stop ID’s waarover de route loopt

segment_id

list

Lijst van segment ID’s waarover de route loopt

location

locationrefer ence

Locatiereferentie. Dit hangt af van de locationreferencetype parameter die wordt opgegeven aan de GET request.

7.2.2 Operaties 7.2.2.1 Type operaties HTTP GET https://connect.simacan.com/api/v1/publictransport/routes HTTP POST https://connect.simacan.com/api/v1/publictransport/routes

7.2.2.2 Parameters Onderstaand worden de parameters opgesomd, die opgegeven kunnen worden bij het opvragen van ov stops. Als er gebruik wordt gemaakt van een trip, route of locationreference, zullen de stops teruggegeven worden in de volgorde van de trip, route of locationreference. Request parameter

Datatype

Beschrijving

route_id

String

Route ID’s gescheiden door een komma. Geef opgegeven routes terug.

route_type

long

Route types gescheiden door een komma. Geef routes terug die bij de route type horen (type transport)

stop_id

String

Stop ID’s gescheiden door een komma. Geef routes terug die de stop bedienen.

segment_id

long

Segment ID's gescheiden door een komma. Geef routes terug die over een segment lopen.


22

bounding_box

boundingbox

Geef routes terug die (deels) vallen binnen de bounding box.

route

coordinate,coo Geeft de ov routes terug die (deels) lopen over de route rdinate beschreven door het startcoördinaat en het eindcoördinaat.

locationreferen ce

locationreferen Geeft die ov routes terug die (deels) lopen over de route ce_type_enum die worden beschreven door de locatiereferentie. De data :encoding:data moet zijn gecodeerd volgens de gegeven encoding. Mogelijk waarden voor encoding zijn: "hex" en "b64". Bijvoorbeeld: openlr:hex:a7d3445.


7.3 Planning Bevat alle planningen van OV trips per stop. De data kan opgevraagd worden via de OV planning API in Simacan Connect. Een call gebeurd middels een HTTP GET of HTTP POST. Data wordt in de HTTP response teruggestuurd in JSON.


Datatype

Eenheid

Beschrijving

stop_id

String


route_id

String


route_type

long




service_id

String

Een ID wat aangeeft wanneer de service beschikbaar is

trip_id

String

Een ID wat de trip beschrijft


23

stop_sequence

long

Het nummer van de stop van de bijbehorende trip

planned_arrival_ti me

timestamp

Geplande aankomsttijd bij stop

planned_departur e_time

timestamp

Geplande vertrektijd bij stop

wheelchair_acces integer sible

0: geen info beschikbaar 1: ten minste 1 plaats beschikbaar 2: niet beschikbaar

bikes_allowed

0: geen info beschikbaar 1: ten minste 1 plaats beschikbaar 2: niet beschikbaar

integer

7.3.2 Operaties 7.3.2.1 Type operaties HTTP GET https://connect.simacan.com/api/v1/publictransport/planning HTTP POST https://connect.simacan.com/api/v1/publictransport/planning

7.3.2.2 Parameters Retourneert de planningen per stop. Request parameter

Datatype

Beschrijving

stop_id

String

Stop ID’s gescheiden door een komma. Geef planning terug die bij de stop horen.

route_id

String

Route ID’s gescheiden door een komma. Geef planning terug die bij de route horen, gescheiden per stop

route_type

long

Route types gescheiden door een komma. Geef planning terug die bij de route type horen (type transport)

trip_id

String

Trip ID’s gescheiden door een komma. Geef planning per stop terug die bij de trip horen


24

start_time

timestamp

Vanaf moment (inclusief) voor retourneren planned_departure_time

end_time

timestamp

Tot moment (inclusief) voor retourneren planned_departure_time

first_planned_d timestamp eparture_time

Geef voor ieder route_id het eerst volgende planned_departure_time


7.4 Actuele vertrektijden (departures) Bevat alle actuele vertrektijden van OV trips. De data kan opgevraagd worden via de OV realtime departs API in Simacan Connect. Een call gebeurd middels een HTTP GET of HTTP POST. Data wordt in de HTTP response teruggestuurd in JSON.


Datatype

Eenheid

Beschrijving

stop_id

String


route_id

String


route_type

long




trip_id

String


stop_sequence

long

Het nummer van de stop van de bijbehorende trip

current_arrival_ti me

timestamp

Actuele (verwachte) aankomsttijd bij stop

current_departure timestamp _time

Actuele (verwachte) vertrektijd bij stop


25

7.4.2 Operaties 7.4.2.1 Type operaties latest HTTP GET https://connect.simacan.com/api/v1/publictransport/departures/latest HTTP POST https://connect.simacan.com/api/v1/publictransport/departures/latest

2.4.2.1.1 Parameters Retourneert de realtime departures per stop. Request parameter

Datatype

Beschrijving

stop_id

String


route_id

String

Route ID’s gescheiden door een komma. Geef planning terug die bij de route horen.

route_type

long


trip_id

String

Trip ID’s gescheiden door een komma. Geef planning terug die bij de trip horen.

start_time

timestamp

Vanaf moment (inclusief) voor retourneren real_departure_time, huidig tijdstip of later

end_time

timestamp

Tot moment (inclusief) voor retourneren real_departure_time, later dan start_time


Geef voor ieder route_id het eerst volgende planned_departure_time, huidig tijdstip of later


7.4.2.3 Type operaties historic HTTP GET https://connect.simacan.com/api/v1/publictransport/departures/historic Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

26

HTTP POST https://connect.simacan.com/api/v1/publictransport/departures/historic 7.4.2.4 Parameters Retourneert de waardes per wegsegment. Indien meerdere wegsegmenten zijn opgegeven wordt een record per wegsegment teruggegeven. Request parameter

Datatype

Beschrijving

stop_id

String


route_id

String

Route ID’s gescheiden door een komma. Geef planning terug die bij de route horen.

route_type

long


trip_id

String

Trip ID’s gescheiden door een komma. Geef planning terug die bij de trip horen.

start_time

timestamp

Vanaf moment (inclusief) voor retourneren real_departure_time, eerder dan end_time

end_time

timestamp

Tot moment (inclusief) voor retourneren real_departure_time, huidig tijstip of eerder


Geef voor ieder route_id het eerst volgende planned_departure_time, huidig tijdstip of eerder


7.5 OV actuele posities Bevat alle actuele posities van OV trips. De data kan opgevraagd worden via de OV realtime positions API in Simacan Connect. Een call gebeurd middels een HTTP GET of HTTP POST. Data wordt in de HTTP response teruggestuurd in JSON.


27


Datatype

Eenheid

Beschrijving

trip_id

String


stop_lat

float

Coordinaat in WGS84 latitude

stop_lon

float

Coordinaat in WGS84 longitude

speed

float

Huidige snelheid van het voertuig

segment_id

long

Indien beschikbaar: het segment ID waar het voertuig zich op bevindt

next_stop_id

String

Het eerst volgende stop ID van deze trip

next_stop_sequen long ce

Het eerst volgende stop sequence van deze trip

vehicle_id

String

Een ID van het voertuig

current_status

String

Huidige status van het voertuig, mogelijke waarden: INCOMING_AT, STOPPED_AT, IN_TRANSIT_TO

schedule_relation ship

String

Status van de trip, mogelijke waarden: SCHEDULED, ADDED, UNSCHEDULED, CANCELED

7.5.2 Operaties 7.5.2.1 Type operaties latest HTTP GET https://connect.simacan.com/api/v1/publictransport/positions/latest HTTP POST https://connect.simacan.com/api/v1/publictransport/positions/latest

7.5.2.2 Parameters Retourneert de waardes per wegsegment. Indien meerdere wegsegmenten zijn opgegeven wordt een record per wegsegment teruggegeven.


28

Request parameter

Datatype

Beschrijving

trip_id

String

Trip ID’s gescheiden door een komma. Geef planning terug die bij de trip horen

segment_id

long

Segment ID's gescheiden door een komma. Geef voertuigen terug die momenteel op een segment liggen.

bounding_box

boundingbox

Geef stops terug die vallen binnen de bounding box.

start_time

timestamp

Retourneert de laatste publicaties vanaf het gespecificeerde tijdstip (start_time). Dit wil zeggen dat het meegeven van de vorige verzoekstijd meegeven als start_time leidt dat er geen data gemist wordt. Als geen waarde voor start_time is opgegeven, dan wordt de laatste gepubliceerde waarde teruggeven. Indien dit zou resulteren in een periode langer dan 5 minuten wordt een foutcode (204, no content) teruggegeven.



29

8 Request en response voorbeelden van de Trafficstate en Events API

8.1 Trafficstate

8.1.1 Request In dit request wordt de trafficstate voor 3 segmenten opgevraagd. ● Segment 123 beschrijft een stuk rijbaan ● Segment 567 beschrijft rijstrook 1 van segment 123 ● Segment 875 beschrijft rijstrook 2 van segment 123 GET https://connect.simacan.com/api/v1/trafficstate/latest?segment_id=123,567,875 Accept: application/json

8.1.2 Response De response bevat de trafficspeed per opgevraagd segment. Omdat geen feed_id is opgegeven wordt de fused trafficstate feed gebruikt (met id 3). Deze is opgebouwd uit de feeds: ● 5: tomtom_hdflow ● 6: ndw_trafficspeed ● 7: ndw_traveltime ● 8: rws_ady Omdat geen vehicle_type is opgegeven wordt alleen de categorie AnyVehicle teruggegeven. De snelheid is voor alle segmenten gelijk (omdat deze niet op rijstrookniveau beschikbaar is). De intensiteit is voor segment 123 (de rijbaan) een gemiddelde van de intensiteiten van de rijstroken (en heeft daarom de metadata vlag lane_specific=false). De intensiteit voor segment 567 en 875 (de rijstroken) is wel rijstrook specifiek. Op rijstrook 2 geldt een aangepaste maximum snelheid (via de rws_ady feed). Dit is te zien in de metadata. 8.1.2.1 application/json HTTP/1.1 200 OK ContentType: application/json; charset=utf8 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

30

{ "records": [ { "measurement_time": "20140613T10:15:00.000", "segment_id": 123, "vehicle_type": "AnyVehicle", "speed": 98.3, "max_speed": 120, "freeflow_speed": "118", "flow": 2000, "traveltime": 18, "feed_id": 3 }, { "measurement_time": "20140613T10:15:00.000", "segment_id": 567, "vehicle_type": "AnyVehicle", "speed": 98.3, "max_speed": 120, "freeflow_speed": "127", "flow": 1500, "traveltime": 18, "feed_id": 3 }, { "measurement_time": "20140613T10:15:00.000", "segment_id": 875, "vehicle_type": "AnyVehicle", "speed": 98.3, "max_speed": 100, "freeflow_speed": "86", "flow": 2600, "traveltime": 29, "feed_id": 3 } ] }


31

8.2 Events 8.2.1 Request In dit voorbeeld worden alle actuele incidenten opgehaald, dus er worden geen segment_ids en geen feed_ids opgegeven. Er is een enkele feed is (NDW met id=726), die slechts een enkel incident meldt.

8.2.2 Response 8.2.2.1 application/json HTTP/1.1 200 OK ContentType: application/json; charset=utf8 { "records": [ { "event_id": 1592388, "version": 14, "event_code": 5, "start_time": "20140320T07:32:00Z", "update_time": "20140320T08:01:08Z", "expected_end_time": "20140320T09:30:00Z", "segment_id": [123, 567, 875], "feed_id": 726 } ] }


32

9 BIJLAGE: Payload formaten en datatypen In dit hoofdstuk wordt voor het JSON payload formaat beschreven hoe de verschillende response parameters worden gedecodeerd en hoe de verschillende datatypes in dat formaat worden gepresenteerd. Ook worden aangegeven hoe samengestelde typen worden geserialiseerd voor dit payload formaat.

9.1 JSON Een json object met een enkel veld "records" met als waarde een json array met een object per record. Elk object bevat de velden zoals gespecificeerd in de record definitie. Accept header waarde: "application/json" NULL waardes: null Datatype

Representatie

text

Javascript string met UTF8 encoded tekst

timestamp

Javascript string met datum en tijd in formaat: yyyyMMdd'T'HH:mm:ss.sssZ Bijvoorbeeld: "20140611T13:54:27.000Z"

integer

Javascript double

long

Javascript double

float

Javascript double

double

Javascript double

boolean

Javascript boolean

9.1.1 Samengestelde types Samengestelde types worden als JSON objecten gecodeerd in het resultaat. Bijvoorbeeld: { Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

33

"records": [ { "measurement_time": "20140531T165525.000Z", "segment_id": 1234567, "vehicle_type": null, "speed": 120.0, "max_speed": 130.0, "freeflow_speed": 115.0, "flow": 1200, "traveltime": 0.00833, "feed_id": 28 } ] }

9.2 Datatypes Datatype

Specificatie

Range

Opmerking

min

max

text

UTF8 encoded string

0

Wisselt per veld

timestamp

Datum en tijd in UTC met nauwkeurigheid in milliseconden

integer

32 bit signed integer

0

2311

Zie opmerking.

long

64 bit signed integer

0

2631

Zie opmerking.

float

32 bit signed floating point

double

64 bit signed floating point

boolean

true / false


34

coordinate

longitude,latitude

Longitude en latitude worden uitgedrukt in 6 decimale waarden .

boundingbox

upperleft,lowerright coordinates

Samengestelde Velden opgebouwd types uit 1 of meer andere velden

Opmerking: Voor de integer en de long geldt dat negatieve waarden niet gebruikt zullen worden.


35

9.3 Enumeraties De volgende enumeraties kunnen worden gebruikt om een datatype te beschrijven. Het onderliggende datatype is altijd text. Hier wordt beschreven welke waarden per enumeratie gedefinieerd zijn.

9.3.1 vehicle_type_enum Voertuigklasse. Mogelijke waarden zijn: ● AnyVehicle Alle voertuigen vallen in deze klasse. ● Motorcycle Motorrijwiel, scooter ● Car Personenauto / bestelauto

● Lorry ● Bus ● ArticulatedLorry

Ongelede vrachtauto Ongelede autobus Gelede vrachtauto

●

Overige voertuigen

Other

9.3.2 locationreference_type_enum Beschrijft een locatiereferentie type. Mogelijke waarden zijn: ● WGS84 Beschrijft een locatie in WGS84 coördinaten in WKT4 formaat. ● AlertC Een AlertC linear of point locatie volgens de NDW interface specificatie. De gebruikte TMC of VILD tabel wordt meegestuurd met de locatie. Via de configuratie API kan een afnemer zien welke tabel versie gebruikt is (bijv TMC of een VILD tabel) ● OpenLR Een OpenLR Line of PointAlongLine locatie.

9.3.3 carriageway_enum Beschrijft het type rijbaan. Mogelijke waarden zijn: ● MainCarriageway ● ConnectingCarriageway ● ParallelCarriageway ● EntrySlipRoad ● ExitSlipRoad

9.3.4 lane_enum

4

http://en.wikipedia.org/wiki/Wellknown_text Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

36

Beschrijft het rijstrook type. Voor de codering van een lanetype in een segment ID wordt de numerieke waarde gebruikt. De gekozen waarden zijn overgenomen zoals deze in DATEX2 zijn gedefinieerd. Mogelijke waarden zijn: ● 00 allLanesCompleteCarriageway ● 01 busLane ● 02 busStop ● 03 carPoolLane ● 04 centralReservation ● 05 crawlerLane ● 06 emergencyLane ● 07 escapeLane ● 08 expressLane ● 09 hardShoulder ● 10 heavyVehicleLane ● 11 lane1 ● 12 lane2 ● 13 lane3 ● 14 lane4 ● 15 lane5 ● 16 lane6 ● 17 lane7 ● 18 lane8 ● 19 lane9 ● 20 layBy ● 21 leftHandTurningLane ● 22 leftLane ● 23 localTrafficLane ● 24 middleLane ● 25 opposingLanes ● 26 overtakingLane ● 27 rightHandTurningLane ● 28 rightLane ● 29 rushHourLane ● 30 setDownArea ● 31 slowVehicleLane ● 32 throughTrafficLane ● 33 tidalFlowLane ● 34 turningLane ● 35 verge

9.3.5 segment_state_type_enum Beschrijft de status van een wegsegment. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.

37

● ● ● ● ● ● ●

MaxSpeed WindWarning IceWarning MistWarning Holiday LaneClosed VMSStatus

Wettelijke maximum snelheid (km/h)

Beeldstand. Mogelijke waarden: BLK, <, >, x, 030, 050, 070, 080, 090, 100, 120

9.3.6 vild_direction_enum Beschrijf de richting, van een lineaire locatie, t.o.v. de vildlijn. Mogelijke waarden zijn: ● Positive ● Negative

9.3.7 weather_type_enum Beschrijft een weer of neerslagtype. Mogelijke waarden staan onderstaand opgesomd. Voor de volledigheid is ook de eenheid opgenomen. ● WindDirection (degrees) ● WindSpeed (m/s) ● Temperature (degree C) ● AirPressure (hPa) ● Rain (mm/h) ● Visibility (m) ● RelativeHumidity (%) ● DewPoint (degree C) ● GlazedFrost (mm/h) ● Snow (mm/h) ● Hail (mm/h)


38

9.4 Java-to-XML Mapping for Built-In Data Types Java Data Type (lower case indicates a primitive data type)

Equivalent XML Schema Data Type

int

int

short

short

long

long

float

float

double

double

byte

byte

boolean

boolean

char

string (with facet of length=1)

java.lang.Integer

int

java.lang.Short

short

java.lang.Long

long

java.lang.Float

float

java.lang.Double

double

java.lang.Byte

byte

java.lang.Boolean

boolean

java.lang.Character

string (with facet of length=1)

java.lang.String

string

java.math.BigInteger

integer

java.math.BigDecimal

decimal

java.util.Calendar

dateTime

java.util.Date

dateTime

byte[]

base64Binary

javax.xml.namespace.QName

Qname


39

java.net.URI

anyURI


40

10 Error status codes De volgende statuscodes worden gebruikt: Code

HTTP Naam

Beschrijving

200

OK

Verzoek succesvol afgehandeld

204

No content

De periode waarover data is opgevraagd is niet beschikbaar.

400

Bad request

Ongeldige parameters, verzoek kon niet worden afgehandeld.

403

Forbidden

U heeft geen rechten om deze aanvraag te doen.

404

Not found

Opgevraagde URL kon niet gevonden worden.

410

Gone

Gegevens zijn niet meer beschikbaar.

500

Internal server error Fout opgetreden in de server. Neem contact op als dit aanhoudt.


41


42

Een introductie voor ontwikkelaars

Recommend Documents