Query schedules using the Datastore API

The Transitland Datastore schedule API collapses the many elements of a schedule into an entity. Transitland models each trip between two stops as an edge, called a ScheduleStopPair (SSP). Each SSP contains an origin stop, a destination stop, a route, an operator, and arrival and departure times. Each edge also includes a service calendar, describing which days a trip is possible. Accessibility information for wheelchair and bicycle riders is included, if available.

Some of this data is normally split across multiple GTFS tables, but is here denormalized for simpler access: each edge contains enough information to get from one stop to another, to another, and finally to your destination.

GTFS schematic

ScheduleStopPair Data Model

These are the attributes and data types of a ScheduleStopPair.

AttributeTypeDescription
feed_onestop_idOnestop IDFeed
feed_version_shaStringFeed Version
route_onestop_idOnestop IDRoute
route_stop_pattern_onestop_idOnestop IDRoute Stop Pattern
operator_onestop_idOnestop IDOperator
origin_onestop_idOnestop IDOrigin stop
origin_timezoneStringOrigin stop timezone
origin_arrival_timeTimeTime vehicle arrives at origin from previous stop
origin_departure_timeTimeTime vehicle leaves origin
origin_timepoint_sourceEnumOrigin timepoint source
origin_dist_traveledNumberDistance in meters along the associated Route Stop Pattern line geometry
destination_onestop_idOnestop IDDestination stop
destination_timezoneStringDestination stop timezone
destination_arrival_timeTimeTime vehicle arrives at destination
destination_departure_timeTimeTime vehicle leaves destination for next stop
destination_timepoint_sourceEnumDestination timepoint source
destination_dist_traveledNumberDistance in meters along the associated Route Stop Pattern line geometry
window_startTimeThe previous known exact timepoint
window_endTimeThe next known exact timepoint
tripStringA text label for a sequence of edges
trip_headsignStringA human-friendly description of the ultimate destination
trip_short_nameStringA commonly known human-readable trip identifier, such as a train number
block_idStringA block of trips made by the same vehicle
service_start_dateDateDate service begins
service_end_dateDateDate service ends
service_days_of_weekBoolean ArrayScheduled service, in ISO order (Monday to Sunday)
service_added_datesDate ArrayArray of additional dates service is scheduled
service_except_datesDate ArrayArray of dates service is not scheduled (for example, holidays)
wheelchair_accessibleBooleanWheelchair accessible: true, false, or null (unknown)
bikes_allowedBooleanBike accessible: true, false, or null (unknown)
drop_off_typeEnumPassenger drop-off
pickup_typeEnumPassenger pickup
frequency_typeEnumFrequency-based schedule
frequency_headway_secondsIntegerFrequency-based schedule headway, in seconds
frequency_start_timeTimeStart of frequency-based schedule
frequency_end_timeTimeEnd of frequency-based schedule

Data types

Times can be specified with more than 24 hours, as indicated by GTFS. For example, 25:10 is 1:10am the day after the trip begins.

Timepoint source

  • gtfs_exact: An exact timepoint in the GTFS
  • gtfs_interpolated: An interpolated timepoint in the GTFS
  • transitland_interpolated_linear: Interpolated based on linear stop sequence
  • transitland_interpolated_geometric: Interpolated based on straight-line distance
  • transitland_interpolated_shape: Interpolated based on shape_dist_traveled

Pickup (origin) and drop-off (destination)

  • null: Regularly scheduled pickup and drop-off
  • unavailable: Pickup or drop-off not available
  • ask_driver: Ask the driver for pickup or drop-off
  • ask_agency: Phone the agency to schedule in advance

Frequency-based schedules

A frequency-based schedule runs at an interval, instead of at specific departure and arrival times. When frequency_type is present, the trip is repeated every frequency_headway_seconds beginning at frequency_start_time and ending at frequency_end_time. See the GTFS documentation for frequencies.txt for more information.

The values for frequency_type are:

  • exact: service is exactly scheduled.
  • not_exact: service repeats, but timepoints are not exact

Query parameters

The main ScheduleStopPair API endpoint is /api/v1/schedule_stop_pairs. It accepts the following query parameters, which may be freely combined.

