Documentation

REST API - Trips

Contents

Request overview
Request parameters
Response format

Trips

Trips are trips.txt entities imported from GTFS, and include the same basic structure and fields, plus some additional metadata.

Trip responses include their associated shape, calendar, frequency, and stop departure information; these entities do not have stand-alone endpoints.

For an overview of trips, schedules, and service calendars, see the Trips & Schedules concept page.

Request overview

Trips must be accessed through a route; either a route ID or Onestop ID may be used.

Stop time information is only available when requesting a single trip by ID.

To instead see all departures from a given stop, use the stops departures endpoint.

Shapes are included when accessing a single trip, requesting geojson or geojsonl formats, or with include_geometry=true.

Trips scheduled to run on a particular date can be selected using the service_date parameter, a date in YYYY-MM-DD format.

The trip API returns "active" feed versions unless requesting a specific feed version.

Trip API results are based on this GraphQL query.

Request parameters

GET/api/v2/rest/routes/{route_key}/trips Search for trips

GET/api/v2/rest/routes/{route_key}/trips.{format} Request trips in specified format

GET/api/v2/rest/routes/{route_key}/trips/{id} Request a trip by ID

GET/api/v2/rest/routes/{route_key}/trips/{id}.{format} Request a trip by ID in specified format

Parameter	Type	Description	Example
route_key	string	Route lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs route_id>' key, or a Onestop ID
service_date	string	Search for trips active on this date	service_date=...
trip_id	string	Search for records with this GTFS trip_id	trip_id=305
include_geometry	string enum truefalse	Include shape geometry	include_geometry=true
use_service_window	string enum truefalse	Use a fall-back service date if the requested service_date is outside the active service period of the feed version. The fall-back date is selected as the matching day-of-week in the week which provides the best level of scheduled service in the feed version. This value defaults to true.	use_service_window=false
relative_date	string enum TODAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAYNEXT_MONDAYNEXT_TUESDAYNEXT_WEDNESDAYNEXT_THURSDAYNEXT_FRIDAYNEXT_SATURDAYNEXT_SUNDAY	Search for departures on a relative date label, e.g. TODAY, TUESDAY, NEXT_WEDNESDAY	relative_date=NEXT_MONDAY
include_alerts	string enum truefalse	Include alerts from GTFS Realtime feeds
id	integer	Search for a specific internal ID
after	integer	Pagination cursor value. This should be treated as an opaque value created by the server and returned as the link to the next result page, which may be empty. For historical reasons, this is based on the integer record ID values, but that should not be assumed to be the case in the future.
limit	integer	Maximum number of records to return	limit=1
format	string enum jsongeojsongeojsonl	Response format	format=geojson
feed_version_sha1	string	Search for records in this feed version	feed_version_sha1=041ffeec...
feed_onestop_id	string	Search for records in this feed	feed_onestop_id=f-sf~bay~area~rg
lat	number	Latitude
lon	number	Longitude
license_commercial_use_allowed	string enum yesnounknownexclude_no	Filter entities by feed license 'commercial_use_allowed' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_share_alike_optional	string enum yesnounknownexclude_no	Filter entities by feed license 'share_alike_optional' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_create_derived_product	string enum yesnounknownexclude_no	Filter entities by feed license 'create_derived_product' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_redistribution_allowed	string enum yesnounknownexclude_no	Filter entities by feed license 'redistribution_allowed' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.
license_use_without_attribution	string enum yesnounknownexclude_no	Filter entities by feed license 'use_without_attribution' value. Please see Source Feed concept for details on license values. 'exclude_no' is equivalent to 'yes' and 'unknown'.

Response format

trips

array: Trip

List or search for Trips

integer

Internal integer ID

trip_id

string

GTFS trips.trip_id

trip_headsign

string

GTFS trips.trip_headsign; text that appears on signage identifying the trip's destination to riders

trip_short_name

string

GTFS trips.trip_short_name; public-facing text used to identify the trip to riders, such as a train number

direction_id

integer

GTFS trips.direction_id; binary indicator of travel direction [0=outbound, 1=inbound]; meaning depends on the agency

block_id

string

GTFS trips.block_id; trips with the same block_id are operated in sequence by the same vehicle

wheelchair_accessible

integer

GTFS trips.wheelchair_accessible [0=no information, 1=vehicle can accommodate at least one rider in a wheelchair, 2=no riders in wheelchairs can be accommodated]

bikes_allowed

integer

GTFS trips.bikes_allowed [0=no information, 1=vehicle can accommodate at least one bicycle, 2=no bicycles allowed]

cars_allowed

integer

GTFS trips.cars_allowed [0=no information, 1=vehicle can accommodate at least one car, 2=no cars allowed]

schedule_relationship

object: ScheduleRelationship

