Contents
REST API - Agencies and Operators
Agencies and Operators
An agency represents a single GTFS agencies.txt
entity that was imported from a single feed version. The metadata, routes, etc., for an agency include only the data for that specific agency in that specific feed version.
Operators are a higher-level abstraction over agencies, with each operator defined by an entry in the Transitland Atlas. Operators provide a method for enriching the basic GTFS agency data, as well as grouping agencies that span across multiple source feeds. Operators are matched with GTFS agencies using associated_feeds
, a simple list of Feed OnestopIDs and GTFS agency_id
s. For instance, the Atlas operator record for the New York City MTA has associated_feeds
values for 8 different GTFS feeds. A query for this operator OnestopID thus represents the union of data from all 8 feeds, and includes routes for the subway, bus service for all 5 boroughs, commuter rail agencies, etc., operated by the MTA. This record also includes additional metadata about the MTA, such as the United States National Transit Database ID, Wikidata IDs, and alternate names for the agency. Operator records are created and maintained through pull requests to the Atlas json files and synchronized with the Transitland database on each commit.
Default operators
The operators implementation includes a fall-back to ensure that all agencies and routes are available through operators queries, even if an Atlas operator record is not defined or the association is broken. In this case, an operator record is automatically generated for each unmatched agency. For example (at the time of writing), the West Berkeley Shuttle uses an automatically generated operator record. However, some fields such as operator_name
will be null in this case.
Unmatched operators
Note that occassionally an operator will fail to associate with the intended agencies. This usually happens when a feed containing multiple agencies has a change in agency_id
values that need to be updated in the operator Atlas record. If you come across such a record, please let us know or open an Atlas pull request to update the operator metadata.
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 radius (meters); requires lat and lon | lat=-122&lon=37&radius=1000 |
lat | number -90 ... 90 | Search for agencies with stops at this lat/lon | |
lon | number -180 ... 180 | Search for agencies with stops at this lat/lon | |
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 feed documentation 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 feed documentation 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 feed documentation 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 feed documentation 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 feed documentation 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 |
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 feed documentation 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 feed documentation 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 feed documentation 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 feed documentation 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 feed documentation 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