Documentation

REST API - Routes

Contents

Request overview
Request parameters
Response format

Routes

The REST API routes endpoint provides a fast and flexible way to browse routes and to visualize their representative geometries.

When visualizing many routes over a large region, consider using Transitland's vector tiles instead of the REST API.

The routes API provides optional flags for including or disincluding certain response sections; this may be useful for optimizing the speed and size of requests. The API also provides png as a format option, which returns a PNG format image containing a simple static map of the route and stops.

Geographic queries require all three parameters of lat, lon, and radius to be specified. The maximum radius is 10km.

The route API returns "active" feed versions unless requesting a specific feed version.

Route API results are based on this GraphQL query.

Request parameters

GET/api/v2/rest/routes Search for routes

GET/api/v2/rest/routes.{format} Request routes in specified format

GET/api/v2/rest/routes/{route_key} Request a route by ID or Onestop ID

GET/api/v2/rest/routes/{route_key}.{format} Request a route by ID or Onestop ID in specified format

Parameter	Type	Description	Example
route_key	string	Route lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs route_id>' key, or a Onestop ID
agency_key	string	Agency lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs agency_id>' key, or a Onestop ID
route_id	string	Search for records with this GTFS route_id	route_id=Bu-130
route_type	integer	Search for routes with this GTFS route (vehicle) type	route_type=1
route_types	string	Search for routes with these GTFS route (vehicle) types. Accepts comma separated values.	route_types=1,2
operator_onestop_id	string	Search for records by operator OnestopID	operator_onestop_id=...
serves_stop_onestop_id	string	Search for routes serving a stop with this OnestopID	serves_stop_onestop_id=s-9q8yyzcny3-embarcadero
include_alerts	string enum truefalse	Include alerts from GTFS Realtime feeds
include_geometry	string enum truefalse	Include route geometry	include_geometry=true
include_stops	string enum truefalse	Include route stops	include_stops=true
id	integer	Search for a specific internal ID
after	integer	Pagination cursor value. This should be treated as an opaque value created by the server and returned as the link to the next result page, which may be empty. For historical reasons, this is based on the integer record ID values, but that should not be assumed to be the case in the future.
limit	integer	Maximum number of records to return	limit=1
format	string enum jsongeojsongeojsonl	Response format	format=geojson
search	string	Full text search	search=daly+city
onestop_id	string	Search for a specific Onestop ID	onestop_id=r-9q9j-l1
feed_version_sha1	string	Search for records in this feed version	feed_version_sha1=041ffeec...
feed_onestop_id	string	Search for records in this feed	feed_onestop_id=f-sf~bay~area~rg
radius	number	Search radius (meters); requires lat and lon	lon=-122&lat=37&radius=1000
lat	number	Latitude
lon	number	Longitude
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	string 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	string 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	string 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	string 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	string 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'.

Response format

routes

array: Route

List or search for Routes

integer

Internal integer ID

route_color

string

GTFS routes.route_color; color that corresponds to a route, as a six-digit hexadecimal number (e.g. FF0000)

route_desc

string

GTFS routes.route_desc; description of a route that provides useful, quality information

route_id

string

GTFS routes.route_id

route_long_name

string

GTFS routes.route_long_name; full descriptive name of a route

route_short_name

string

GTFS routes.route_short_name; short name of a route, such as a line number or abbreviation

route_sort_order

integer

GTFS routes.route_sort_order; orders routes for display; routes with a lower value should be displayed first

route_text_color

string

GTFS routes.route_text_color; legible color to use for text drawn against the route_color background, as a six-digit hexadecimal number

route_type

integer

GTFS routes.route_type; numeric code indicating the type of transportation [0=tram/light rail, 1=subway/metro, 2=rail, 3=bus, 4=ferry, 5=cable tram, 6=aerial lift, 7=funicular, 11=trolleybus, 12=monorail]; extended types also supported

route_url

string

GTFS routes.route_url; URL of a web page about the particular route

continuous_pickup

integer

GTFS routes.continuous_pickup; indicates whether a rider can board along the route between stops [0=continuous stopping pickup, 1=no continuous stopping, 2=must phone agency, 3=must coordinate with driver]

continuous_drop_off

integer

GTFS routes.continuous_drop_off; indicates whether a rider can alight along the route between stops [0=continuous stopping drop-off, 1=no continuous stopping, 2=must phone agency, 3=must coordinate with driver]

cemv_support

integer

GTFS routes.cemv_support; whether riders can use a contactless EMV (cEMV) card or mobile device as fare media for trips on this route [0=no information, 1=supported, 2=not supported]; takes precedence over agency.cemv_support

onestop_id

string

Onestop ID for this route

geometry

Aggregated representative geometry for this route as a single LineString or MultiLineString; for direction-specific shapes see geometries

alerts

array: Alert

GTFS-RT service alerts for this route; pass active: true to return only currently active alerts

cause

string

GTFS-RT Alert cause

effect

string

GTFS-RT Alert effect

severity_level

string

Alert severity: UNKNOWN_SEVERITY, INFO, WARNING, or SEVERE

url

array: RTTranslation

URL for more information

header_text

array: RTTranslation

GTFS-RT Alert header text

description_text

array: RTTranslation

GTFS-RT Alert description text

tts_header_text

array: RTTranslation

Header text optimized for text-to-speech (TTS) systems

tts_description_text

array: RTTranslation

Description text optimized for text-to-speech (TTS) systems

active_period

array: RTTimeRange

Time ranges during which this alert is active. See https://gtfs.org/realtime/reference/#message-timerange

agency

object: Agency

Agency associated with this route

integer

Internal integer ID

agency_id

string

GTFS agency.agency_id

agency_name

string

GTFS agency.agency_name

onestop_id

string

Onestop ID for this agency (or its associated operator)

alerts

array: Alert

GTFS-RT service alerts for this agency; pass active: true to return only currently active alerts

feed_version

object: FeedVersion

Source feed version for this entity

integer

Internal integer ID

sha1

string

SHA1 hash of the zip file

Exampleab5bdc8b6cedd06792d42186a9b542504c5eef9a

fetched_at

string

Time when the file was fetched from the URL

Example2019-11-15T00:45:55.409906

feed

object: Feed

Feed associated with this feed version

route_stops

array: RouteStop

Stops on this route as RouteStop associations (with route and agency context)

stop

object: Stop

Associated stop

Routes

Request overview

Request parameters

Response format