REST API - Routes

Routes

Routes are routes.txt entities imported from GTFS, and include the same basic structure and fields, plus some additional metadata and derived information. A route is a collection of trips, where each trip represents scheduled service to stops on a given day and time.

Route geometries

Each route includes a representative geometry based on the most common trip patterns for each direction. Generally, a trip shape is included if it represents at least 10% of all trips in that direction. The first shape in the geometry will be the most common shape in the predominant direction. Full shapes are available when accessing trips.

Route Onestop IDs

Onestop ID values are automatically generated for every route using a geohash of the stop locations visited by this route and the name of the route. Two very similar routes may generate the same Onestop ID value, in which more than one route entry will be returned when searching by Onestop ID.

Request overview

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

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

ParameterTypeDescriptionExample
idinteger
0 ... unlimited
Search for a specific internal ID
route_keystring

Route lookup key; can be an integer ID, a '<feed onestop_id>:<gtfs route_id>' key, or a Onestop ID
afterinteger

Return records past this record ID
limitinteger
0 ... 100
Maximum number of records to returnlimit=1
format enum
jsongeojsonpng
Response formatformat=png
include_alertsstring enum
truefalse
Include alerts from GTFS Realtime feeds
searchstring

Full text searchsearch=daly+city
onestop_idstring

Search for a specific Onestop IDonestop_id=r-9q9j-local
route_idstring

Search for records with this GTFS route_idroute_id=Bu-130
route_typeinteger

Search for records with this GTFS route_typeroute_type=1
operator_onestop_idstring

Search for records by operator OnestopIDoperator_onestop_id=...
include_geometrystring enum
truefalse
Include route geometryinclude_geometry=true
feed_version_sha1string

Search for records in this feed versionfeed_version_sha1=041ffeec...
feed_onestop_idstring

Search for records in this feedfeed_onestop_id=f-9q9-caltrain
radiusnumber
0 ... 10000
Search radius (meters); requires lat and lonlat=-122&lon=37&radius=1000
latnumber
-90 ... 90
Latitude
lonnumber
-180 ... 180
Longitude
license_commercial_use_allowed enum
yesnounknownexclude_no
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
yesnounknownexclude_no
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
yesnounknownexclude_no
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
yesnounknownexclude_no
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
yesnounknownexclude_no
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'.

Response format

Array of objects
Description Route entity
id
(integer)
Unique integer ID
onestop_id
(string)
Onestop ID for this route, if available

Exampler-dr72-1

route_id
(string)
GTFS route_id

Exampleorange

route_type
(integer)
GTFS route_type

Example3

route_short_name
(string)
GTFS route_short_name

ExampleOrange

route_long_name
(string)
GTFS route_long_name

ExampleRichmond - Warm Springs

route_color
(color)
GTFS route_color

Example#ff00bb

route_text_color
(color)
GTFS route_text_color

Example#000000

route_sort_order
(integer)
GTFS route_sort_order
continuous_pickup
(integer)
GTFS continuous_pickup
continuous_drop_off
(integer)
GTFS continuous_drop_off
agency
(object)
A subset of fields for this route's agency
feed_version
(object)
A subset of fields for this route's feed version
route_stops
(object array)
An array of all stops visited by this route. This field is only populated when requesting a single route.
stop
()
A subset of fields for this stop visited by this route
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 ] ]

Vehicle Types

Every route in Transitland has a vehicle type. The list of allowable vehicle types is drawn from the GTFS specification and Google's extended list of route types.

Unlike within GTFS feeds, Transitland allows route vehicle type to be queried by either a numerical code (e.g., 0) or text (tram). Both will return the same set of results. The route data model is always returned with the text form.

