gtfs.media

GTFS Media API

The read API exposed by a gtfs.media deployment. Static

Operations

33 operations across 4 groups.

Discovery

GET / · GET /feeds · GET /feeds/{feed_alias}

Static GTFS

GET /feeds/{feed_alias}/agencies · GET /feeds/{feed_alias}/agencies/{agency_id} · GET /feeds/{feed_alias}/agencies/{agency_id}/routes · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id} · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/geojson · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/directions · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/directions/{direction_id} · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/stops/{direction_ids} · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id} · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/stop_times · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/schedules/{service_id}/{direction_id} · GET /feeds/{feed_alias}/services · GET /feeds/{feed_alias}/services/{service_id} · GET /feeds/{feed_alias}/shapes/{shape_id} · GET /feeds/{feed_alias}/stops · GET /feeds/{feed_alias}/stops/{stop_id} · GET /feeds/{feed_alias}/stops/{stop_id}/routes · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/wkt · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/geojson · GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/stops · GET /feeds/{feed_alias}/shapes · GET /feeds/{feed_alias}/shapes/{shape_id}/geojson · GET /feeds/{feed_alias}/stops/{stop_id}/directions · GET /feeds/{feed_alias}/stops/{stop_id}/trips · GET /feeds/{feed_alias}/stops/{stop_id}/stop_times

Realtime

GET /rt/tripupdates/{stop_id} · GET /rt/vehicles/{route_id} · GET /rt/alerts/{entity_type}/{entity_id}

Display

GET /display/annotations/{entity_type}/{entity_id}

Discovery

Finding out what a deployment serves.

List every resource the deployment serves

Returns each REST resource with its URI template. Useful for discovering the surface of an unfamiliar deployment.

GET /
Parameters for GET /
Parameter In Required Type
`undefined` no

List available feeds

Every feed loaded into the deployment, with its alias.

GET /feeds
Parameters for GET /feeds
Parameter In Required Type
`undefined` no

Describe one feed

Feed metadata, plus links to its collections in meta.links.

GET /feeds/{feed_alias}
Parameters for GET /feeds/{feed_alias}
Parameter In Required Type
`undefined` no
`undefined` no

Static GTFS

Scheduled service, imported from the agency's GTFS feed.

List agencies

Contents of agency.txt.

GET /feeds/{feed_alias}/agencies
Parameters for GET /feeds/{feed_alias}/agencies
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get one agency

GET /feeds/{feed_alias}/agencies/{agency_id}
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no

List routes

Contents of routes.txt for one agency.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get one route

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get a route's shape as GeoJSON

A GeoJSON Feature whose geometry is a MultiLineString covering every shape the route's trips reference. Route identity and styling (route_color, route_text_color) travel in properties, ready to hand to a map library.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/geojson
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/geojson
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List a route's directions

The directions the route operates in, derived from its trips. Direction names come from the feed where present.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/directions
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/directions
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get one direction of a route

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/directions/{direction_id}
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/directions/{direction_id}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List the stops a route serves

Stops along the route, in service order, for one or more directions.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/stops/{direction_ids}
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/stops/{direction_ids}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`direction_ids` path yes string
`undefined` no
`undefined` no
`undefined` no

List a route's trips

Contents of trips.txt for this route. Large routes run to thousands of trips; page with limit and offset.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get one trip

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List a trip's stop times

Contents of stop_times.txt for the trip, in stop_sequence order. Times may exceed 24 hours ("25:10:00") for service running past midnight, per the GTFS specification.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/stop_times
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/stop_times
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get a route timetable

A timetable for one route, service and direction: the ordered stops and the trips that call at them, assembled ready to render as a grid.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/schedules/{service_id}/{direction_id}
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/schedules/{service_id}/{direction_id}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List service calendars

Service calendars from calendar.txt. Each item carries the weekly pattern and date range; fetch a single service to add its exceptions from calendar_dates.txt.

