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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. 5.1.3 Record definitie
Veldnaam 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. 5.2.1 Record definitie
Veldnaam 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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. 6.1.1 Record definitie
Veldnaam 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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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<integer> TPEG TEC causeCode start_time timestamp update_time timestamp Van deze versie expected_end_t timestamp ime segment_id list<long> 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 Wegsegment(en) gescheiden door een komma. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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’. 6.3.1 Record Definitie
Veldnaam Datatype Eenhe
id Beschrijving segment_id long Lijst van id’s van getroffen segmenten
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 Wegsegment(en) gescheiden door een komma. weather_type weather_type_enum Optioneel Weer/neerslag types, gescheiden door komma. feed_id integer Optioneel Databron(nen), gescheiden door een komma. 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. 6.4.1 Record Definitie
Veldnaam Datatype Eenheid Beschrijving segment_id long Lijst van id’s van getroffen segmenten
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 Wegsegment(en) gescheiden door een komma. weather_type weather_type_enum Optioneel Weer/neerslag types, gescheiden door komma. feed_id integer Optioneel Databron(nen), gescheiden door een komma. 6.4.2.1.2 Respons
0 .. N records, volgens de record definitie. Alle weersvoorspellingen die betrekking hebben op het wegsegment worden teruggegeven. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. 7.1.1 Record definitie (response)
Veldnaam 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<long> 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.1.2.2.1 Respons
0 .. N records, volgens de record definitie in JSON formaat
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. 7.2.1 Record definitie (response)
Veldnaam 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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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<long> Lijst van stop ID’s waarover de route loopt segment_id list<long> 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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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.2.2.2.1 Respons
0 .. N records, volgens de record definitie in JSON formaat
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. 7.3.1 Record definitie (response)
Veldnaam Datatype Eenheid Beschrijving stop_id String Een ID wat de bushalte of station beschrijft route_id String Een ID wat de route beschrijft route_type long Een ID wat het type transport van de route beschrijft localized_route_ty String pe Additionele info over het type transport, bijv Buurtbus of Belbus service_id String Een ID wat aangeeft wanneer de service beschikbaar is trip_id String Een ID wat de trip beschrijft Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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.3.2.2.1 Respons
0 .. N records, volgens de record definitie in JSON formaat
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. 7.4.1 Record definitie (response)
Veldnaam Datatype Eenheid Beschrijving stop_id String Een ID wat de bushalte of station beschrijft route_id String Een ID wat de route beschrijft route_type long Een ID wat het type transport van de route beschrijft localized_route_ty String pe Additionele info over het type transport, bijv Buurtbus of Belbus trip_id String Een ID wat de trip beschrijft 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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 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. 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 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 first_planned_d timestamp eparture_time Geef voor ieder route_id het eerst volgende planned_departure_time, huidig tijdstip of later 7.4.2.2.1 Respons
0 .. N records, volgens de record definitie in JSON formaat 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 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. 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 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 first_planned_d timestamp eparture_time Geef voor ieder route_id het eerst volgende planned_departure_time, huidig tijdstip of eerder 7.4.2.4.1 Respons
0 .. N records, volgens de record definitie in JSON formaat
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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
27 7.5.1 Record definitie (response)
Veldnaam Datatype Eenheid Beschrijving trip_id String Een ID wat de trip beschrijft 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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. 7.5.2.2.1 Respons
0 .. N records, volgens de record definitie in JSON formaat
Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 } ] } Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 } ] } Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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) Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
39 java.net.URI anyURI Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
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. Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
41 Aan dit document kunnen geen rechten worden ontleend. Wijzigingen voorbehouden.
42
© Copyright 2024 ExpyDoc
