Getting started

All requests go to https://api.transcapi.com. Pass your key on every request via the X-Api-Key header:

curl "https://api.transcapi.com/v1/bus/stops.json?lat=53.3824&lon=-1.4695&radius=100" \
  -H "X-Api-Key: YOUR_API_KEY"

Or via the api_key query parameter if headers aren't convenient:

curl "https://api.transcapi.com/v1/bus/stops.json?lat=53.3824&lon=-1.4695&radius=100&api_key=YOUR_API_KEY"

Each stop comes back with towards, the way its buses go. Show it beside the name: it's how a passenger tells the stop from the one across the road.

One request in each area

What's leaving a bus stop

curl "https://api.transcapi.com/v1/bus/stop_timetables/370022870.json?live=true" \
  -H "X-Api-Key: YOUR_API_KEY"

A tracked bus has an expected time, delay_seconds and source: "avl"; an untracked one keeps its timetabled time with source: "gtfs_scheduled". Add type=arrivals for what's arriving, including buses that terminate here.

Live trains at a station

curl "https://api.transcapi.com/v1/rail/station_timetables/LDS.json" \
  -H "X-Api-Key: YOUR_API_KEY"

Expected times, platforms, cancellations and delay reasons from National Rail. Pass any departure's trip_id to /v1/rail/services/{trip_id}.json to follow that train station by station.

Buses on the road near a point

curl "https://api.transcapi.com/v1/bus/vehicles.json?lat=53.3811&lon=-1.4701&radius=1500" \
  -H "X-Api-Key: YOUR_API_KEY"

Each bus carries the trip_id of the journey it's working, the same id departures use, so you can show exactly where the bus a passenger is waiting for has got to.

What's disrupting a journey

curl "https://api.transcapi.com/v1/disruptions.json?path=ENCODED_POLYLINE&path_radius=300" \
  -H "X-Api-Key: YOUR_API_KEY"

Pass the journey's geometry, for example a leg's leg_geometry from journey planning or a route direction's shape.encoded_polyline, and only disruptions naming a stop near it come back. See matching a disruption to a route.

Being told when your bus is near

curl -X POST "https://api.transcapi.com/v1/alerts.json" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"type": "vehicle_approaching", "atcocode": "370022870", "minutes": 5,
       "url": "https://example.com/hooks/transcapi"}'

TransCAPI posts signed JSON to your URL when a tracked bus is due at that stop within 5 minutes. Keep the secret in the response to check the signature. See push alerts.

Finding a place

curl "https://api.transcapi.com/v1/places.json?query=S1%201AA" \
  -H "X-Api-Key: YOUR_API_KEY"

Towns, villages, postcodes, streets, landmarks and stops. Places sharing a name are ranked by size, so Newport finds the city first, and Broad Street, Sheffield finds the street in Sheffield.

Before you ship

Add the attribution line from Data sources & attribution somewhere your users can see it. The source licences require it.
Handle null: missing geometry, unknown delays and live feeds that are down all come back as null or a scheduled time, never a guess.
Read the X-RateLimit-* headers to stay inside your limits.

See your key and usage anytime from your dashboard.