Skip to content
Documentation

REST API - Stop departures

Last updated

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 and schedules concept page.

Departures or transit routing?

Use stop departures for a known stop. It returns the trips serving that stop in a time window, in departure order, with real-time arrival estimates where a feed provides them. It does not plan routes, transfers, or walking.

Use transit routing for an origin and a destination. It selects stops, routes, and transfers, and returns itineraries with walking legs, timings, and geometry.

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.

GEThttps://transit.land/api/v2/rest/stops/{stop_key}/departures

Request

stop_keystringrequired
Stop lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs stop_id'> key, a Onestop ID
limitoptional integer (int32)
Maximum number of records to return
service_dateoptional string (date)
Search for departures on a specified GTFS service calendar date, in YYYY-MM-DD format
dateoptional string (date)
Search for departures on a specified calendar date, in YYYY-MM-DD format
nextoptional integer
Search for departures leaving within the next specified number of seconds in local time
start_timeoptional string
Search for departures leaving after a specified local time, in HH:MM:SS format
end_timeoptional string
Search for departures leaving before a specified local time, in HH:MM:SS format
include_geometryoptional string
Include route geometry

Allowed:true, false

use_service_windowoptional string
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.

Allowed:true, false

idoptional integer (int32)
Search for a specific internal ID
relative_dateoptional string
Search for departures on a relative date label, e.g. TODAY, TOMORROW, TUESDAY, NEXT_WEDNESDAY

Allowed:TODAY, YESTERDAY, TOMORROW, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, NEXT_MONDAY, NEXT_TUESDAY, NEXT_WEDNESDAY, NEXT_THURSDAY, NEXT_FRIDAY, NEXT_SATURDAY, NEXT_SUNDAY

include_alertsoptional string
Include alerts from GTFS Realtime feeds

Allowed:true, false

afteroptional integer (int32)
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

stopsarray of Stop
List or search for Stops
stops.idinteger
Internal integer ID
stops.onestop_idstring
Onestop ID for this stop, or empty string if not registered

Example:s-dr5ruvgnyk-madisonav~e69st

stops.stop_codenullable string
GTFS stops.stop_code; short text or number identifying the location for riders
stops.stop_descnullable string
GTFS stops.stop_desc

Example:NW Corner of Broadway and 14th

stops.stop_idstring
GTFS stops.stop_id

Example:400029

stops.stop_namenullable string
GTFS stops.stop_name

Example:MADISON AV/E 68 ST

stops.stop_timezonenullable string
GTFS stops.stop_timezone; overrides agency timezone; inherits from parent station if empty

Example:America/Los_Angeles

stops.stop_urlnullable string
GTFS stops.stop_url
stops.geometryPoint
Geographic location of this stop as a GeoJSON Point
stops.location_typeinteger
GTFS stops.location_type [0=stop/platform, 1=station, 2=entrance/exit, 3=generic node, 4=boarding area]
stops.platform_codenullable string
GTFS stops.platform_code; platform identifier without a 'platform' prefix (e.g. G or 3)
stops.tts_stop_namenullable string
GTFS stops.tts_stop_name; readable version of stop_name for use with text-to-speech systems
stops.stop_accessnullable 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
stops.wheelchair_boardingnullable integer
GTFS stops.wheelchair_boarding [0=no information, 1=some accessible path exists, 2=no accessible path]
stops.zone_idnullable string
GTFS stops.zone_id; identifies the fare zone for a stop; required only on stops referenced by fare_rules.txt
stops.feed_versionFeedVersion
Source feed version for this entity
stops.departuresarray of StopTime
Scheduled departures from this stop, filtered by date/time window and enriched with GTFS-RT estimated times where available. Frequencies with headway_secs under 60 are not expanded.
stops.childrennullable array of Stop
Child stops belonging to this station (platforms, entrances, generic nodes, boarding areas)
stops.parentnullable Stop
Parent station for this stop; for platforms and entrances (location_type 2, 3, 4), this is the enclosing station (location_type 1)
stops.alertsnullable array of Alert
GTFS-RT service alerts on this stop, with or without a route. An agency, route or mode the alert also gives must be in this stop's feed version and agree with each other; alerts on a trip at the stop are on the trip instead. Pass active: true to return only currently active alerts