Query parameterTypeDescriptionExample
origin_onestop_idOnestop IDOrigin Stop. Accepts multiple separated by commas.from Embarcadero BART
destination_onestop_idOnestop IDDestination Stop. Accepts multiple separated by commas.to Montgomery St. BART
route_onestop_idOnestop IDRoute. Accepts multiple separated by commas.on Muni N
route_stop_pattern_onestop_idOnestop IDRoute Stop Pattern. Accepts multiple separated by commas.with Route Stop Pattern
operator_onestop_idOnestop IDOperator. Accepts multiple separated by commas.on BART
dateDateService operates on a datevalid on 2015-10-26
service_from_dateDateService operates on a date, or in the futurevalid on and after 2015-10-26
service_before_dateDateService operates up to and including datevalid on and before 2015-11-30
origin_departure_betweenTime,TimeOrigin departure time between two timesdeparting between 07:00 - 09:00
tripStringTrip identifieron trip '03SFO11SUN'
bboxLon1,Lat1,Lon2,Lat2Origin Stop within bounding boxin the Bay Area

The date and origin_departure_between query parameters accept special values.

  • date=today: Use the current local date.
  • time=now: Use the current time. You can also specify now+<seconds> or now-<seconds>. Example: time=now-600,now+600.

For both of these options, a local timezone must be specified by providing one of the following parameters: origin_onestop_id, destination_onestop_id, or operator_onestop_id.

Note: When you query schedule_stop_pair, the origin and destination must be directly connected without any stops between them. For example, you can query stops that are next to each other or are coupled as an express route. To find all the trips that travel between certain stops, use the Mapzen Turn-by-Turn API with multimodal costing, which can extract the intermediate stops and do route planning.

Response format

{
    "schedule_stop_pairs": [{
        "origin_onestop_id": "s-69y7pexjtx-plazademayo<1076s",
        "destination_onestop_id": "s-69y7pesyw0-perú<1075s",
        "route_onestop_id": "r-69y7n-a",
        "route_stop_pattern_onestop_id": "r-69y7n-a-f48841-3c4d66",
        "operator_onestop_id": "o-69y7-sbase",
        "feed_onestop_id": "f-69y7-recursosdatabuenosairesgobar",
        "feed_version_sha1": "95742a1a65826abfa23f5aeaeeb082e45f066801",
        "origin_timezone": "America/Argentina/Buenos_Aires",
        "destination_timezone": "America/Argentina/Buenos_Aires",
        "trip": "A01",
        "trip_headsign": "San Pedrito",
        "block_id": null,
        "trip_short_name": null,
        "wheelchair_accessible": null,
        "bikes_allowed": null,
        "pickup_type": null,
        "drop_off_type": null,
        "shape_dist_traveled": 0.34,
        "origin_arrival_time": "05:00:00",
        "origin_departure_time": "05:00:24",
        "destination_arrival_time": "05:00:58",
        "destination_departure_time": "05:01:22",
        "origin_dist_traveled": 58.7,
        "destination_dist_traveled": 343.2,
        "service_start_date": "2014-03-01",
        "service_end_date": "2017-12-31",
        "service_added_dates": [],
        "service_except_dates": ["2015-01-01", "2015-02-16"],
        "service_days_of_week": [true, true, true, true, true, false, false],
        "window_start": "05:00:24",
        "window_end": "05:00:58",
        "origin_timepoint_source": "gtfs_exact",
        "destination_timepoint_source": "gtfs_exact",
        "frequency_start_time": "05:00:00",
        "frequency_end_time": "05:56:00",
        "frequency_headway_seconds": 480,
        "frequency_type": "exact",
        "created_at": "2017-02-22T03:42:22.827Z",
        "updated_at": "2017-02-22T03:42:22.827Z"
    }],
    "meta": {
        "sort_key": "id",
        "sort_order": "asc",
        "offset": 0,
        "per_page": 1,
        "next": "https://transit.land/api/v1/schedule_stop_pairs?feed_onestop_id=f-69y7-recursosdatabuenosairesgobar&offset=1&per_page=1&sort_key=id&sort_order=asc"
    }
}