GET /feeds/{feed_alias}/services
Parameters for GET /feeds/{feed_alias}/services
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get one service calendar

The weekly service pattern, the date range it applies over, and any exceptions from calendar_dates.txt.

GET /feeds/{feed_alias}/services/{service_id}
Parameters for GET /feeds/{feed_alias}/services/{service_id}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no

Get a shape's points

The ordered points of one shape from shapes.txt. For route geometry ready to draw, prefer the route GeoJSON resource.

GET /feeds/{feed_alias}/shapes/{shape_id}
Parameters for GET /feeds/{feed_alias}/shapes/{shape_id}
Parameter In Required Type
`undefined` no
`shape_id` path yes string
`undefined` no
`undefined` no
`undefined` no

List stops

Contents of stops.txt. Systems commonly have thousands of stops and the default page is 500; follow meta.links.next to page through.

GET /feeds/{feed_alias}/stops
Parameters for GET /feeds/{feed_alias}/stops
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get one stop

GET /feeds/{feed_alias}/stops/{stop_id}
Parameters for GET /feeds/{feed_alias}/stops/{stop_id}
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no

List the routes calling at a stop

GET /feeds/{feed_alias}/stops/{stop_id}/routes
Parameters for GET /feeds/{feed_alias}/stops/{stop_id}/routes
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get a route's shape as WKT

The same geometry as the GeoJSON resource, as a Well-Known Text MULTILINESTRING. Useful for loading straight into PostGIS or another geospatial tool. The payload is a bare string, not an object.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/wkt
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/wkt
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get a trip's shape as GeoJSON

A GeoJSON Feature for one trip's path — a LineString, where the route resource returns a MultiLineString covering every variant. properties carries the trip's identity and headsign.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/geojson
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/geojson
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List the stops a trip calls at

Stops on this trip, in stop_sequence order.

GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/stops
Parameters for GET /feeds/{feed_alias}/agencies/{agency_id}/routes/{route_id}/trips/{trip_id}/stops
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List shape ids

Every shape_id in the feed, with a link to its points. Identifiers only — fetch a shape for its geometry.

GET /feeds/{feed_alias}/shapes
Parameters for GET /feeds/{feed_alias}/shapes
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Get a shape as GeoJSON

A GeoJSON Feature whose geometry is the shape's LineString. Carries no properties; the shape id is in the request.

GET /feeds/{feed_alias}/shapes/{shape_id}/geojson
Parameters for GET /feeds/{feed_alias}/shapes/{shape_id}/geojson
Parameter In Required Type
`undefined` no
`shape_id` path yes string
`undefined` no

List the route directions serving a stop

Every route-and-direction combination that calls at this stop. Each item embeds the full route, so a departure board can be built from one request.

GET /feeds/{feed_alias}/stops/{stop_id}/directions
Parameters for GET /feeds/{feed_alias}/stops/{stop_id}/directions
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List the trips calling at a stop

Every trip that stops here. Busy stops run to thousands of trips across all service days; page with limit and offset.

GET /feeds/{feed_alias}/stops/{stop_id}/trips
Parameters for GET /feeds/{feed_alias}/stops/{stop_id}/trips
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

List scheduled calls at a stop

Every scheduled arrival and departure at this stop, across all trips and service days — the timetable for one stop. Filter by service day using the service_id on the referenced trips.

GET /feeds/{feed_alias}/stops/{stop_id}/stop_times
Parameters for GET /feeds/{feed_alias}/stops/{stop_id}/stop_times
Parameter In Required Type
`undefined` no
`undefined` no
`undefined` no
`undefined` no
`undefined` no

Realtime

GTFS-Realtime, decoded from Protobuf and served as JSON.

Predicted arrivals and departures at a stop

GTFS-Realtime TripUpdate entities affecting this stop, decoded from Protobuf. Realtime feeds may identify stops differently from the static feed — many agencies publish stop_code in realtime and stop_id in the schedule. Use the identifier your realtime feed uses. meta.last_fetched is the Unix timestamp of the last successful poll of the upstream feed. Compare it against your own clock to d

