improve /stops, /locations & /journeys documentation

[mbariola]

Hi,

I wanted to reactivate some old code using your API which has been decommissioned, and it seems there may be some things not working.
For instance, I have been trying these links from your documentation
https://3.vbb.transport.rest/journeys?from=900000023201&to.id=900980720&to.name=ATZE%20Musiktheater&to.latitude=52.543333&to.longitude=13.351686 { "error": true, "msg": "invalid to.type: location" }

https://3.vbb.transport.rest/stops Cannot GET /stops

I discovered that when trying to do a /journeys request passing an origin in address form. Then I tried some of the listed examples and got errors too.

Also, could you please clarify in docs e.g. for address format if address AND latitude AND longitude are all three required? I suppose either of the three as long as to and from are univocally determined, but may be mistaken. Thanks for looking into it!

[derhuerst]

Thanks for reporting this!

The developer experience & documentation on *.transport.rest is pretty bad right now, it hasn't been my top priority in the past year. Especially, documentation on possible /journeys inputs is lacking a lot and outdated.

https://3.vbb.transport.rest/journeys?from=900000023201&to.id=900980720&to.name=ATZE%20Musiktheater&to.latitude=52.543333&to.longitude=13.351686 { "error": true, "msg": "invalid to.type: location" }

This is a bug, fixed in the underlying library hafas-rest-api as of public-transport/hafas-rest-api@099d49d. This should be working on 3.vbb.transport.rest now.

https://3.vbb.transport.rest/stops Cannot GET /stops

This is a documentation issue, let's fix it!

At some point, I messed up /stops and /stations, there has already been confusion about that in derhuerst/bvg-rest#6.

I discovered that when trying to do a /journeys request passing an origin in address form. Then I tried some of the listed examples and got errors too.

Can you give a specific URL?

I will add an example with an address as the destination: https://3.vbb.transport.rest/journeys?from=900000023201&to.latitude=52.540673&to.longitude=13.386673&to.address=13355%20Berlin-Gesundbrunnen%2C%20Voltastr.%2017%22. Would that be helpful?

Also, could you please clarify in docs e.g. for address format if address AND latitude AND longitude are all three required? I suppose either of the three as long as to and from are univocally determined, but may be mistaken.

All three have "required" next to them. How would you change it to be more understandable?

[mbariola]

Hi there thanks for the quick reply!

So:

https://3.vbb.transport.rest/journeys?from=900000023201&to.id=900980720&to.name=ATZE%20Musiktheater&to.latitude=52.543333&to.longitude=13.351686

gives a response now. I have to check in detail but overall it looks like the structure I remember

https://3.vbb.transport.rest/journeys?from.address=%27Weserstr.%2037%27&to.address=%27Alexanderplatz%27&results=1&when=1581896878&fuzzy=true this one doesn't seem to work

https://3.vbb.transport.rest/stations/all this one now seems to work. Could it be that it is not adding an application/json content-type header though?

Many thanks!

[derhuerst]

https://3.vbb.transport.rest/journeys?from.address=%27Weserstr.%2037%27&to.address=%27Alexanderplatz%27&results=1&when=1581896878&fuzzy=true this one doesn't seem to work

fuzzy is not a valid parameter of /journeys. What do you want to do?

https://3.vbb.transport.rest/stations/all this one now seems to work. Could it be that it is not adding an application/json content-type header though?

It does. curl -X HEAD -I 'https://3.vbb.transport.rest/stations/all' gives me this:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=864000
Content-Length: 7252010
Content-Type: application/json; charset=UTF-8
Date: Mon, 17 Feb 2020 14:06:56 GMT
Etag: W/"6ea82a-7438674ba0"
Last-Modified: Sat, 26 Oct 1985 08:15:00 GMT
Server: Caddy
Strict-Transport-Security: max-age=864000; includeSubDomains
Vary: Accept-Encoding
X-Api-Version: 0.4.0
X-Powered-By: vbb-rest 0.4.0 https://github.com/derhuerst/vbb-rest

[mbariola]

https://3.vbb.transport.rest/journeys?from.address=%27Weserstr.%2037%27&to.address=%27Alexanderplatz%27&results=1&when=1581896878

I tried to add fuzzy just in case that there was a different spelling of the street, but even without fuzzy I get a missing origin error. I wanted journeys from Weserstr. 37 to alexanderplatz.

Re the json, hmm, good, my browser doesn't format it, maybe the size of response exceeds its ability to prettify

[mbariola]

also for instance, this link:
https://3.vbb.transport.rest/journeys?from.latitude=52.488165&from.longitude=13.445107&to=900000260005&results=1 no matter whether I specify a when parameter or not

[mbariola]

I discovered that when trying to do a /journeys request passing an origin in address form. Then I tried some of the listed examples and got errors too.

Can you give a specific URL?

