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 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
| Parameter | Type | Description | Example |
|---|---|---|---|
| id | integer 0 ... unlimited | Search for a specific internal ID | |
| agency_key | string | Agency lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs agency_id>' key, or a Onestop ID | |
| include_alerts | string enum | Include alerts from GTFS Realtime feeds | |
| after | integer | Return records past this record ID | |
| limit | integer 0 ... 100 | Maximum number of records to return | limit=1 |
| format | 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-9q9-caltrain |
| 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 |
| radius | number 0 ... 10000 | Search for agencies geographically, based on stops at this location; radius is in meters, requires lon and lat | lon=-122&lat=37&radius=1000 |
| lon | number -180 ... 180 | Longitude | |
| lat | number -90 ... 90 | 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 |
| lat | number -90 ... 90 | Latitude | |
| lon | number -180 ... 180 | Longitude | |
| license_commercial_use_allowed | 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 | 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 | 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 | 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 | 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
Array of objects
Description Agency entity
Reference GTFS specification for agencies.txt
id
(integer)
(integer)
Unique integer ID
onestop_id
(string)
(string)
Onestop ID for this agency, if available
Exampleo-9q9-bart
agency_id
(string)
(string)
GTFS agency_id
ExampleBART
agency_name
(string)
(string)
GTFS agency_name
ExampleBay Area Rapid Transit
agency_url
(uri)
(uri)
GTFS agency_url
Examplehttp://www.bart.gov
agency_timezone
(timezone)
(timezone)
GTFS agency_timezone
ExampleAmerica/Los_Angeles
agency_lang
(string)
(string)
GTFS agency_lang
Exampleen-US
agency_phone
(string)
(string)
GTFS agency_phone
Example800-660-4287
agency_fare_url
(uri)
(uri)
GTFS agency_fare_url
Examplehttp://www.caltrain.com/fares
agency_email
(string)
(string)
GTFS agency_email
Examplesupport@bart.gov
operator
(object)
(object)
Subset of fields for operator, if matched
feed_version
(object)
(object)
A subset of fields for the source feed version
routes
(object array)
(object array)
A subset of fields for routes associated with this agency. This field is only populated when requesting a single agency.
geometry
(object)
(object)
Geometry in GeoJSON format
type
(string)
(string)
GeoJSON geometry type
ExampleLineString
coordinates
(number array)
(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)
(object array)
Array of places associated with this agency
city_name
(string)
(string)
Best-matched city
ExampleOakland
adm1_name
(string)
(string)
Best-matched state or province
ExampleCalifornia
adm0_name
(string)
(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
| Parameter | Type | Description | Example |
|---|---|---|---|
| id | integer 0 ... unlimited | Search for a specific internal ID | |
| after | integer | Return records past this record ID | |
| limit | integer 0 ... 100 | Maximum number of records to return | |
| search | string | Full text search | search=bart |
| include_alerts | string enum | Include alerts from GTFS Realtime feeds | |
| 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-9q9-caltrain |
| 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 |
| 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 0 ... 10000 | Search for operators geographically, based on stops at this location; radius is in meters, requires lon and lat | lon=-122&lat=37&radius=1000 |
| lon | number -180 ... 180 | Longitude | |
| lat | number -90 ... 90 | 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 | 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 | 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 | 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 | 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 | 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
Array of objects
Description Transitland operator record
id
(integer)
(integer)
Unique integer ID
onestop_id
(string)
(string)
Onestop ID for this operator
Exampleo-9q9-bart
name
(string)
(string)
Operator name
ExampleBay Area Rapid Transit
short_name
(string)
(string)
Operator short name
ExampleBART
website
(string)
(string)
Operator website
Examplehttps://www.bart.gov
tags
(object)
(object)
Operator tags
Example{ "us_ntd_id": "1231" }
agencies
(object array)
(object array)
Subset of fields for matching agencies