GET /rt/tripupdates/{stop_id}
Parameters for GET /rt/tripupdates/{stop_id}
Parameter In Required Type
`stop_id` path yes string
`undefined` no

Live vehicle positions on a route

GTFS-Realtime VehiclePosition entities for the route, with coordinates, bearing and speed where the agency publishes them.

GET /rt/vehicles/{route_id}
Parameters for GET /rt/vehicles/{route_id}
Parameter In Required Type
`undefined` no
`undefined` no

Service alerts affecting an entity

GTFS-Realtime Alert entities whose informed entities include the one addressed. Returns an empty array when nothing is disrupted.

GET /rt/alerts/{entity_type}/{entity_id}
Parameters for GET /rt/alerts/{entity_type}/{entity_id}
Parameter In Required Type
`entity_type` path yes enum: stop, stops, route, routes, trip, trips, agency, agencies
`entity_id` path yes string
`undefined` no

Display

Operator annotations and overrides attached to GTFS entities.

Operator annotations for an entity

Notes and overrides staff have attached to a GTFS entity — a boarding change, a temporary closure, a message for one route at one stop. Only annotations currently within their active time window are returned. body is text-format processed HTML.

GET /display/annotations/{entity_type}/{entity_id}
Parameters for GET /display/annotations/{entity_type}/{entity_id}
Parameter In Required Type
`entity_type` path yes enum: stops, routes, trips, agency
`entity_id` path yes string
`undefined` no

Schemas

27 object types the operations above return.

Envelope

The wrapper every successful response shares. data is an object for single resources and an array for collections.

Fields of Envelope
Field Type Required Notes
`meta` Meta yes
`data` yes The payload; shape depends on the resource.

Meta

Counts, paging state and related links.

Fields of Meta
Field Type Required Notes
`totalCount` integer no Total items matching the request, ignoring paging.
`dataCount` integer no Items in this response.
`limit` integer no Page size in effect. `0` where paging does not apply.
`offset` integer no Items skipped.
`links` Links no
`last_fetched` integer no Realtime resources only. Unix timestamp of the last successful poll of the upstream GTFS-Realtime feed.

Error

Error document returned for 4xx and 5xx responses.

Fields of Error
Field Type Required Notes
`message` string no Human-readable explanation.

ResourceDescriptor

One resource advertised by the API root.

Fields of ResourceDescriptor
Field Type Required Notes
`id` string no Internal plugin id.
`label` string no Human-readable name.
`uri_template` string no RFC 6570 URI template for the resource.

Feed

An imported GTFS feed.

Fields of Feed
Field Type Required Notes
`name` string no Name given at import
`alias` string no Alias used in paths.
`link` string uri no The feed's own resource.

Agency

A row of agency.txt.

Fields of Agency
Field Type Required Notes
`label` string no Human-readable label for the row.
`agency_id` string no
`agency_name` string no
`agency_url` string uri no
`agency_timezone` string no
`agency_lang` string,null no
`agency_phone` string,null no
`agency_fare_url` string,null no
`agency_email` string,null no
`links` Links no

Route

A row of routes.txt. Deployments may enrich route payloads with their own fields through hook_gtfs_route_data_alter() — an agency logo URL, a route map image. Treat unrecognised keys as additive rather than an error.

Fields of Route
Field Type Required Notes
`label` string no
`route_id` string no
`agency_id` string no
`route_short_name` string,null no Public-facing designation, e.g. "38R".
`route_long_name` string,null no
`route_desc` string,null no
`route_type` string no GTFS route type as a string, e.g. "3" for bus.
`route_url` string,null no
`route_color` string,null no Six-digit hex, no leading "#".
`route_text_color` string,null no
`route_sort_order` string,null no
`continuous_pickup` string,null no
`continuous_drop_off` string,null no
`network_id` string,null no
`links` Links no

