Vertrektijd.Info REST API
1,097 views
Skip to first unread message
Jochem Beek
Aug 16, 2016, 1:03:58 PM8/16/16
to openov
Beste allen,
Implementatie van OV-Data is niet eenvoudig.
Wie o.a. deze groep doorleest zal opmerken dat de veelvoud aan specificaties, grote hoeveelheden data en de resources benodigd om deze te verwerken
een drempel vormen om (in publiek belang) met OV data aan de slag te gaan.
Logisch; enerzijds vereist de complexiteit een hoge upfront investering (leercurve) en leiden de nodige resources tot relatief hoge running costs (hosting).
Anderzijds zijn de verdiensten vaak beperkt of haast nihil.
Persoonlijk had ik bij de totstandkoming van de principes NDOV en Open Data de hoop gevestigd op partijen als 9292 en andere marktpartijen om API's te lanceren die deze leemte zouden vullen.
Tot op heden is hier echter geen API uit voortgekomen die wij voor onze eigen OV-projecten konden gebruiken, de transitie van Open-Data naar Open-API is hiermee beperkt gebleven.
Daarom hebben wij, net als velen van jullie een eigen API ontwikkeld.
Geinitieerd voor een OV project waarbij hoge prestaties, redundantie en beschikbaarheid nodig waren, is de door ons gebruikte API doorontwikkeld tot een platform dat zich goed
leent voor toepassingen van derden.
Met het openbaar stellen van deze API uiten wij de hoop de drempel voor ontwikkelaars en bedrijven om met OV-Data aan de slag te gaan substantieel te verlagen.
Tegelijkertijd rekenen wij erop dat gebruikers van deze API ons scherp houden en ons helpen deze API verder te verbeteren.
Gebruik van deze API is kosteloos voor Publieke, Non-Commerciele toepassingen. Waarbij redelijk gebruik verondersteld wordt.
Komende periode zullen we de frontend verder bijwerken en meer informatie hierover uitbrengen.
De API tref je hier: www.vertrektijd.info
Happy Coding! :)
Met vriendelijke groet,
Jochem Beek
www.vertrektijd.info
Implementatie van OV-Data is niet eenvoudig.
Wie o.a. deze groep doorleest zal opmerken dat de veelvoud aan specificaties, grote hoeveelheden data en de resources benodigd om deze te verwerken
een drempel vormen om (in publiek belang) met OV data aan de slag te gaan.
Logisch; enerzijds vereist de complexiteit een hoge upfront investering (leercurve) en leiden de nodige resources tot relatief hoge running costs (hosting).
Anderzijds zijn de verdiensten vaak beperkt of haast nihil.
Persoonlijk had ik bij de totstandkoming van de principes NDOV en Open Data de hoop gevestigd op partijen als 9292 en andere marktpartijen om API's te lanceren die deze leemte zouden vullen.
Tot op heden is hier echter geen API uit voortgekomen die wij voor onze eigen OV-projecten konden gebruiken, de transitie van Open-Data naar Open-API is hiermee beperkt gebleven.
Daarom hebben wij, net als velen van jullie een eigen API ontwikkeld.
Geinitieerd voor een OV project waarbij hoge prestaties, redundantie en beschikbaarheid nodig waren, is de door ons gebruikte API doorontwikkeld tot een platform dat zich goed
leent voor toepassingen van derden.
Met het openbaar stellen van deze API uiten wij de hoop de drempel voor ontwikkelaars en bedrijven om met OV-Data aan de slag te gaan substantieel te verlagen.
Tegelijkertijd rekenen wij erop dat gebruikers van deze API ons scherp houden en ons helpen deze API verder te verbeteren.
Gebruik van deze API is kosteloos voor Publieke, Non-Commerciele toepassingen. Waarbij redelijk gebruik verondersteld wordt.
Komende periode zullen we de frontend verder bijwerken en meer informatie hierover uitbrengen.
De API tref je hier: www.vertrektijd.info
Happy Coding! :)
Met vriendelijke groet,
Jochem Beek
www.vertrektijd.info
Erik van Heck
Aug 16, 2016, 1:43:59 PM8/16/16
to openov
Ziet er goed uit Jochem. Ik ga morgen zeker even een kijkje wagen en wat dingetjes uitproberen :-). Altijd leuk nieuwe initiatieven!
Martin Beck
Sep 8, 2016, 5:35:27 PM9/8/16
to openov
Hallo Jochem,
Mooi initiatief. Ik heb zojuist even gekeken en een account aangemaakt, en mij geregistreerd als developer!
Als ik kijk naar de Swagger en de statische API key invul, krijg ik de response "NotAuthorized" .
Er staat op dat elke request ook vergezeld moet zijn van een Session token. Maar hier staat geen invoerveld voor bij de Swagger.
Is de Api via de Swagger eenvoudig te testen (met session token)?
Alvast bedankt voor je antwoord!
gr Martin
Op dinsdag 16 augustus 2016 19:03:58 UTC+2 schreef Jochem Beek:
Op dinsdag 16 augustus 2016 19:03:58 UTC+2 schreef Jochem Beek:
Jochem Beek
Sep 9, 2016, 12:55:16 PM9/9/16
to openov
Beste Martin,
Mogelijk haal je de Admin API en de Client API door elkaar, we zullen proberen dit op de website te verhelderen.
Ik zie dat je reeds een Application hebt aangemaakt, je Api Key staat geregistreerd en werkt naar behoren.Mogelijk haal je de Admin API en de Client API door elkaar, we zullen proberen dit op de website te verhelderen.
Vul deze in bij de X-Vertrektijd-Client-Api-Key header, en je krijgt een valide response terug.
Ter aanvulling en verduidelijking:
We onderscheiden 3 API's: de Admin API, de Client API en de Streaming API.
De Admin API en de Client API zijn REST API's en zijn conform de OpenAPI spec gedocumenteerd en zijn reeds publiek.
De Admin API en de Client API zijn REST API's en zijn conform de OpenAPI spec gedocumenteerd en zijn reeds publiek.
De Streaming API is een SSE/EventSource API voor o.a. realtime voertuigposities, deze is nog niet gedocumenteerd en daarom nog niet publiek.
Admin API, zie ook: https://www.vertrektijd.info/swagger/admin.html
Gebruikt de (statische) API-Key in de header: "X-Vertrektijd-Admin-Api-Key:8a1b2f27652bcc20d6a02241df2a4a057ebe666b856c3aa1dd46a71c60911a84".
De Admin API integreer je bijv. in je eigen backend of CMS.
In de Admin API maak je een user account aan, met een user account krijg je toegang tot de Admin API.
Bij inloggen wordt een sessie aangemaakt, je ontvangt een session-token.
Deze session-token gebruik je in i.c.m. de bovenstaande API-Key in alle opvolgende requests naar de Admin API.
Eenmaal ingelogd kan je nog geen Application aanmaken, hiervoor dien je je eerst als Developer te registreren.
Eenmaal geregistreerd als developer, kan je Applications aanmaken. Bij het aanmaken ontvang je voor die Application een (Client) API key.
Pro Tip!
Developers die gebruik maken van de NS-API kunnen in de Admin API hun NS-API account toevoegen aan een Application.
Hierdoor is bijv. het gebruik van een proxy-server en/of het converteren van xml >> json niet meer nodig.
Client API, zie ook: https://www.vertrektijd.info/swagger/client.html
Gebruikt de (dynamische) Client API-Key in de header: "X-Vertrektijd-Client-Api-Key: {Application API-KEY}"
De Client API integreer je in je eigen toepassing (Website/App/Narrowcasting).
Testen met Swagger doe je dus met de API key die je hebt ontvangen bij het aanmaken van je Application, verder heb je niets nodig.
Pro Tip!
Voor de Client API hanteren we Semantic Versioning 2.0.
Een versie specificeren doe je in de gebruikelijke header "Accept-Version", zonder header gebruikt de API altijd de laatste versie.
Een versie specificeren doe je in de gebruikelijke header "Accept-Version", zonder header gebruikt de API altijd de laatste versie.
Minor en Patch versies (bijv. v1.1.2 of v1.2.4) zijn backwards compatible en worden ondersteund zolang de brondata dit toelaat.
Het kan daarom voordelig zijn altijd minstens een Major versie in je Application te specificeren bijv. "Accept-Version: 1",
op die manier gebruikt je applicatie altijd een versie die compatible is en geniet je automatisch van patches of fixes.
op die manier gebruikt je applicatie altijd een versie die compatible is en geniet je automatisch van patches of fixes.
Een API Key kwijt/vergeten?
Alles wat je via de Admin API aanmaakt (POST) is opvraagbaar (GET), en bewerkbaar (PATCH).
Voorbeeld:
1. Inloggen
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
"email": "mi...@email.nl",
"password": "mijnwachtwoord"
}' 'https://admin.vertrektijd.info/api/v2/user/session/'
Response: {SESSION-TOKEN}
2. API Keys Opvragen
curl -X GET --header 'Accept: application/json' --header 'X-Vertrektijd-Admin-Api-Key: 8a1b2f27652bcc20d6a02241df2a4a057ebe666b856c3aa1dd46a71c60911a84' --header 'X-Vertrektijd-Admin-Session-Token: {SESSION-TOKEN}' 'https://admin.vertrektijd.info/api/v2/vti_admin/_table/api_keys/'
Response: {API-KEY}
3. Vertrektijd Opvragen Amsterdam CS
curl -X GET --header 'Accept: application/json' --header 'Accept-Version: 1.3.0' --header 'X-Vertrektijd-Client-Api-Key: {API-KEY}' 'https://api.vertrektijd.info/departures/_nametown/Amsterdam/Centraal/'
Response: {RESULTS}
Alles wat je via de Admin API aanmaakt (POST) is opvraagbaar (GET), en bewerkbaar (PATCH).
Voorbeeld:
1. Inloggen
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
"email": "mi...@email.nl",
"password": "mijnwachtwoord"
}' 'https://admin.vertrektijd.info/api/v2/user/session/'
Response: {SESSION-TOKEN}
2. API Keys Opvragen
curl -X GET --header 'Accept: application/json' --header 'X-Vertrektijd-Admin-Api-Key: 8a1b2f27652bcc20d6a02241df2a4a057ebe666b856c3aa1dd46a71c60911a84' --header 'X-Vertrektijd-Admin-Session-Token: {SESSION-TOKEN}' 'https://admin.vertrektijd.info/api/v2/vti_admin/_table/api_keys/'
Response: {API-KEY}
3. Vertrektijd Opvragen Amsterdam CS
curl -X GET --header 'Accept: application/json' --header 'Accept-Version: 1.3.0' --header 'X-Vertrektijd-Client-Api-Key: {API-KEY}' 'https://api.vertrektijd.info/departures/_nametown/Amsterdam/Centraal/'
Response: {RESULTS}
Heb ik je hiermee geholpen?
Veel succes!
Vriendelijke groet,
Jochem
David Bonting
Oct 31, 2016, 7:41:13 AM10/31/16
to openov
Hallo Jochem,
Bedankt voor je API. Ik ben het H-E-L-E-M-A-A-L met je eens dat openOV veel te complex is. Ik heb veel ervaring, maar weet mij echt geen raad met dit alles. Van KV78turbo/CC-0 tot GTFS-RT de benaming is mij echt niet duidelijk en het feit dat er 1 miljoen verschillende databases zijn. Dan wordt je op de site en hier in de Google groep altijd door verwezen naar links als: http://gtfs.openov.nl/gtfs-rt/. Ja thanks maar wat kan ik daar mee? Hoe werkt het?
Dat is allemaal zo zonde aangezien een hoop mensen aan de slag wil met deze data. Jochem, bedankt voor je API. Hij is actuelere dan https://github.com/skywave/KV78Turbo-OVAPI/wiki. Ik heb de afgelopen dagen liggen spelen met je API, maar krijg vaak een 504 Gateway time-out. Hierdoor is eerlijk gezegd jouw API ook niet bruikbaar voor mij (omdat hij soms geen data terug geeft).
En daarom wil ik hier in deze Google groep vandaag even mijn frustratie kwijt:
- onbruikbaar: http://gtfs.openov.nl/gtfs-rt/ en al die soortgelijke links. Wat kan ik daar mee? Hoe krijg ik het aan de praat? Waar is de documentatie? WTF, zo frustrerend
- (bijna) onbruikbaar: https://github.com/skywave/KV78Turbo-OVAPI/wiki. Die heb ik weleens gebruikt voor een school project, maar kent twee problemen: 1. de data is niet actueel / live (qua tijden). 2. je krijgt alleen een stuk of 8 resultaten van een halte. Je kunt dus niet iets plannen in de middag of volgende dag bijvoorbeeld.
- (bijna) onbruikbaar: https://www.vertrektijd.info/. Geeft 50% van de tijd een 504 error of geen data. Onbruikbaar in mijn ogen.
En dat wil ik dus even kwijt. Links als http://gtfs.openov.nl/gtfs-rt/ hebben een veel te hoog instapniveau (of ik kan de documentatie niet vinden / hoe je het überhaupt aan de praat krijgt). En de overige API's zijn onbruikbaar. Zo zonde dat je hier in Nederland dus niets kan doen met het openbaar vervoer.
David
Stefan de Konink
Oct 31, 2016, 7:46:05 AM10/31/16
to ope...@googlegroups.com
On maandag 31 oktober 2016 12:41:13 CET, David Bonting wrote:
> En daarom wil ik hier in deze Google groep vandaag even mijn
> frustratie kwijt:
> onbruikbaar: http://gtfs.openov.nl/gtfs-rt/ en al die
> soortgelijke links. Wat kan ik daar mee? Hoe krijg ik het aan de
> praat? Waar is de documentatie? WTF, zo frustrerend
> (bijna)
http://lmgtfy.com/?q=gtfs-rt
> En daarom wil ik hier in deze Google groep vandaag even mijn
> frustratie kwijt:
> onbruikbaar: http://gtfs.openov.nl/gtfs-rt/ en al die
> soortgelijke links. Wat kan ik daar mee? Hoe krijg ik het aan de
> praat? Waar is de documentatie? WTF, zo frustrerend
> (bijna)
Ik ben maar gestopt met lezen.
--
Stefan
Erik van Heck
Oct 31, 2016, 7:56:46 AM10/31/16
to openov
David,
Op maandag 31 oktober 2016 12:41:13 UTC+1 schreef David Bonting:
OpenOV is geen kant-en-klare oplossing voor een end-user applicatie, of ook maar iets wat enigzins lijkt op een REST-interface.
OpenOV stelt ruwe data beschikbaar in verschillende vormen via verschillende koppelvlakken. Het is aan de ontwikkelaars om van die ruwe data een bruikbare API of applicatie te schrijven.
GTFS is één van de beschikbare databronnen. Vertrektijd.info welke je bijvoorbeeld noemt is een implementatie op een van de koppelvlakken.
Het feit dat de mensen van OpenOV, vaak onbetaald, de ruwe data beschikbaar kunnen stellen is al een heel goed fenomeen op zich. Dat verscheidene ontwikkelaars via applicaties of end-user API's data beschikbaar stellen welke foutmeldingen geven of incompleet zijn, ligt niet aan OpenOV, maar aan de desbetreffende ontwikkelaar.
Daarom mag en kan je OpenOV hier niet de schuld van geven.
Ik zou zeggen; zet een eigen applicatie op welke aansluit op een van de beschikbare databronnen / koppelvlakken en ontwikkel een API daarvoor. Kijken hoe ver je komt ;-).
Deze reactie is daarin tegen niet kwaad bedoeld, maar ik vond dat dat er ook even voor OpenOV opgestaan mocht worden.
Met gehele vriendelijke groeten,
Erik
Op maandag 31 oktober 2016 12:41:13 UTC+1 schreef David Bonting:
Jochem Beek
Oct 31, 2016, 4:18:37 PM10/31/16
to openov
Mooi he? Dat we kritisch kunnen zijn over de toegankelijkheid van actuele reisinformatie.
Geeft alleen maar aan dat we het besef van vanzelfsprekendheid al voorbij zijn. Waarvoor alle kudos daarvoor aan de OV-chef in de reacties hierboven. :)
Desalniettemin is het positief dat je direct aan de bel trekt, ik vermoed dat de stille meerderheid reeds was/is afgehaakt.
Dan inhoudelijk:
Timeouts
De timeouts die je hebt ontvangen zijn bij overmatig gebruik van de publieke API ontstaan.
De Vertrektijd.Info API is opgesplitst in een publieke/openbare API en een niet-publieke API (voor afnemers met een SLA).
Hierbij worden 4 servers (ESXI) op 3 locaties met loadbalancers ontsloten in een failover setup (2 x 2); dit doen we softwarematig (haproxy/vps) voor de gratis publieke API en hardwarematig (Aloha/colocatie) voor de niet-publieke API.
Hierdoor kunnen we private/commerciele afspraken en publiek gebruik goed gescheiden houden.
Helaas blijkt dat de publieke api al gauw onnodig wordt/werd misbruikt, 250 requests per seconde was geen uitzondering.
Om dit tijdelijk te mitigeren hebben we tijdelijk een 'harde' rate limit van pakweg 10 requests/sec per IP gehanteerd, en de betreffende gebruikers aangeschreven.
Het hanteren van een rate limit is onzes inziens echter niet wenselijk, iedere vorm van rate limiting heeft zo z'n nadelen.
We schalen daarom liever mee en maken goede afspraken.
Hier werken we aan. Inmiddels is de loadbalancer opgeschaald.
We zien geen timeouts meer in de logging van onze loadbalancer.
Ter controle en ondeugd nog even een api-wijde benchmark met jouw api-key:
siege -t*m -d* -c* -H 'X-Vertrektijd-Client-API-Key: **api key**' -i -v -f Amsterdam.txt
Transactions: 14390 hits
Availability: 99.97 %
Elapsed time: 59.26 secs
Data transferred: 133.37 MB
Response time: 0.41 secs
Transaction rate: 242.83 trans/sec
Throughput: 2.25 MB/sec
Concurrency: 100.33
Successful transactions: 14390
Failed transactions: 4
Longest transaction: 6.34
Shortest transaction: 0.06
Dan voor de liefhebbers nog een postmortem van de gefaalde requests, deze waren:
https://api.vertrektijd.info/departures/_nametown/Amsterdam/Osdorppln/ Don Boscostr
https://api.vertrektijd.info/departures/_nametown/Amsterdam/CS/ De Ruyterkade
https://api.vertrektijd.info/departures/_nametown/Amsterdam/De Boelelaan/ VU
https://api.vertrektijd.info/departures/_nametown/Amsterdam/CS/ De Ruyterkade
door gebrekkige URL-encoding: "/ " => "%2F " :)
Geen data
Mocht je geen data terugkrijgen, koppel dat dan vooral hier terug!
Of er wel of niet data aanwezig is, en of die data juist is, is lastig programmatisch te beoordelen.
Ik peuter dan ook graag het fijne voor je los.
Vriendelijke groet,
Jochem
Joel Haasnoot
Nov 1, 2016, 2:45:00 PM11/1/16
to ope...@googlegroups.com
Hoi David,
Naar aanleiding van je signaal en wat ik van de mensen om mij heen hoor heb ik gisteravond een eerste verhaaltje gemaakt. Onder de noemer "OV reisinformatie voor nerds" wil ik een serie blogs/artikelen schrijven die deze pijnpunten wegnemen. Zie hier de eerste: https://ndovloket.wordpress.com/2016/11/01/koppel-wattus-welkom-in-de-wereld-van-bus-tram-en-metro/
Ik ben begonnen met wat de verschillende koppelvlakken zijn om een basis te schetsen. Ik hoor graag wat jullie er van vinden en welke vragen jullie hebben (maar een ander topic op deze mailing list is dan handiger).
Joel Haasnoot
--
Je hebt dit bericht ontvangen omdat je bent geabonneerd op de groep "openov" van Google Discussiegroepen.
Als je je wilt afmelden bij deze groep en geen e-mails van de groep meer wilt ontvangen, stuur je een e-mail naar openov+unsubscribe@googlegroups.com.
Ga naar https://groups.google.com/d/optout voor meer opties.
David Bonting
Nov 3, 2016, 5:29:30 AM11/3/16
to openov
Bedankt voor de reacties. Gelukkig ben ik dus niet de enigste (dat merkte ik al om mij heen, maar nu ook online).
@stefan en erik, opzich is dit wel precies wat ik bedoel. Dat als je om hulp vraagt altijd naar dezelfde links wordt verwezen en er een attitude is van "duh, zo werkt het. Probeer zelf maar wat" (terwijl niemand weet hoe het werkt)
Uitleg verschil datasets: http://www.hackdeoverheid.nl/aan-de-slag-met-open-ov-data/ (wat ook in jouw blogpost goed wordt uitgelegd)
Uitleg relaties: https://developers.google.com/transit/gtfs/reference/ (mooi overzicht van het GTFS-NL bestand)
Download zelf de dataset: http://gtfs.ovapi.nl/new/gtfs-nl.zip
Er is overigens één ding waar ik op dit moment niet uit kom. In het GTFS-NL bestand mis ik "calendar.txt" (volgens mij verplicht volgens de GTFS standaarden). Hoe kom ik achter de planning van vervoerders? Op openov.nl > beschikbare datasets > dienstregelingen kom ik er niet achter. De eerste link werkt niet, de tweede link is het GTFS bestand en de derde link bevat volgens mij niet de informatie zoals beschreven op de Google pagina.
@jochem, bedankt voor de informatie. Nu begrijp ik waarom hij soms dus niets terug gaf.
@joel, ook erg bedankt voor de informatie ik zal de blogposts bijhouden! Ik ben zelf ook bezig geweest om het voor mijzelf duidelijk te maken. Zo als ik het nu zie:
Uitleg verschil datasets: http://www.hackdeoverheid.nl/aan-de-slag-met-open-ov-data/ (wat ook in jouw blogpost goed wordt uitgelegd)
Uitleg relaties: https://developers.google.com/transit/gtfs/reference/ (mooi overzicht van het GTFS-NL bestand)
Download zelf de dataset: http://gtfs.ovapi.nl/new/gtfs-nl.zip
Er is overigens één ding waar ik op dit moment niet uit kom. In het GTFS-NL bestand mis ik "calendar.txt" (volgens mij verplicht volgens de GTFS standaarden). Hoe kom ik achter de planning van vervoerders? Op openov.nl > beschikbare datasets > dienstregelingen kom ik er niet achter. De eerste link werkt niet, de tweede link is het GTFS bestand en de derde link bevat volgens mij niet de informatie zoals beschreven op de Google pagina.
Maar goed, bedankt voor de reacties. Het brengt in ieder geval veel teweeg ;)
Stefan de Konink
Nov 3, 2016, 5:44:31 AM11/3/16
to openov
On Thu, 3 Nov 2016, David Bonting wrote:
> Uitleg verschil datasets:
> http://www.hackdeoverheid.nl/aan-de-slag-met-open-ov-data/ (wat ook in jouw
> blogpost goed wordt uitgelegd)
> Uitleg relaties: https://developers.google.com/transit/gtfs/reference/ (mooi
> overzicht van het GTFS-NL bestand)
> Download zelf de dataset: http://gtfs.ovapi.nl/new/gtfs-nl.zip
Het lijkt er vooral op dat je begint met schreeuwen zonder dat je
> Uitleg verschil datasets:
> http://www.hackdeoverheid.nl/aan-de-slag-met-open-ov-data/ (wat ook in jouw
> blogpost goed wordt uitgelegd)
> Uitleg relaties: https://developers.google.com/transit/gtfs/reference/ (mooi
> overzicht van het GTFS-NL bestand)
> Download zelf de dataset: http://gtfs.ovapi.nl/new/gtfs-nl.zip
uberhaupt hebt gezocht. Dat is HBO onwaardig gedrag...
> Er is overigens één ding waar ik op dit moment niet uit kom. In het GTFS-NL
> bestand mis ik "calendar.txt" (volgens mij verplicht volgens de GTFS
> standaarden). Hoe kom ik achter de planning van vervoerders? Op openov.nl >
> beschikbare datasets > dienstregelingen kom ik er niet achter. De eerste
> link werkt niet, de tweede link is het GTFS bestand en de derde link bevat
> volgens mij niet de informatie zoals beschreven op de Google pagina.
calendar_dates.txt. If your schedule varies most days of the month, or you
want to programmatically output service dates without specifying a normal
weekly schedule, this approach may be preferable.
Stefan
Reply all
Reply to author
Forward
0 new messages