merklingen connection check: api docs

note for the impatient: you can skip most of the docs and go straight to the examples, the api isn't that cryptic :)

`./vvs/find_stop/simple/<stop>`

Can be used to check which stop a certain stop query would actually use: ./vvs/find_stop/simple/oberdrackenstein
Responds with ok: <actual name of the stop> or err: ....

`./vvs/mins_before[_check]/simple/<from>/<to>?year=&month=&day=&hour=&minute=&interchanges=&minutes=`

Searches for connections from <from> to <to> which arrive before the specified time. Can optionally filter by number of interchanges. Of the connections (after filtering), finds the one which departs last and responds with how many minutes before the specified time the found connection departs at <from>.
For example, if you request to arrive at 8:50, a trip arrives at 8:45 and departs at 8:40, then the response would be minutes: 10.

Replace <from> and <to> with the names of your origin and destination stops, and add values for the missing query parameters.
interchanges is optional and, if present, limits the search to connections with at most the specified number of interchanges. Setting interchanges=0 filters out any non-direct connections.
Additionally, you can add &allowtaxi=true to prevent the server from filtering our lines which contain "taxi" in their name (Ruftaxi/Linientaxi).
minutes is required by mins_before_check and is not used by mins_before. It limits how many minutes before the specified time, at most, you want to depart. If mins_before would respond with a number greater than the minutes parameter, mins_before_check responds with an error (410 Gone) instead, if mins_before would respond with a number smaller than or equal to the minutes parameter, mins_before_check responds with an empty string (this should be easy to check if you can't easily access the response's http status code).

mins_before responds with

a 404 (Not Found) response if the origin or destination stop could not be found: err: ...
a 410 (Gone) response if no connection was found: gone: ...
a 200 (Ok) response if one or more connections were found: minutes: <minutes as an integer>

mins_before_check responds with

a 404 (Not Found) response if the origin or destination stop could not be found: err: ...
a 410 (Gone) response if no connection was found: gone: ...
a 410 (Gone) response if all connections would take too long: gone: <a> > <b> minutes
a 200 (Ok) response if one or more connections were found. in this case, the response consists of an empty string:

If something goes wrong (especially plausible: the server's communication with the vvs api fails in some way), you may also get a 500 (Internal Server Error) response: err: ...

Examples

Assuming the bus runs normally tomorrow (10.3.2025), this should respond with an empty string:

./vvs/mins_before_check/simple/oberdrackenstein%20rathaus/merklingen%20bahnhof?year=2025&month=3&day=10&hour=8&minute=40&interchanges=0&minutes=25

and this should display about 20 minutes, since the bus usually departs at 8:20, 20 minutes before the requested 8:40:

./vvs/mins_before/simple/oberdrackenstein%20rathaus/merklingen%20bahnhof?year=2025&month=3&day=10&hour=8&minute=40&interchanges=0

You can use the first case to easily check if everything is alright (empty 200 response) or not (non-empty, non-200 response).
For convenience, you can also use the shorter and not date-dependent versions, which can optionally take override values for hours= and minute=:

./vvs/short/in_hrs/2/mins_before_check/oberdrackenstein%20rathaus/merklingen%20bahnhof?minute=40&interchanges=0&minutes=25

and ./vvs/short/in_hrs/0.5/mins_before/oberdrackenstein%20rathaus/merklingen%20bahnhof?interchanges=0

Usage Examples

With sh and curl (replace the echo command with whatever command you want to run if the bus may not arrive as expected):

curl -f 'https://tomatenmhark.org/nöpnv/vvs/short/in_hrs/1/mins_before_check/oberdrackenstein%20rathaus/merklingen%20bahnhof?minute=40&interchanges=0&minutes=25' || echo whoops, bus gone