Stop

A row of stops.txt.

Fields of Stop
Field Type Required Notes
`label` string no
`stop_id` string no
`stop_code` string,null no Rider-facing code
`stop_name` string no
`stop_desc` string,null no
`stop_lat` string no Latitude as a string.
`stop_lon` string no Longitude as a string.
`zone_id` string,null no
`stop_url` string,null no
`location_type` string,null no
`parent_station` string,null no
`stop_timezone` string,null no
`wheelchair_boarding` string,null no
`platform_code` string,null no
`tts_stop_name` string,null no Pronunciation hint for speech output.
`level_id` string,null no
`links` Links no

Trip

A row of trips.txt.

Fields of Trip
Field Type Required Notes
`label` string no
`trip_id` string no
`route_id` string no
`service_id` string no
`trip_headsign` string,null no Destination shown to riders.
`trip_short_name` string,null no
`direction_id` string,null no
`block_id` string,null no
`shape_id` string,null no
`wheelchair_accessible` string,null no
`bikes_allowed` string,null no
`links` Links no

StopTime

A row of stop_times.txt.

Fields of StopTime
Field Type Required Notes
`label` string no
`trip_id` string no
`arrival_time` string,null no May exceed 24h, e.g. "25:10:00".
`departure_time` string,null no
`stop_id` string no
`location_group_id` string,null no
`stop_sequence` string no Order within the trip
`stop_headsign` string,null no
`start_pickup_drop_off_window` string,null no
`end_pickup_drop_off_window` string,null no
`pickup_type` string,null no
`drop_off_type` string,null no
`continuous_pickup` string,null no
`continuous_drop_off` string,null no
`shape_dist_traveled` string,null no
`timepoint` string,null no
`pickup_booking_rule_id` string,null no
`drop_off_booking_rule_id` string,null no
`links` no Present when listed for a stop; a trip's own stop times omit it.

Direction

A direction a route operates in.

Fields of Direction
Field Type Required Notes
`label` string no
`route_id` string no
`direction_id` string no
`direction` string no Name of the direction.
`route` no The full route, embedded when the direction is reached through a stop, so a departure board needs one request. Absent on a route's own directions.
`service` no The service calendar, where the deployment resolves one. Often `null`.
`links` Links no

Service

A service calendar: which days it runs, over what date range, and the dates that deviate.

Fields of Service
Field Type Required Notes
`label` string no
`service_id` string no
`monday` string no "1" when service runs, "0" when not.
`tuesday` string no
`wednesday` string no
`thursday` string no
`friday` string no
`saturday` string no
`sunday` string no
`start_date` string date-time no First day of service, ISO 8601 — not GTFS `YYYYMMDD`.
`end_date` string date-time no Last day of service, ISO 8601.
`exceptions` array of object no Dates that deviate, from `calendar_dates.txt`. Returned by the single-service resource; the collection omits it.
`links` Links no

ShapeStub

Item shape returned by the shapes collection — an identifier and a link to its points, not the geometry itself.

Fields of ShapeStub
Field Type Required Notes
`shape_id` string no
`links` Links no

ShapePoint

One point of a shape, from shapes.txt.

Fields of ShapePoint
Field Type Required Notes
`label` string no
`shape_id` string no
`shape_pt_lat` string no
`shape_pt_lon` string no
`shape_pt_sequence` string no
`shape_dist_traveled` string,null no

Schedule

A timetable for one route, service and direction, pre-assembled as a grid: schedule.stops are the rows and schedule.trips the columns. Each trip's stop_times array is positionally aligned to schedule.stops and always the same length: index n is that trip's call at stops[n], or null where the trip skips it. Render the grid by walking the two in step — do not match on stop_id.

Fields of Schedule
Field Type Required Notes
`agency_id` string no
`route_id` string no
`service_id` string no
`direction_id` string no
`schedule` object no The grid itself.

ScheduleCell

One call in a timetable grid.

