BusMaps

byAPI3·Free·Airnode v0.1.0

BusMaps is a public transport API over official operator data: the stops, timetables, journey plans, service alerts and live vehicle positions of transit networks worldwide, assembled from the GTFS and GTFS-Realtime feeds the operators publish. This Airnode wraps its read endpoints, so a consumer receives a departure board or a vehicle's position with a signature saying this Airnode obtained it from BusMaps at this time.

What is worth attesting here is the part that does not survive: a scheduled timetable can be looked up again tomorrow, but where a bus was and how late it was running is gone the moment it moves. vehiclePositions and the live departure fields are readings of a moment, and a signed copy is the only thing afterwards that says what that moment held.

Coverage follows whether an operator publishes a feed, so it varies by city rather than by country, and the API says which case a caller is in rather than leaving it to be guessed. stopsInRadius drops its stops key entirely and carries a message instead. planJourney, nextDepartures and vehiclePositions answer with an empty list and a notices entry. The code on that notice separates the two reasons. noCoverage means BusMaps holds nothing for the region. noRouteFound means the region is covered and these two points still cannot be connected. Read the notice before concluding from silence that nothing runs. Real-time data is a second, narrower question: a network can be fully timetabled and feed no live positions at all, in which case the live time fields are simply absent and vehiclePositions is empty.

Eight operations here are not transit data, and a caller reads them either side of a transit answer. driveRoute and driveMatrix say what the same trip costs by car, in time and distance, which is what makes a ride worth taking. walkRoute and walkMatrix cover the part of a journey no vehicle covers, and say how far apart two stops are on foot. geocode, geocodeReverse, geocodeAutocomplete and geocodeNearest turn a place name into the coordinate every transit operation here takes, and back. They come from OSRM, Nominatim and Photon rather than from operator feeds, and each answers in its own service's shape rather than in BusMaps'.

Everything except a journey plan and a viewport of vehicles is addressed by an identifier, and stopsInRadius is where identifiers come from: it answers with the stopId that nextDepartures takes and, under each stop's routes, the routeId that routeTimetable and alerts take. A tripId comes from a departure or a vehicle. Every response carries regionName at its top level and every id carries a countryIso beside it, and both are needed to address anything: an id means nothing without the region that issued it and the country that prefixes it.

Every response carries an EIP-191 signature from the Airnode that served it, so the data can be attributed back to its source rather than trusted on reputation.

Interface

Served at https://airnode-busmaps.fly.dev/. The two requests below are everything the endpoint speaks, and each can be sent from this page. What comes back is verified right here in the browser.