Documentation

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
List or search for Stops
id
integer
Internal integer ID
onestop_id
string
Onestop ID for this stop, or empty string if not registered

Examples-dr5ruvgnyk-madisonav~e69st

stop_code
string
GTFS stops.stop_code; short text or number identifying the location for riders
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; overrides agency timezone; inherits from parent station if empty

ExampleAmerica/Los_Angeles

stop_url
string
GTFS stops.stop_url
geometry
Geographic location of this stop as a GeoJSON Point
location_type
integer
GTFS stops.location_type [0=stop/platform, 1=station, 2=entrance/exit, 3=generic node, 4=boarding area]
platform_code
string
GTFS stops.platform_code; platform identifier without a 'platform' prefix (e.g. G or 3)
tts_stop_name
string
GTFS stops.tts_stop_name; readable version of stop_name for use with text-to-speech systems
stop_access
integer
GTFS stops.stop_access [0=access only via station entrance/pathways, 1=route directly to the stop]; only valid for platforms (location_type 0) with a parent_station
wheelchair_boarding
integer
GTFS stops.wheelchair_boarding [0=no information, 1=some accessible path exists, 2=no accessible path]
zone_id
string
GTFS stops.zone_id; identifies the fare zone for a stop; required only on stops referenced by fare_rules.txt
feed_version
object: FeedVersion
Source feed version for this entity
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
Scheduled departures from this stop, filtered by date/time window and enriched with GTFS-RT estimated times where available
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
timepoint
integer
GTFS stop_times.timepoint [0=times are approximate, 1=times are exact]
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]
continuous_pickup
integer
GTFS stop_times.continuous_pickup; overrides routes.continuous_pickup for the segment to the next stop [0=continuous, 1=none, 2=must phone agency, 3=must coordinate with driver]
continuous_drop_off
integer
GTFS stop_times.continuous_drop_off; overrides routes.continuous_drop_off for the segment to the next stop [0=continuous, 1=none, 2=must phone agency, 3=must coordinate with driver]
interpolated
integer
1 if this arrival/departure time was filled in by interpolation during import; 0 or null otherwise
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; distance from the start of the shape, in the same units as shapes.txt
schedule_relationship
object: ScheduleRelationship
Real-time status of the parent trip. STATIC means no GTFS-RT data was matched. See ScheduleRelationship for per-value semantics
EnumSCHEDULEDADDEDUNSCHEDULEDCANCELEDSTATICSKIPPEDNO_DATAREPLACEMENTDUPLICATEDDELETED
service_date
string
When part of an arrival/departure query, the GTFS service date for this scheduled stop time

Example2019-11-15

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

Example2019-11-15

arrival
object: StopTimeEvent
Arrival data, including GTFS-RT updates and estimates
departure
object: StopTimeEvent
Departure data, including GTFS-RT updates and estimates
trip
object: Trip
Trip associated with this stop time
children
array: Stop
Child stops belonging to this station (platforms, entrances, generic nodes, boarding areas)
id
integer
Internal integer ID
onestop_id
string
Onestop ID for this stop, or empty string if not registered

Examples-dr5ruvgnyk-madisonav~e69st

stop_code
string
GTFS stops.stop_code; short text or number identifying the location for riders
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; overrides agency timezone; inherits from parent station if empty

ExampleAmerica/Los_Angeles

stop_url
string
GTFS stops.stop_url
geometry
Geographic location of this stop as a GeoJSON Point
location_type
integer
GTFS stops.location_type [0=stop/platform, 1=station, 2=entrance/exit, 3=generic node, 4=boarding area]
platform_code
string
GTFS stops.platform_code; platform identifier without a 'platform' prefix (e.g. G or 3)
tts_stop_name
string
GTFS stops.tts_stop_name; readable version of stop_name for use with text-to-speech systems
stop_access
integer
GTFS stops.stop_access [0=access only via station entrance/pathways, 1=route directly to the stop]; only valid for platforms (location_type 0) with a parent_station
wheelchair_boarding
integer
GTFS stops.wheelchair_boarding [0=no information, 1=some accessible path exists, 2=no accessible path]
zone_id
string
GTFS stops.zone_id; identifies the fare zone for a stop; required only on stops referenced by fare_rules.txt
departures
array: StopTime
Scheduled departures from this stop, filtered by date/time window and enriched with GTFS-RT estimated times where available
alerts
array: Alert
GTFS-RT service alerts for this stop; pass active: true to return only currently active alerts
parent
object: Stop
Parent station for this stop; for platforms and entrances (location_type 2, 3, 4), this is the enclosing station (location_type 1)
id
integer
Internal integer ID
onestop_id
string
Onestop ID for this stop, or empty string if not registered

Examples-dr5ruvgnyk-madisonav~e69st

stop_code
string
GTFS stops.stop_code; short text or number identifying the location for riders
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; overrides agency timezone; inherits from parent station if empty

ExampleAmerica/Los_Angeles

stop_url
string
GTFS stops.stop_url
geometry
Geographic location of this stop as a GeoJSON Point
location_type
integer
GTFS stops.location_type [0=stop/platform, 1=station, 2=entrance/exit, 3=generic node, 4=boarding area]
platform_code
string
GTFS stops.platform_code; platform identifier without a 'platform' prefix (e.g. G or 3)
tts_stop_name
string
GTFS stops.tts_stop_name; readable version of stop_name for use with text-to-speech systems
stop_access
integer
GTFS stops.stop_access [0=access only via station entrance/pathways, 1=route directly to the stop]; only valid for platforms (location_type 0) with a parent_station
wheelchair_boarding
integer
GTFS stops.wheelchair_boarding [0=no information, 1=some accessible path exists, 2=no accessible path]
zone_id
string
GTFS stops.zone_id; identifies the fare zone for a stop; required only on stops referenced by fare_rules.txt
children
array: Stop
Child stops belonging to this station (platforms, entrances, generic nodes, boarding areas)
alerts
array: Alert
GTFS-RT service alerts for this stop; pass active: true to return only currently active alerts
alerts
array: Alert
GTFS-RT service alerts for this stop; 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