REST API - Stop departures

Stop departures

The stop-departures endpoint provides information about when transit trips serve a given stop.

To instead see departures for a specific transit trip, use the trips endpoint. For an overview of trips and schedules, see the Trips & Schedules concept page.

How do I specify a date?

By default, departures for the next hour (in the local timezone for the stop) are shown. You can increase this time window using the next parameter. You can also specify the start and end times manually, using the start_time and end_time parameters.

Dates can also be specified in three different ways:

  1. Use date to request departures on a specific date.
  2. Use relative_date to automatically select TODAY or the next occurrence of the named day, e.g. FRIDAY
  3. Use service_date to specify an explicit GTFS service date.

Both date and relative_date will correctly translate GTFS calendar.txt/calendar_date.txt semantics into normal calendar dates with 24 hour days. That is, the results may include departures from the previous GTFS service date that occur after midnight and/or from the early morning of the subsequent GTFS service date. The service_date parameter will restrict the search to only trips and departures for that specific GTFS service date.

This flexibility is provided because some users need "wall clock" times, while other users need results strictly tied to the GTFS service date model.

The plain day of week values (e.g. FRIDAY) will select the next time that day of the week occurs, inclusive of the current date. NEXT_ values will select the next time that day of week occurs, not inclusive of the current date. For instance, if the current weekday is Monday, MONDAY will return the current date, and NEXT_MONDAY will return the next Monday, seven days from now. TUESDAY would select the same date in both circumstances, e.g. the day after today.

How are departure times calculated?

Transitland calculates scheduled arrivals/departures from static GTFS feeds using the following approaches:

  1. The scheduled arrival and/or departure times for a given stop, as defined in a static GTFS feed's stop_times.txt file.
  2. If the static GTFS feed does not provide an arrival or departure time for the specified stop, Transitland will interpolate times between "timepoint" stops before and after the specified stops.
  3. When available, Transitland will make use of shape_dist_traveled values in shapes.txt to improve interpolation accuracy.

For operators that also provide GTFS Realtime feeds with TripUpdates, Transitland also provides real-time arrivals/departures. Real-time and scheduled values are listed separately in API responses. Note that "added" trips will only have real-time values, but not scheduled values.

Limitations

  • For operators that provide GTFS Realtime feeds with VehiclePositions (but not TripUpdates), Transitland does not use vehicle positions to independently estimate real-time arrivals/departures.
  • For operators that define route schedules using frequencies.txt (a much less popular approach than using stop_times.txt), Transitland does not currently calculate stop departure times.

Request parameters

GET/api/v2/rest/stops/{stop_key}/departures Departures from a given stop based on static and real-time data

ParameterTypeDescriptionExample
stop_keystring

Stop lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs stop_id'> key, a Onestop IDf-sf~bay~area~rg:LAKE
limitinteger

Maximum number of records to returnlimit=1
service_datestring

Search for departures on a specified GTFS service calendar date, in YYYY-MM-DD formatservice_date=2022-09-28
datestring

Search for departures on a specified calendar date, in YYYY-MM-DD formatdate=2022-09-28
nextinteger

Search for departures leaving within the next specified number of seconds in local timenext=600
start_timestring

Search for departures leaving after a specified local time, in HH:MM:SS formatstart_time=10:00:00
end_timestring

Search for departures leaving before a specified local time, in HH:MM:SS formatend_time=11:00:00
include_geometrystring enum
truefalse
Include route geometryinclude_geometry=true
use_service_windowstring 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
idinteger

Search for a specific internal ID
relative_datestring enum
TODAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAYNEXT_MONDAYNEXT_TUESDAYNEXT_WEDNESDAYNEXT_THURSDAYNEXT_FRIDAYNEXT_SATURDAYNEXT_SUNDAY
Search for departures on a relative date label, e.g. TODAY, TUESDAY, NEXT_WEDNESDAYrelative_date=NEXT_MONDAY
include_alertsstring enum
truefalse
Include alerts from GTFS Realtime feeds
afterinteger

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.

Response format


stops
array: Stop
Currently imported stops. If no feed version is specified, defaults to active feed versions.
id
integer
Internal integer ID
onestop_id
string
OnestopID for this stop, if available

Examples-dr5ruvgnyk-madisonav~e69st

stop_code
string
GTFS stops.stop_code
stop_desc
string
GTFS stops.stop_desc

ExampleNW Corner of Broadway and 14th

stop_id
string
GTFS stops.stop_id

Example400029

stop_name
string
GTFS stops.stop_name

ExampleMADISON AV/E 68 ST

stop_timezone
string
GTFS stops.stop_timezone; if overriding agency/route timezone

ExampleAmerica/Los_Angeles

