Routes and route stop patterns

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.

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 Sources

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.

Threshold computation

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:

  1. 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.
  2. 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"
    }
}