Public Transit API

Transit routing, real-time vehicle data, timetables, and GTFS downloads across 90+ countries

Version 2.0 Base URL: https://capi.busmaps.com:8443 Machine-readable spec (JSON)
Use this API from AI agents

Every endpoint here is also exposed as an MCP tool. Point any MCP client (Claude, ChatGPT, Gemini, Cursor) at https://mcp.busmaps.com/mcp - the agent reads the tools, schemas, and examples itself, no docs pasting needed. Your API key powers both REST and MCP.

About the MCP server →

Authentication

All API requests require authentication using API key and host headers

Required Headers

capi-key Required

Bearer token with your API key

Format: Bearer YOUR_API_KEY
capi-host Required

Platform host for data source

Format:
Options: busmaps.com, wikiroutes.info

Platform Hosts

busmaps.com

Global transit data coverage (official data from busmaps.com)

wikiroutes.info

Coverage provided by wikiroutes.info crowdsourcing project

Rate Limits

Limits are enforced per API key, per endpoint. Exceeding one returns 429 Too Many Requests. These are the Free tier limits:

Endpoint Per day Per month
All endpoints (combined) 10,000 150,000
routes 1,500 10,000
nextDepartures 6,000 50,000
stopsInRadius 6,000 50,000
rawVehiclePositions 1,000 10,000
getGtfsFeedsDownloads 50 1,000

Pedestrian routing and geocoding are available on paid plans. Need higher limits? See plans & pricing.

Example Request

curl -H "capi-key: Bearer YOUR_API_KEY" -H "capi-host: busmaps.com" "https://capi.busmaps.com:8443/routes?origin=51.52,-0.149&destination=51.50,-0.108"

Available Endpoints

/routes

Calculate optimal public transport routes with real-time data integration

/nextDepartures

Retrieve scheduled and real-time departure information from public transport stops. Two modes: search by coordinates (location) or query a specific stop (stopId + regionName from /stopsInRadius response)

/stopsInRadius

Search for all public transport stops within a given radius of coordinates

/line

Return a route's full timetable: directions, ordered stops, inline geometry and the schedule as a trips x stops grid. Addressed by routeId + regionName from a /stopsInRadius or /nextDepartures response. countryIso is required on the busmaps.com host and must be omitted on wikiroutes.info. The embedded alerts[] block is a busmaps.com feature only - wikiroutes.info responses never include it.

/alerts

Return current service alerts (disruptions) filtered to a single route or a single operator. Lightweight alternative to fetching the whole /line card just for its alerts: call it in parallel with the route/operator screen. Pass exactly one of routeId or operatorId. Alerts are a busmaps.com feature only - wikiroutes.info has none, so there is no reason to call this endpoint there. The alert objects are identical to the alerts[] embedded in /line and /nextDepartures.

/trip

Return a single trip (one scheduled vehicle run) as an ordered list of stops with arrival/departure times and GTFS boarding rules (pickupType/dropOffType). Addressed by tripId + regionName from a /nextDepartures or /rawVehiclePositions response.

/rawVehiclePositions

Retrieve raw real-time vehicle positions within specified geographic bounds. positionType: 'gps' - real position, 'estimated' - derived from trip updates. Can be filtered by route (routeId + countryIso) or trip (tripId). Real-time vehicle positions are a busmaps.com feature only - wikiroutes.info has none, so there is no reason to call this endpoint there.

/pedestrian/route/lon,lat;lon,lat

Calculate optimal walking routes between coordinates using OSRM pedestrian routing. Prioritizes pedestrian infrastructure like sidewalks and footpaths. Compatible with OSRM API specification.

/pedestrian/matrix/lon,lat;lon,lat

Calculate distance and duration matrices between multiple coordinates for pedestrian routing. Compatible with OSRM matrix API.

/getGtfsFeedsDownloads

Access the GTFS feed catalog with original and improved data, validation reports, licenses, short public content and artifact hashes, and versioned download URLs. Filter by countryIso or feedName and save each file using downloadFileName.

/nominatim/reverse

Convert geographic coordinates (latitude, longitude) into a human-readable address using OpenStreetMap Nominatim. Worldwide coverage with detailed address components.

/nominatim/search

Search for locations by name, address, or place using OpenStreetMap Nominatim. Returns coordinates and details for matching locations. Worldwide coverage.

/photon/api

Forward geocoding with prefix/autocomplete support using Photon (Komoot). Supports partial queries, location bias, bounding box filter and OSM layer/tag filters. Returns GeoJSON FeatureCollection.

/photon/reverse

Reverse geocoding using Photon (Komoot). Returns the nearest OSM object as a GeoJSON FeatureCollection. The nearest object may be a street, building or POI.

Common Response Fields

Most API responses include additional metadata and processing information:

processingTimeMs

number

Server processing time for the request in milliseconds

Example: 156.68
Available in: routes, nextDepartures, stopsInRadius

regionName

string

Geographic region identifier for the request

Example: "uk_ireland"
Available in: routes, nextDepartures, stopsInRadius

imperial

boolean

Whether distances and measurements use imperial units

Example: true
Available in: routes, nextDepartures, stopsInRadius

Note: Pedestrian routing endpoints (pedestrianRoute, pedestrianMatrix) are powered by OSRM and follow a different response format without these common fields.

HTTP Status Codes

200

OK

Request was successful and returned valid data

Response includes:
  • Requested data (routes, departures, etc.)
  • Processing time metrics
400

Bad Request

Invalid request parameters or malformed request

Common causes:
  • Missing required parameters
  • Invalid coordinate format
  • Invalid parameter values
500

Internal Server Error

Unexpected server error occurred

Possible reasons:
  • Server processing error
  • Database connectivity issues
  • Internal service failure
502

Bad Gateway

Upstream service is unavailable or responding incorrectly

Common scenarios:
  • Transit data service outage
  • Routing service unavailable
  • External API connectivity issues