stop_url
string
GTFS stops.stop_url
geometry
Stop geometry
location_type
integer
GTFS stops.location_type; this is optional in GTFS spec
Enum01234
platform_code
string
GTFS stops.platform_code
tts_stop_name
string
GTFS stops.tts_stop_name
wheelchair_boarding
integer
GTFS stops.wheelchair_boarding
Enum012
zone_id
string
GTFS stops.zone_id
feed_version
object: FeedVersion
Feed version
id
integer
Internal integer ID
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
departures
array: StopTime
Departures from this stop for a given date and time
stop_sequence
integer
GTFS stop_times.stop_sequence
stop_headsign
string
GTFS stop_times.stop_headsign
timepoint
integer
GTFS stop_times.timepoint
pickup_type
integer
GTFS stop_times.pickup_type
drop_off_type
integer
GTFS stop_times.drop_off_type
continuous_pickup
integer
GTFS stop_times.continuous_pickup
continuous_drop_off
integer
GTFS stop_times.continuous_drop_off
interpolated
integer
Set if this arrival/departure time was interpolated during import
arrival_time
string
GTFS stop_times.arrival_time

Example15:21:04

departure_time
string
GTFS stop_times.departure_time

Example15:21:04

shape_dist_traveled
number
GTFS stop_times.shape_dist_traveled
schedule_relationship
object: ScheduleRelationship
A status flag for real-time information about this trip. If no real-time information is available, the value will be STATIC and the estimated arrival/departure times will be empty. A trip with real-time information available will be SCHEDULED; a canceled trip will be CANCELED, and an added trip that is not present in the static GTFS will be ADDED.
EnumSCHEDULEDADDEDUNSCHEDULEDCANCELEDSTATICSKIPPEDNO_DATAREPLACEMENTDUPLICATEDDELETED
service_date
string
If part of an arrival/departure query, the GTFS service date for this scheduled stop time

Example2019-11-15

date
string
If part of an arrival/departure query, the calendar date for this scheduled stop time

Example2019-11-15

arrival
object: StopTimeEvent
Detailed arrival information, including GTFS-RT updates and estimates
departure
object: StopTimeEvent
Detailed departure information, including GTFS-RT updates and estimates
trip
object: Trip
Trip associated with this stop time
children
array: Stop
Stop children
id
integer
Internal integer ID
onestop_id
string
OnestopID for this stop, if available

Examples-dr5ruvgnyk-madisonav~e69st

stop_code
string
GTFS stops.stop_code
stop_desc
string
GTFS stops.stop_desc

ExampleNW Corner of Broadway and 14th

stop_id
string
GTFS stops.stop_id

Example400029

stop_name
string
GTFS stops.stop_name

ExampleMADISON AV/E 68 ST

stop_timezone
string
GTFS stops.stop_timezone; if overriding agency/route timezone

ExampleAmerica/Los_Angeles

stop_url
string
GTFS stops.stop_url
geometry
Stop geometry
location_type
integer
GTFS stops.location_type; this is optional in GTFS spec
Enum01234
platform_code
string
GTFS stops.platform_code
tts_stop_name
string
GTFS stops.tts_stop_name
wheelchair_boarding
integer
GTFS stops.wheelchair_boarding
Enum012
zone_id
string
GTFS stops.zone_id
departures
array: StopTime
Departures from this stop for a given date and time
alerts
array: Alert
GTFS-RT Alerts for this stop
parent
object: Stop
Stop parent station
id
integer
Internal integer ID
onestop_id
string
OnestopID for this stop, if available

Examples-dr5ruvgnyk-madisonav~e69st

stop_code
string
GTFS stops.stop_code
stop_desc
string
GTFS stops.stop_desc

ExampleNW Corner of Broadway and 14th

stop_id
string
GTFS stops.stop_id

Example400029

stop_name
string
GTFS stops.stop_name

ExampleMADISON AV/E 68 ST

stop_timezone
string
GTFS stops.stop_timezone; if overriding agency/route timezone

ExampleAmerica/Los_Angeles

stop_url
string
GTFS stops.stop_url
geometry
Stop geometry
location_type
integer
GTFS stops.location_type; this is optional in GTFS spec
Enum01234
platform_code
string
GTFS stops.platform_code
tts_stop_name
string
GTFS stops.tts_stop_name
wheelchair_boarding
integer
GTFS stops.wheelchair_boarding
Enum012
zone_id
string
GTFS stops.zone_id
children
array: Stop
Stop children
alerts
array: Alert
GTFS-RT Alerts for this stop
alerts
array: Alert
GTFS-RT Alerts for this stop
cause
string
GTFS-RT Alert cause
effect
string
GTFS-RT Alert effect
severity_level
string
GTFS-RT Alert severity level
url
array: RTTranslation
GTFS-RT Alert 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
GTFS-RT Alert TTS header text
tts_description_text
array: RTTranslation
GTFS-RT Alert TTS description text
active_period
array: RTTimeRange
GTFS-RT Alert active alert period. See https://gtfs.org/realtime/reference/#message-timerange