Vehicle types Textual codes for queries Numerical codes for queries Example of querying for all routes of this vehicle type
Tram tram 0 query
Metro metro 1 query
Rail rail 2 query
Bus bus 3 query
Ferry ferry 4 query
Cablecar cablecar 5 query
Gondola gondola 6 query
Funicular funicular 7 query
Railway Service railway_service 100 query
High Speed Rail Service high_speed_rail_service 101 query
Long Distance Trains long_distance_trains 102 query
Inter Regional Rail Service inter_regional_rail_service 103 query
Car Transport Rail Service car_transport_rail_service 104 query
Sleeper Rail Service sleeper_rail_service 105 query
Regional Rail Service regional_rail_service 106 query
Tourist Railway Service tourist_railway_service 107 query
Rail Shuttle (Within Complex) rail_shuttle_within_complex 108 query
Suburban Railway suburban_railway 109 query
Replacement Rail Service replacement_rail_service 110 query
Special Rail Service special_rail_service 111 query
Lorry Transport Rail Service lorry_transport_rail_service 112 query
All Rail Services all_rail_services 113 query
Cross-Country Rail Service cross-country_rail_service 114 query
Vehicle Transport Rail Service vehicle_transport_rail_service 115 query
Rack and Pinion Railway rack_and_pinion_railway 116 query
Additional Rail Service additional_rail_service 117 query
Coach Service coach_service 200 query
International Coach Service international_coach_service 201 query
National Coach Service national_coach_service 202 query
Shuttle Coach Service shuttle_coach_service 203 query
Regional Coach Service regional_coach_service 204 query
Special Coach Service special_coach_service 205 query
Sightseeing Coach Service sightseeing_coach_service 206 query
Tourist Coach Service tourist_coach_service 207 query
Commuter Coach Service commuter_coach_service 208 query
All Coach Services all_coach_services 209 query
Suburban Railway Service suburban_railway_service 300 query
Urban Railway Service urban_railway_service 400 query
Metro Service metro_service 401 query
Underground Service underground_service 402 query
Urban Railway Service urban_railway_service 403 query
All Urban Railway Services all_urban_railway_services 404 query
Monorail monorail 405 query
Metro Service metro_service 500 query
Underground Service underground_service 600 query
Bus Service bus_service 700 query
Regional Bus Service regional_bus_service 701 query
Express Bus Service express_bus_service 702 query
Stopping Bus Service stopping_bus_service 703 query
Local Bus Service local_bus_service 704 query
Night Bus Service night_bus_service 705 query
Post Bus Service post_bus_service 706 query
Special Needs Bus special_needs_bus 707 query
Mobility Bus Service mobility_bus_service 708 query
Mobility Bus for Registered Disabled mobility_bus_for_registered_disabled 709 query
Sightseeing Bus sightseeing_bus 710 query
Shuttle Bus shuttle_bus 711 query
School Bus school_bus 712 query
School and Public Service Bus school_and_public_service_bus 713 query
Rail Replacement Bus Service rail_replacement_bus_service 714 query
Demand and Response Bus Service demand_and_response_bus_service 715 query
All Bus Services all_bus_services 716 query
Trolleybus Service trolleybus_service 800 query
Tram Service tram_service 900 query
City Tram Service city_tram_service 901 query
Local Tram Service local_tram_service 902 query
Regional Tram Service regional_tram_service 903 query
Sightseeing Tram Service sightseeing_tram_service 904 query
Shuttle Tram Service shuttle_tram_service 905 query
All Tram Services all_tram_services 906 query
Water Transport Service water_transport_service 1000 query
International Car Ferry Service international_car_ferry_service 1001 query
National Car Ferry Service national_car_ferry_service 1002 query
Regional Car Ferry Service regional_car_ferry_service 1003 query
Local Car Ferry Service local_car_ferry_service 1004 query
International Passenger Ferry Service international_passenger_ferry_service 1005 query
National Passenger Ferry Service national_passenger_ferry_service 1006 query
Regional Passenger Ferry Service regional_passenger_ferry_service 1007 query
Local Passenger Ferry Service local_passenger_ferry_service 1008 query
Post Boat Service post_boat_service 1009 query
Train Ferry Service train_ferry_service 1010 query
Road-Link Ferry Service road-link_ferry_service 1011 query
Airport-Link Ferry Service airport-link_ferry_service 1012 query
Car High-Speed Ferry Service car_high-speed_ferry_service 1013 query
Passenger High-Speed Ferry Service passenger_high-speed_ferry_service 1014 query
Sightseeing Boat Service sightseeing_boat_service 1015 query
School Boat school_boat 1016 query
Cable-Drawn Boat Service cable-drawn_boat_service 1017 query
River Bus Service river_bus_service 1018 query
Scheduled Ferry Service scheduled_ferry_service 1019 query
Shuttle Ferry Service shuttle_ferry_service 1020 query
All Water Transport Services all_water_transport_services 1021 query
Air Service air_service 1100 query
International Air Service international_air_service 1101 query
Domestic Air Service domestic_air_service 1102 query
Intercontinental Air Service intercontinental_air_service 1103 query
Domestic Scheduled Air Service domestic_scheduled_air_service 1104 query
Shuttle Air Service shuttle_air_service 1105 query
Intercontinental Charter Air Service intercontinental_charter_air_service 1106 query
International Charter Air Service international_charter_air_service 1107 query
Round-Trip Charter Air Service round-trip_charter_air_service 1108 query
Sightseeing Air Service sightseeing_air_service 1109 query
Helicopter Air Service helicopter_air_service 1110 query
Domestic Charter Air Service domestic_charter_air_service 1111 query
Schengen-Area Air Service schengen-area_air_service 1112 query
Airship Service airship_service 1113 query
All Air Services all_air_services 1114 query
Ferry Service ferry_service 1200 query
Telecabin Service telecabin_service 1300 query
Telecabin Service telecabin_service 1301 query
Cable Car Service cable_car_service 1302 query
Elevator Service elevator_service 1303 query
Chair Lift Service chair_lift_service 1304 query
Drag Lift Service drag_lift_service 1305 query
Small Telecabin Service small_telecabin_service 1306 query
All Telecabin Services all_telecabin_services 1307 query
Funicular Service funicular_service 1400 query
Funicular Service funicular_service 1401 query
All Funicular Service all_funicular_service 1402 query
Taxi Service taxi_service 1500 query
Communal Taxi Service communal_taxi_service 1501 query
Water Taxi Service water_taxi_service 1502 query
Rail Taxi Service rail_taxi_service 1503 query
Bike Taxi Service bike_taxi_service 1504 query
Licensed Taxi Service licensed_taxi_service 1505 query
Private Hire Service Vehicle private_hire_service_vehicle 1506 query
All Taxi Services all_taxi_services 1507 query
Self Drive self_drive 1600 query
Hire Car hire_car 1601 query
Hire Van hire_van 1602 query
Hire Motorbike hire_motorbike 1603 query
Hire Cycle hire_cycle 1604 query
Miscellaneous Service miscellaneous_service 1700 query
Cable Car cable_car 1701 query
Horse-drawn Carriage horse-drawn_carriage 1702 query