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

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.

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

Geometry Sources

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:

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.

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