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_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

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
after integer

Return records past this record ID
limit integer
0 ... 100
Maximum number of records to return limit=1
format enum
jsongeojsonpng
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

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

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

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