This documentation is for the Transitland v1 platform, which was shut down as of October 31, 2023. The Transitland v2 APIs provide equivalent functionality and more.
Routes and route stop patterns
Transit routes are geographical areas of service. Transitland has two models to effectively represent routes and their connection to services: the Route and the RouteStopPattern. Routes are essentially a summary of the aggregate characteristics of the whole transit route. RouteStopPatterns are geographical representations of the services that make up the Route.
Routes
Route Data Model
Attribute | Type | Description |
---|---|---|
onestop_id | Onestop ID | A unique identifier for this route |
name | String | Name of Route |
vehicle_type | String | Type of transportation used |
color | String | Route color in 6 hexidecimal characters |
geometry | Geography | MultiLineString. A representative sample of the whole route geometry. |
wheelchair_accessible | String | Wheelchair accessible: some_trips, all_trips, no_trips, or unknown |
bikes_allowed | String | Bike accessible: some_trips, all_trips, no_trips, or unknown |
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 |
Route Representative Geometry
The Route model geometry is a representation of the actual given route geometry, and may not contain every path from the original data. The Route geometry is primarily for visualizing the route as a whole as efficiently as possible; a complete (but often redundant) set of the geometry would be the set of all the Route's RouteStopPatterns. To compute this geometry, a sample of the Route's RouteStopPatterns is chosen by mapping every sequential pair of stops to a list of RouteStopPatterns that visit the stop pair. A single RouteStopPattern is chosen from each of those lists, and those chosen RouteStopPatterns make up the sample. After a representative selection of RouteStopPatterns is made, the Douglas-Peucker algorithm is applied to remove coordinates that are extraneous to visualization. It is important to note that if there are two distinct paths for a single sequential stop pair, only one of those paths might end up being chosen. This is why the Route geometry is not always a complete representation of the true geometry.
RouteStopPattern
In addition to the Route, Transitland models route geometries by breaking them into individual components called RouteStopPatterns, or sometimes RSPs. RouteStopPatterns are uniquely defined by a route, a stop pattern, and a line geometry; all three derived from the trip routes, trip stop sequences, and shapes of a GTFS feed and its services. Because of this, it is possible to have two distinct RouteStopPatterns within one route, both sharing the same line geometry but having different stop patterns, and vice versa. Individual RouteStopPatterns also have records of the GTFS trips and the single shape used to create them; a typical RouteStopPattern will reference back to one or many trips having the same stop pattern, but only references the one shape shared by those trips. When a RouteStopPattern's trips have no shapes or empty shapes, there will be no shape reference.
RouteStopPatterns may also modify the original shape line geometry if necessary. Currently, the line geometry is only modified when it is generated as the result of missing its original GTFS shape id or shape points. In this case, the line geometry becomes the sequential points of the stop pattern
RouteStopPattern Data Model
Attribute | Type | Description |
---|---|---|
onestop_id | Onestop ID | RouteStopPattern |
route_onestop_id | Onestop ID | Route |
geometry | Geography | LineString |
stop_pattern | Onestop ID array | List of stops along geometry in trip order. Stops may reappear. |
stop_distances | Number array | List of distances in meters of stop_pattern stops along geometry. |
identifiers | String array | List of identifiers. |
trips | String array | List of trip ids |
tags | Object of keys and values | When imported from GTFS, includes the associated shape_id |
geometry_source | String | One of a set of values that indicate how the current line geometry originated. |
Geometry Source | Description |
---|---|
trip_stop_points | The line has been generated from the stop points. |
shapes_txt | Shape points exist but do not have distance information. |
shapes_txt_with_dist_traveled | Shape points exist and have distance information. This also indicates that stop times has distance information. |
user_edited | The line geometry has been manually generated or edited. |
Onestop ID
RouteStopPatterns are uniquely identified by a Onestop Id, but the composition of this id is different from that of Route, Stop, Feed, and Operator Onestop Ids. The RouteStopPattern Onestop Id has 5 components instead of 3, with each component separated by a dash just as the ids of the latter Transitland entities. The first 3 components are exactly the Route Onestop Id of the Route to which the RouteStopPattern belongs to. The fourth component is the first 6 hexadecimal characters of the MD5 hash produced from the stop pattern string (stop onestop id's separated by comma). The fifth component is the first 6 hexadecimal characters of the MD5 hash produced from geometry coordinates as a string (coordinates separated by comma).
Distance calculation heuristic algorithm
RouteStopPatterns' stop_distances are useful for cutting a slice of the route line between two stops for visualization, among other reasons. Each ScheduleStopPair has an associated RouteStopPattern. In addition, two attributes have been added to ScheduleStopPair: origin_distance_traveled and destination_distance_traveled. These are the distances, in meters rounded to the nearest decimeter, of the origin and destination stops along the line geometry from the start point.
The algorithm for calculating stop_distances must first solve the problem of matching stops to a set of optimal segments of the route line. A set of segment matches for the RSP stops is optimal if the distances between the stops and the nearest points of the chosen segments are minimized, with the constraint that distances along the route line of the nearest points of the chosen segments (stop_distances) are increasing for each subsequent stop.
The current algorithm runs as follows, with some details omitted. First, it computes reasonable segment matching possibilities for each stop based on a threshold of how far the stop is from the segment. Then for each stop in order, the algorithm loops through each segment match possibility in sorted order of distance from the line, until it finds a list of all subsequent stop distances along the line ahead that are in increasing order. Each stop's segment evaluation results in a recursive call to the next stop. Recursion is valuable because a poor segment choice for one stop can cause inaccuracies that aren't apparent until much later along the stop pattern for other stops.
The distance threshold for segment matches is computed for each RouteStopPattern, and its value is computed as follows. Imagine the two triangle legs formed by the average of all stops' minimum distance to the line and half the average distance between the two neighboring stops on either side of a single stop (so the threshold value can be different for each stop). The threshold value is the length, in meters, of the hypotenuse formed from these legs.
The distance calcuation is not always perfect, unfortunately. Transitland logs inaccuracies through Quality Issues. If any inaccuracies are found for a particular RouteStopPattern, the stop_distances for that RouteStopPattern are set to null.
Before and After Stops
Sometimes stops at the beginning and end of route lines are found to be off the route line. The algorithm needs to identify these stops so that their distances can be set to 0.0 meters for stops before the route line, and the length of the route line for stops after. Here are the conditions for determining these "before" and "after" stops. The examples are for "before" stops, but the same logic applies in reverse for "after" stops. A stop is considered to be before a RouteStopPattern line geometry if its point satisfies one of two conditions:
- It is found on the opposite side of the line that is perpendicular to the first line segment that passes through the first endpoint of the segment.
- It is greater than 100 meters distant from any point in the line geometry.
For example:
Before:
| x |-----------> |
Before:
| |-----------> | ] 100 m x
Not before:
| |-----------> | x ] 100 m
Query parameters
The main RouteStopPattern API endpoint is https://transit.land/api/v1/route_stop_patterns. It accepts the following query parameters, which may be freely combined.
Query parameter | Type | Description | Example |
---|---|---|---|
onestop_id | Onestop ID | RouteStopPattern. | with Onestop ID r-9q9-pittsburg~baypoint~sfia~millbrae-49ae87-5ae164 |
traversed_by | Onestop ID | Route. Accepts multiple route onestop ids separated by commas. | belonging to Route Pittsburg/Bay Point - SFIA/Millbrae |
stops_visited | Onestop ID | Stop. Accepts multiple separated by commas. | Having stop MacArthur |
trips | String | Derived from trip. Accepts multiple trips ids separated by commas. | Having trips |
bbox | Lon1,Lat1,Lon2,Lat2 | RouteStopPatterns within bounding box | in the Bay Area |
Response format
{
"route_stop_patterns": [
{
"identifiers": [
"gtfs://f-9q9-caltrain/trip/147",
"gtfs://f-9q9-caltrain/trip/RTD8550540",
"gtfs://f-9q9-caltrain/trip/155",
"gtfs://f-9q9-caltrain/trip/191",
"gtfs://f-9q9-caltrain/trip/193",
"gtfs://f-9q9-caltrain/trip/199",
"gtfs://f-9q9-caltrain/trip/135",
"gtfs://f-9q9-caltrain/trip/101",
"gtfs://f-9q9-caltrain/trip/139",
"gtfs://f-9q9-caltrain/trip/143",
"gtfs://f-9q9-caltrain/trip/RTD8550531",
"gtfs://f-9q9-caltrain/trip/RTD8550532",
"gtfs://f-9q9-caltrain/trip/RTD8550533",
"gtfs://f-9q9-caltrain/trip/RTD8550534",
"gtfs://f-9q9-caltrain/trip/RTD8550535",
"gtfs://f-9q9-caltrain/trip/RTD8550536",
"gtfs://f-9q9-caltrain/trip/RTD8550537",
"gtfs://f-9q9-caltrain/trip/RTD8550538",
"gtfs://f-9q9-caltrain/trip/RTD8550539",
"gtfs://f-9q9-caltrain/trip/151"
],
"imported_from_feed_onestop_ids": [
"f-9q9-caltrain"
],
"imported_from_feed_version_sha1s": [
"36ba71b654ba6ed1e4866822832c11942c4761e5"
],
"created_or_updated_in_changeset_id": 10,
"onestop_id": "r-9q9-local-f68455-dcd599",
"route_onestop_id": "r-9q9-local",
"stop_pattern": [
"s-9q9k652x5g-caltrain~diridonstation",
"s-9q9k3rbsm5-caltrain~santaclarastation",
"s-9q9hxghghb-caltrain~lawrencestation",
"s-9q9hxhefny-caltrain~sunnyvalestation",
"s-9q9hwp7n80-caltrain~mountainviewstation",
"s-9q9hv3gt1t-caltrain~sanantoniostation",
"s-9q9hutfdz0-caltrain~californiaavestation",
"s-9q9jh06g20-caltrain~paloaltostation",
"s-9q9j5dmedf-caltrain~menloparkstation",
"s-9q9j681ejk-caltrain~redwoodcitystation",
"s-9q9j3uj1fs-caltrain~sancarlosstation",
"s-9q9j3w3tux-caltrain~belmontstation",
"s-9q9j916p33-caltrain~hillsdalestation",
"s-9q9j8u1jr3-caltrain~haywardparkstation",
"s-9q9j8qyzjx-caltrain~sanmateostation",
"s-9q8vzcqbz3-caltrain~burlingamestation",
"s-9q8vzh9pm5-caltrain~millbraestation",
"s-9q8yn6qcdh-caltrain~sanbrunostation",
"s-9q8ynwfu1e-caltrain~ssanfranciscostation",
"s-9q8yw9n59m-caltrain~bayshorestation",
"s-9q8yycsdkr-caltrain~22ndststation",
"s-9q8yyv42k3-caltrain~sanfranciscostation"
],
"geometry": {
"type": "LineString",
"coordinates": [
[
-121.903447,
37.328642
],
[
-121.936346,
37.352892
],
[
-121.996437,
37.370515
],
[
-122.030683,
37.378613
],
[
-122.075954,
37.394458
],
[
-122.108158,
37.40796
],
[
-122.142258,
37.42952
],
[
-122.164182,
37.44334
],
[
-122.182266,
37.454382
],
[
-122.231594,
37.485892
],
[
-122.259862,
37.507648
],
[
-122.275574,
37.520713
],
[
-122.297001,
37.537416
],
[
-122.309097,
37.552181
],
[
-122.32325,
37.567616
],
[
-122.345145,
37.580246
],
[
-122.386097,
37.599223
],
[
-122.411291,
37.629831
],
[
-122.405821,
37.654972
],
[
-122.401366,
37.711202
],
[
-122.392318,
37.757692
],
[
-122.395406,
37.776541
]
]
},
"created_at": "2016-02-06T20:05:59.645Z",
"updated_at": "2016-02-06T20:05:59.645Z",
"trips": [
"147",
"RTD8550540",
"155",
"191",
"193",
"199",
"135",
"101",
"139",
"143",
"RTD8550531",
"RTD8550532",
"RTD8550533",
"RTD8550534",
"RTD8550535",
"RTD8550536",
"RTD8550537",
"RTD8550538",
"RTD8550539",
"151"
],
"tags": {
"shape_id": null
}
}
],
"meta": {
"offset": 0,
"per_page": 50,
"next": "https://transit.land/api/v1/route_stop_patterns?offset=50&per_page=50"
}
}