Documentation

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 by ID or Onestop ID

GET/api/v2/rest/agencies/{agency_key}.{format} Request an agency by ID or Onestop ID in specified format

ParameterTypeDescriptionExample
agency_keystring

Agency lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs agency_id>' key, or a Onestop ID
agency_idstring

Search for records with this GTFS agency_id (string)agency_id=BART
agency_namestring

Search for records with this GTFS agency_nameagency_name=Caltrain
idinteger

Search for a specific internal ID
include_alertsstring enum
truefalse
Include alerts from GTFS Realtime feeds
include_routesstring enum
truefalse
Include routes that serve this stopinclude_routes=true
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.
limitinteger

Maximum number of records to returnlimit=1
formatstring enum
jsongeojsongeojsonl
Response formatformat=geojson
searchstring

Full text searchsearch=bart
onestop_idstring

Search for a specific Onestop IDonestop_id=o-9q9-caltrain
feed_version_sha1string

Search for records in this feed versionfeed_version_sha1=1c4721d4...
feed_onestop_idstring

Search for records in this feedfeed_onestop_id=f-sf~bay~area~rg
radiusnumber

Search radius (meters); requires lat and lonlon=-122.3&lat=37.8&radius=1000
lonnumber

Longitude
latnumber

Latitude
bboxstring

Geographic search using a bounding box, with coordinates in (min_lon, min_lat, max_lon, max_lat) order as a comma separated stringbbox=-122.269,37.807,-122.267,37.808
adm0_namestring

Search by country nameadm0_name=Mexico
adm0_isostring

Search by country 2 letter ISO 3166 codeadm0_iso=US
adm1_namestring

Search by state/province/division nameadm1_name=California
adm1_isostring

Search by state/province/division ISO 3166-2 codeadm1_iso=US-CA
city_namestring

Search by city namecity_name=Oakland
license_commercial_use_allowedstring enum
yesnounknownexclude_no
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_optionalstring enum
yesnounknownexclude_no
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_productstring enum
yesnounknownexclude_no
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_allowedstring enum
yesnounknownexclude_no
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_attributionstring enum
yesnounknownexclude_no
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: Agency
List or search for Agencies (each an agency.txt record from a specific FeedVersion); defaults to currently active feed versions when none is specified
id
integer
Internal integer ID
agency_name
string
GTFS agency.agency_name
agency_id
string
GTFS agency.agency_id
onestop_id
string
Onestop ID for this agency (or its associated operator)
agency_url
string
GTFS agency.agency_url
agency_timezone
string
GTFS agency.agency_timezone; stop times use this timezone unless overridden by stop_timezone
agency_lang
string
GTFS agency.agency_lang; primary language used by this transit agency, as a BCP 47 language tag
agency_phone
string
GTFS agency.agency_phone; voice telephone number for the agency's customer service
agency_fare_url
string
GTFS agency.agency_fare_url; URL of a web page where a rider can purchase tickets or passes
agency_email
string
GTFS agency.agency_email; email address actively monitored by the agency's customer service department
cemv_support
integer
GTFS agency.cemv_support; whether riders can use a contactless EMV (cEMV) card or mobile device as fare media for trips associated with this agency [0=no information, 1=supported, 2=not supported]
geometry
Convex hull of all stops served by this agency
operator
object: Operator
Operator associated with this agency
onestop_id
string
Onestop ID for this operator. Format: o-geohash-name. Example: o-dr5r-nyct.
name
string
Operator name
short_name
string
Operator short name
tags
object
Atlas tags providing additional metadata for this operator
feeds
array: Feed
Feeds associated with this operator
alerts
array: Alert
GTFS-RT service alerts for this agency; 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
places
array: AgencyPlace
Administrative places (city, state, country) matched to this agency by overlap with stop locations, ranked by association strength
city_name
string
Best-matched city name
adm0_name
string
Best-matched country name
adm1_name
string
Best-matched state or province name
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
routes
array: Route
Routes associated with this agency
id
integer
Internal integer ID
route_id
string
GTFS routes.route_id
route_short_name
string
GTFS routes.route_short_name; short name of a route, such as a line number or abbreviation
route_long_name
string
GTFS routes.route_long_name; full descriptive name of a route
alerts
array: Alert
GTFS-RT service alerts for this route; pass active: true to return only currently active alerts

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/{operator_key} Request an operator by ID or Onestop ID

GET/api/v2/rest/operators/{operator_key}.{format} Request an operator by ID or Onestop ID in specified format

ParameterTypeDescriptionExample
tag_keystring

Search for operators with a tag. Combine with tag_value also query for the value of the tag.tag_key=us_ntd_id
tag_valuestring

Search for feeds tagged with a given value. Must be combined with tag_key.tag_key=us_ntd_id&tag_value=40029
onestop_idstring

Search for a specific Onestop IDonestop_id=o-9q9-caltrain
feed_onestop_idstring

Search for records in this feedfeed_onestop_id=f-sf~bay~area~rg
searchstring

Full text searchsearch=bart
include_alertsstring enum
truefalse
Include alerts from GTFS Realtime feeds
idinteger

Search for a specific internal ID
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.
limitinteger

Maximum number of records to return
adm0_namestring

Search by country nameadm0_name=Mexico
adm0_isostring

Search by country 2 letter ISO 3166 codeadm0_iso=US
adm1_namestring

Search by state/province/division nameadm1_name=California
adm1_isostring

Search by state/province/division ISO 3166-2 codeadm1_iso=US-CA
city_namestring

Search by city namecity_name=Oakland
radiusnumber

Search radius (meters); requires lat and lonlon=-122.3&lat=37.8&radius=1000
lonnumber

Longitude
latnumber

Latitude
bboxstring

Geographic search using a bounding box, with coordinates in (min_lon, min_lat, max_lon, max_lat) order as a comma separated stringbbox=-122.269,37.807,-122.267,37.808
license_commercial_use_allowedstring enum
yesnounknownexclude_no
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_optionalstring enum
yesnounknownexclude_no
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_productstring enum
yesnounknownexclude_no
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_allowedstring enum
yesnounknownexclude_no
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_attributionstring enum
yesnounknownexclude_no
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: Operator
List or search for Operators (higher-level groupings of agencies)
id
integer
Internal integer ID
onestop_id
string
Onestop ID for this operator. Format: o-geohash-name. Example: o-dr5r-nyct.
name
string
Operator name
short_name
string
Operator short name
website
string
Operator website
tags
object
Atlas tags providing additional metadata for this operator
feeds
array: Feed
Feeds associated with this operator
id
integer
Internal integer ID
onestop_id
string
Onestop ID for this feed. Format: f-geohash-name. Example: f-9q9-bart.
name
string
A common name for this feed; alternatively use associated_operators[].name
spec
object: FeedSpecTypes
Type of feed: GTFS, GTFS_RT, GBFS, or MDS
EnumGTFSGTFS_RTGBFSMDS
agencies
array: Agency
Agencies for this operator from active feed versions
id
integer
Internal integer ID
agency_id
string
GTFS agency.agency_id
agency_name
string
GTFS agency.agency_name
geometry
Convex hull of all stops served by this agency
alerts
array: Alert
GTFS-RT service alerts for this agency; pass active: true to return only currently active alerts
places
array: AgencyPlace
Administrative places (city, state, country) matched to this agency by overlap with stop locations, ranked by association strength