I will add an example with an address as the destination: https://3.vbb.transport.rest/journeys?from=900000023201&to.latitude=52.540673&to.longitude=13.386673&to.address=13355%20Berlin-Gesundbrunnen%2C%20Voltastr.%2017%22. Would that be helpful?

I just tried it, and saw that I need to specify all three parameters indeed, but that seems redundant and overkill given that lat/lon <==> address. Was it always like this? my old code has calls like this and worked. the new method requires to make a query just to have the right lat/lon from the address or vice versa before calling the API.

https://vbb.transport.rest/journeys?from.latitude=52.488165&from.longitude=13.445107&to=900000087171&results=1&when=1581963560

having just lat/lon was sufficient (please note the domain part of the url, these URLs are those I used back in sept 2017, I have not used this code since then). Maybe I am missing something?

[mbariola]

I tried this:
https://3.vbb.transport.rest/journeys?from.latitude=52.488165&from.longitude=13.445107&from.address=THIS_ADDRESS_IS_A_FAKE_PLACEHOLDER&to=900000260005&results=1

and it DOES work (i.e. results are corresponding to closest station), even though from.address is clearly a fake place which gets replicated in the response. I don't know if it is in your power to address this (i.e. use just either one of lat+lon OR address), for the time being I'll just use a placeholder, for my use case is good enough but I'll need to remove a "check by address"

[derhuerst]

I tried this: https://3.vbb.transport.rest/journeys?from.latitude=52.488165&from.longitude=13.445107&from.address=THIS_ADDRESS_IS_A_FAKE_PLACEHOLDER&to=900000260005&results=1

and it DOES work (i.e. results are corresponding to closest station), even though from.address is clearly a fake place which gets replicated in the response.

Yes, the from.address is just being "passed through" to the resulting journeys. This is how the underlying HAFAS system works unfortunately.

I don't know if it is in your power to address this (i.e. use just either one of lat+lon OR address), for the time being I'll just use a placeholder, for my use case is good enough but I'll need to remove a "check by address"

Because of the aforementioned HAFAS limitation, you need to pass address. If vbb-rest would not require you to provide it and just use e.g. foo when calling HAFAS, foo would end up in the resulting journeys as legs[0].origin.address, which would be unintuitive for consumer to say the least.

The developer experience is bad – I'm aware of that –, but right now, you need to use /locations to find an address, and pass all three fields latitude, longitude & address to /journeys in order to get journeys starting at that address.

Was it always like this? my old code has calls like this and worked

[...] having just lat/lon was sufficient (please note the domain part of the url, these URLs are those I used back in sept 2017, I have not used this code since then).

It may have worked that way with the old vbb.transport.rest API, but AFAIR you got bogus address values in the resulting journeys back then. I made the address parameter mandatory to prevent subtly wrong results.

[derhuerst]

Re-reading our discussion here, I can see that the /locations, /stops & /journeys docs are not helpful right now. I'd propose two changes:

• per API "method", specify more thoroughly the purpose of each parameter,
• include a "cook book" section that covers common use cases, such as "finding journeys from an address".

Unfortunately, improving vbb-rest/bvg-rest/db-rest/hvv-rest (or the underlying hafas-rest-api rather) is not a priority for me right now, because I'm planning to create a different, more powerful public transport API anyways (sneak peek).

I'd be happy to review & merge a PR that improves documentation though!

[mbariola]

Re-reading our discussion here, I can see that the /locations, /stops & /journeys docs are not helpful right now. I'd propose two changes:

• per API "method", specify more thoroughly the purpose of each parameter,
• include a "cook book" section that covers common use cases, such as "finding journeys from an address".

Unfortunately, improving vbb-rest/bvg-rest/db-rest/hvv-rest (or the underlying hafas-rest-api rather) is not a priority for me right now, because I'm planning to create a different, more powerful public transport API anyways (sneak peek).

I'd be happy to review & merge a PR that improves documentation though!

I might try that, I am a little bit under deadline for my main project at the moment but yes it'll help also me to improve my understanding of the api. Let me underpromise and who knows hopefully overdeliver! Cookbook might be a little too much above my capabilities atm.

New api looks quite cool, is it an aggregator / proxy for different local infomobility services?

Also re /locations : just did 1 quick test, I can work with that in case I need to start from an address. As long as I have a chain of calls I can make to get where I need, it works :-) thanks.

[derhuerst]

New api looks quite cool, is it an aggregator / proxy for different local infomobility services?

Yes, in a way. From #41 (comment) :

There is a more systematic approach however: building a network of federated data sources and/or APIs. With your use case, that would let use ask the respective local endpoints about IDs of e.g. Zwickau, and then do routing across the federated data sets.

This is a complex endeavour however, and AFAICT there's little existing work out there. Check the stable-public-transport-ids readme for the bigger picture, pan-european-public-transport for a work-in-progress implementation, and public-transport/ideas#1 for a higher-level general chat about how to get data across Europe.

[derhuerst]

FYI I have set up v5.vbb.transport.rest, which has slightly more intuitive route names and documentation.