Real-time status of this trip. STATIC means no GTFS-RT data was matched; otherwise reflects the matching TripUpdate's schedule_relationship. See ScheduleRelationship for per-value semantics

EnumSCHEDULEDADDEDUNSCHEDULEDCANCELEDSTATICSKIPPEDNO_DATAREPLACEMENTDUPLICATEDDELETED

stop_pattern_id

integer

Calculated stop pattern ID; an integer scoped to the feed version

feed_version

object: FeedVersion

Feed version for this entity

sha1

string

SHA1 hash of the zip file

Exampleab5bdc8b6cedd06792d42186a9b542504c5eef9a

fetched_at

string

Time when the file was fetched from the URL

Example2019-11-15T00:45:55.409906

feed

object: Feed

Feed associated with this feed version

shape

object: Shape

Shape for this trip

shape_id

string

GTFS shapes.shape_id

geometry

Path geometry for this shape as a LineString

generated

boolean

True if this geometry was generated from stop locations because the source feed lacks a shapes.txt

calendar

object: Calendar

Calendar for this trip

service_id

string

GTFS calendar.service_id

start_date

string

GTFS calendar.start_date

Example2019-11-15

end_date

string

GTFS calendar.end_date

Example2019-11-15

monday

integer

GTFS calendar.monday [1=service runs on Mondays, 0=service does not run]

tuesday

integer

GTFS calendar.tuesday [1=service runs on Tuesdays, 0=service does not run]

wednesday

integer

GTFS calendar.wednesday [1=service runs on Wednesdays, 0=service does not run]

thursday

integer

GTFS calendar.thursday [1=service runs on Thursdays, 0=service does not run]

friday

integer

GTFS calendar.friday [1=service runs on Fridays, 0=service does not run]

saturday

integer

GTFS calendar.saturday [1=service runs on Saturdays, 0=service does not run]

sunday

integer

GTFS calendar.sunday [1=service runs on Sundays, 0=service does not run]

added_dates

array: Date

Service-added dates derived from calendar_dates.txt records with exception_type=1

removed_dates

array: Date

Service-removed dates derived from calendar_dates.txt records with exception_type=2

frequencies

array: Frequency

Frequencies for this trip

start_time

string

GTFS frequencies.start_time

Example15:21:04

end_time

string

GTFS frequencies.end_time

Example15:21:04

headway_secs

integer

GTFS frequencies.headway_secs; time in seconds between departures from the same stop for this trip

exact_times

integer

GTFS frequencies.exact_times [0=frequency-based, not exactly scheduled; 1=schedule-based, same headway throughout]

alerts

array: Alert

GTFS-RT service alerts for this trip; pass active: true to return only currently active alerts

cause

string

GTFS-RT Alert cause

effect

string

GTFS-RT Alert effect

severity_level

string

Alert severity: UNKNOWN_SEVERITY, INFO, WARNING, or SEVERE

url

array: RTTranslation

URL for more information

header_text

array: RTTranslation

GTFS-RT Alert header text

description_text

array: RTTranslation

GTFS-RT Alert description text

tts_header_text

array: RTTranslation

Header text optimized for text-to-speech (TTS) systems

tts_description_text

array: RTTranslation

Description text optimized for text-to-speech (TTS) systems

active_period

array: RTTimeRange

Time ranges during which this alert is active. See https://gtfs.org/realtime/reference/#message-timerange

route

object: Route

Route for this trip

integer

Internal integer ID

onestop_id

string

Onestop ID for this route

route_id

string

GTFS routes.route_id

route_short_name

string

GTFS routes.route_short_name; short name of a route, such as a line number or abbreviation

route_long_name

string

GTFS routes.route_long_name; full descriptive name of a route

alerts

array: Alert

GTFS-RT service alerts for this route; pass active: true to return only currently active alerts

agency

object: Agency

Agency associated with this route

stop_times

array: StopTime

Stop times for this trip

arrival_time

string

GTFS stop_times.arrival_time

Example15:21:04

departure_time

string

GTFS stop_times.departure_time

Example15:21:04

stop_sequence

integer

GTFS stop_times.stop_sequence; order of stops for this trip; values must increase along the trip but need not be consecutive

stop_headsign

string

GTFS stop_times.stop_headsign; overrides the trip-level headsign for passengers boarding at this stop

pickup_type

integer

GTFS stop_times.pickup_type [0=regular scheduled pickup, 1=no pickup available, 2=must phone agency to arrange, 3=must coordinate with driver]

drop_off_type

integer

GTFS stop_times.drop_off_type [0=regular scheduled drop-off, 1=no drop-off available, 2=must phone agency to arrange, 3=must coordinate with driver]

timepoint

integer

GTFS stop_times.timepoint [0=times are approximate, 1=times are exact]

interpolated

integer

1 if this arrival/departure time was filled in by interpolation during import; 0 or null otherwise

stop

object: Stop

Stop associated with this stop time