REST API - 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_ids. 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 by ID or Onestop ID
GET /api/v2/rest/agencies/{agency_key}.{format} — Request an agency by ID or Onestop ID in format
| Parameter | Type | Description | Example |
|---|---|---|---|
| id |
integer
0 ... unlimited | Search for a specific internal ID | |
| agency_key |
string
| Equivalent to id (if an integer) or onestop_id (if string) | |
| 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 |
Agency Response format
(int64)
Example:123
(string)
Example:o-9q9-bart
(string)
Example:BART
(string)
Example:Bay Area Rapid Transit
(uri)
Example:http://www.bart.gov
(timezone)
Example:America/Los_Angeles
(string)
Example:en-US
(string)
Example:800-660-4287
(uri)
Example:http://www.caltrain.com/fares
(string)
Example:support@bart.gov
(object)
(string)
Example:LineString
(number array)
Example:[ [ -122.496, 37.778 ], [ -122.425, 37.786 ] ]
(object)
(object array)
(string)
Example:Oakland
(string)
Example:California
(string)
Example:United States of America
(object)
(object array)
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 |
| 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 |
Operator Response format
(int64)
Example:123
(string)
Example:o-9q9-bart
(string)
Example:Bay Area Rapid Transit
(string)
Example:BART
(string)
Example:https://www.bart.gov
(object)
Example:{ "us_ntd_id": "1231" }
(object array)