Fields of ScheduleCell
Field Type Required Notes
`stop_id` integer no The stop for this cell. Note this is an **integer** here, while `Stop.stop_id` elsewhere in the API is a string.
`arrival_time` string no Arrival formatted for display.
`arrival_time_seconds` integer no The same arrival as seconds after midnight, for sorting and comparison. Values above 86400 are service past midnight.

GeoJsonFeature

A GeoJSON Feature (RFC 7946). Coordinates are [longitude, latitude] and are real numbers, unlike the string coordinates on static resources. Geometry and properties depend on which resource produced it: a route returns a MultiLineString covering every shape its trips use, with route identity and styling in properties; a trip returns the `Li

Fields of GeoJsonFeature
Field Type Required Notes
`type` string no
`properties` object,null no Identity and styling for the feature. Route features carry the route fields below; trip features carry `trip_id`, `route_id`, `service_id`, `trip_headsign` and `block_id`; shape features carry none.
`geometry` object no

TripUpdate

A GTFS-Realtime TripUpdate. Field names follow the Protobuf schema in camelCase.

Fields of TripUpdate
Field Type Required Notes
`trip` RtTripDescriptor no
`vehicle` RtVehicleDescriptor no
`stopTimeUpdate` array of object no Predictions for the stops ahead on this trip.
`timestamp` string no Unix timestamp of this update

RtTripDescriptor

GTFS-Realtime TripDescriptor — which scheduled trip an update refers to. Shared by trip updates and vehicle positions.

Fields of RtTripDescriptor
Field Type Required Notes
`tripId` string no
`routeId` string no
`directionId` integer no Direction as an integer here, unlike the string on static trips.
`startDate` string no Service date the trip started, `YYYYMMDD`.
`scheduleRelationship` string no How this trip relates to the schedule.
`tripHeadsign` string,null no

RtVehicleDescriptor

GTFS-Realtime VehicleDescriptor — which vehicle is running the trip.

Fields of RtVehicleDescriptor
Field Type Required Notes
`id` string no Agency's vehicle identifier.
`label` string,null no Fleet number shown to riders.
`licensePlate` string,null no Often an empty string where the agency does not publish it.

StopTimeEvent

A predicted arrival or departure.

Fields of StopTimeEvent
Field Type Required Notes
`time` string no Predicted Unix timestamp
`delay` integer no Seconds behind schedule; negative is early. Absent when not published.

VehiclePosition

A GTFS-Realtime VehiclePosition.

Fields of VehiclePosition
Field Type Required Notes
`trip` RtTripDescriptor no
`vehicle` RtVehicleDescriptor no
`position` object no Coordinates here are numbers, not strings.
`currentStopSequence` integer no
`currentStatus` string no Where the vehicle is relative to `stopId` — GTFS-Realtime's VehicleStopStatus enum.
`stopId` string no
`timestamp` string no
`occupancyStatus` string no GTFS-Realtime occupancy enum, where the agency publishes it.

Alert

A GTFS-Realtime Alert. Text fields are TranslatedStrings; pick the translation matching your locale.

Fields of Alert
Field Type Required Notes
`id` string no
`headerText` TranslatedString no
`descriptionText` TranslatedString no
`informedEntity` array of object no The stops, routes or trips this alert applies to.

TranslatedString

GTFS-Realtime translated text.

Fields of TranslatedString
Field Type Required Notes
`translation` array of object no

Annotation

An operator note or override attached to a GTFS entity.

Fields of Annotation
Field Type Required Notes
`id` integer no
`annotation_type` enum: comment, override no `comment` adds a message; `override` redirects predictions to another entity.
`entity_type` string no
`entity_id` string no
`secondary_entity_type` string,null no Narrows the annotation, e.g. one route at one stop.
`secondary_entity_id` string,null no
`body` string no Processed HTML.
`override_entity_id` string,null no Replacement entity, for overrides.
`active` boolean no Whether it is within its time window now.