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 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 specified format

ParameterTypeDescriptionExample
idinteger
0 ... unlimited
Search for a specific internal ID
agency_keystring

Agency lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs agency_id>' key, or a Onestop ID
include_alertsstring enum
truefalse
Include alerts from GTFS Realtime feeds
afterinteger

Return records past this record ID
limitinteger
0 ... 100
Maximum number of records to returnlimit=1
format enum
jsongeojsonpng
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-9q9-caltrain
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
radiusnumber
0 ... 10000
Search for agencies geographically, based on stops at this location; radius is in meters, requires lon and latlon=-122&lat=37&radius=1000
lonnumber
-180 ... 180
Longitude
latnumber
-90 ... 90
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
latnumber
-90 ... 90
Latitude
lonnumber
-180 ... 180
Longitude
license_commercial_use_allowed 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_optional 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_product 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_allowed 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_attribution 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

Array of objects
Description Agency entity
id
(integer)
Unique integer ID
onestop_id
(string)
Onestop ID for this agency, if available

Exampleo-9q9-bart

agency_id
(string)
GTFS agency_id

ExampleBART

agency_name
(string)
GTFS agency_name

ExampleBay Area Rapid Transit

agency_url
(uri)
GTFS agency_url

Examplehttp://www.bart.gov

agency_timezone
(timezone)
GTFS agency_timezone

ExampleAmerica/Los_Angeles

agency_lang
(string)
GTFS agency_lang

Exampleen-US

agency_phone
(string)
GTFS agency_phone

Example800-660-4287

agency_fare_url
(uri)
GTFS agency_fare_url

Examplehttp://www.caltrain.com/fares

agency_email
(string)
GTFS agency_email

Examplesupport@bart.gov

operator
(object)
Subset of fields for operator, if matched
feed_version
(object)
A subset of fields for the source feed version
routes
(object array)
A subset of fields for routes associated with this agency. This field is only populated when requesting a single agency.
geometry
(object)
Geometry in GeoJSON format
type
(string)
GeoJSON geometry type

ExampleLineString

coordinates
(number array)
An array of coordinates; may be nested arrays if geometry is Polygon or MultiLineString

Example[ [ -122.496, 37.778 ], [ -122.425, 37.786 ] ]

places
(object array)
Array of places associated with this agency
city_name
(string)
Best-matched city

ExampleOakland

adm1_name
(string)
Best-matched state or province

ExampleCalifornia

adm0_name
(string)
Best-matched country

ExampleUnited States of America


Operator Request parameters

GET/api/v2/rest/operators 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

ParameterTypeDescriptionExample
idinteger
0 ... unlimited
Search for a specific internal ID
afterinteger

Return records past this record ID
limitinteger
0 ... 100
Maximum number of records to return
searchstring

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

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

Search for records in this feedfeed_onestop_id=f-9q9-caltrain
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
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
0 ... 10000
Search for operators geographically, based on stops at this location; radius is in meters, requires lon and latlon=-122&lat=37&radius=1000
lonnumber
-180 ... 180
Longitude
latnumber
-90 ... 90
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_allowed 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_optional 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_product 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_allowed 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_attribution 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

Array of objects
Description Transitland operator record
id
(integer)
Unique integer ID
onestop_id
(string)
Onestop ID for this operator

Exampleo-9q9-bart

name
(string)
Operator name

ExampleBay Area Rapid Transit

short_name
(string)
Operator short name

ExampleBART

website
(string)
Operator website

Examplehttps://www.bart.gov

tags
(object)
Operator tags

Example{ "us_ntd_id": "1231" }

agencies
(object array)
Subset of fields for matching agencies