Contents
REST API - Agencies and Operators
Agencies and Operators
Operators and agencies are two means of grouping together stops, routes, trips, and other data for a single organization that offers transit service. For more information on the distinction, see agencies and operators.
Request overview
The REST API provides access to both agencies and operators, with results based on agency and operator GraphQL queries.
Agency request parameters
GET/api/v2/rest/agencies Search for agencies
GET/api/v2/rest/agencies.{format} Request agencies in specified format
GET/api/v2/rest/agencies/{agency_key} Request an agency
GET/api/v2/rest/agencies/{agency_key}.format Request an agency in a specified format
| Parameter | Type | Description | Example |
|---|---|---|---|
| agency_key | string | Agency lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs agency_id>' key, or a Onestop ID | |
| agency_id | string | Search for records with this GTFS agency_id (string) | agency_id=BART |
| agency_name | string | Search for records with this GTFS agency_name | agency_name=Caltrain |
| id | integer | Search for a specific internal ID | |
| include_alerts | string enum | Include alerts from GTFS Realtime feeds | |
| 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 | Response format | format=geojson |
| search | string | Full text search | search=bart |
| onestop_id | string | Search for a specific Onestop ID | onestop_id=o-9q9-caltrain |
| feed_version_sha1 | string | Search for records in this feed version | feed_version_sha1=1c4721d4... |
| feed_onestop_id | string | Search for records in this feed | feed_onestop_id=f-sf~bay~area~rg |
| radius | number | Search radius (meters); requires lat and lon | lon=-122.3&lat=37.8&radius=1000 |
| lon | number | Longitude | |
| lat | number | Latitude | |
| bbox | string | Geographic search using a bounding box, with coordinates in (min_lon, min_lat, max_lon, max_lat) order as a comma separated string | bbox=-122.269,37.807,-122.267,37.808 |
| adm0_name | string | Search by country name | adm0_name=Mexico |
| adm0_iso | string | Search by country 2 letter ISO 3166 code | adm0_iso=US |
| adm1_name | string | Search by state/province/division name | adm1_name=California |
| adm1_iso | string | Search by state/province/division ISO 3166-2 code | adm1_iso=US-CA |
| city_name | string | Search by city name | city_name=Oakland |
| license_commercial_use_allowed | string enum | 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 | 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 | 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 | 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 | 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'. |
Agency response format
agencies
array: AgencyCurrently imported agencies. If no feed version is specified, defaults to active feed versions.
id
integerInternal integer ID
agency_name
stringGTFS agency.agency_name
agency_id
stringGTFS agency.agency_id
onestop_id
stringOnestopID for this agency (or its associated operator)
agency_url
stringGTFS agency.agency_url
agency_timezone
stringGTFS agency.agency_timezone
agency_lang
stringGTFS agency.agency_lang
agency_phone
stringGTFS agency.agency_phone
agency_fare_url
stringGTFS agency.agency_fare_url
agency_email
stringGTFS agency.agency_email
geometry
Geometry for this agency, generated as the convex hull of all stops
operator
object: OperatorOperator associated with this agency
onestop_id
stringOnestopID for this operator
name
stringOperator name
short_name
stringOperator short name, if available
tags
objectSource DMFR tag data
feeds
array: FeedFeeds associated with this operator
alerts
array: AlertGTFS-RT alerts for this agency
cause
stringGTFS-RT Alert cause
effect
stringGTFS-RT Alert effect
severity_level
stringGTFS-RT Alert severity level
url
array: RTTranslationGTFS-RT Alert uRL for more information
header_text
array: RTTranslationGTFS-RT Alert header text
description_text
array: RTTranslationGTFS-RT Alert description text
tts_header_text
array: RTTranslationGTFS-RT Alert TTS header text
tts_description_text
array: RTTranslationGTFS-RT Alert TTS description text
active_period
array: RTTimeRangeGTFS-RT Alert active alert period. See https://gtfs.org/realtime/reference/#message-timerange
places
array: AgencyPlacePlaces associated with this agency through a matching process
city_name
stringBest-matched city name
adm0_name
stringBest-matched country name
adm1_name
stringBest-matched state or province name
feed_version
object: FeedVersionSource feed version for this entity
id
integerInternal integer ID
sha1
stringSHA1 hash of the zip file
Exampleab5bdc8b6cedd06792d42186a9b542504c5eef9a
fetched_at
stringTime when the file was fetched from the url
Example2019-11-15T00:45:55.409906
feed
object: FeedFeed associated with this feed version
routes
array: RouteRoutes associated with this agency
id
integerInternal integer ID
route_id
stringGTFS routes.route_id
route_short_name
stringGTFS routes.route_short_name
route_long_name
stringGTFS routes.route_long_name
alerts
array: AlertGTFS-RT alerts for this route
Operator request parameters
GET/api/v2/rest/operators Search for operators
GET/api/v2/rest/operators.{format} Request operators in specified format
GET/api/v2/rest/operators/{onestop_id} Request an operator by Onestop ID
GET/api/v2/rest/operators/{onestop_id}.format Request an operator by Onestop ID in specified format
| Parameter | Type | Description | Example |
|---|---|---|---|
| tag_key | string | Search for operators with a tag. Combine with tag_value also query for the value of the tag. | tag_key=us_ntd_id |
| tag_value | string | Search for feeds tagged with a given value. Must be combined with tag_key. | tag_key=us_ntd_id&tag_value=40029 |
| onestop_id | string | Search for a specific Onestop ID | onestop_id=o-9q9-caltrain |
| feed_onestop_id | string | Search for records in this feed | feed_onestop_id=f-sf~bay~area~rg |
| search | string | Full text search | search=bart |
| include_alerts | string enum | 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 | |
| adm0_name | string | Search by country name | adm0_name=Mexico |
| adm0_iso | string | Search by country 2 letter ISO 3166 code | adm0_iso=US |
| adm1_name | string | Search by state/province/division name | adm1_name=California |
| adm1_iso | string | Search by state/province/division ISO 3166-2 code | adm1_iso=US-CA |
| city_name | string | Search by city name | city_name=Oakland |
| radius | number | Search radius (meters); requires lat and lon | lon=-122.3&lat=37.8&radius=1000 |
| lon | number | Longitude | |
| lat | number | Latitude | |
| bbox | string | Geographic search using a bounding box, with coordinates in (min_lon, min_lat, max_lon, max_lat) order as a comma separated string | bbox=-122.269,37.807,-122.267,37.808 |
| license_commercial_use_allowed | string enum | 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 | 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 | 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 | 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 | 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'. |
Operator response format
operators
array: OperatorOperators
id
integerInternal integer ID
onestop_id
stringOnestopID for this operator
name
stringOperator name
short_name
stringOperator short name, if available
website
stringOperator website, if available
tags
objectSource DMFR tag data
feeds
array: FeedFeeds associated with this operator
id
integerInternal integer ID
onestop_id
stringOnestopID for this feed
name
stringA common name for this feed. Optional. Alternatively use
associated_operators[].namespec
object: FeedSpecTypesType of feed
agencies
array: AgencyCurrently imported and active agencies associated with this operator
id
integerInternal integer ID
agency_id
stringGTFS agency.agency_id
agency_name
stringGTFS agency.agency_name
geometry
Geometry for this agency, generated as the convex hull of all stops
alerts
array: AlertGTFS-RT alerts for this agency
places
array: AgencyPlacePlaces associated with this agency through a matching process