apirtroute

Documentation

Overview

Package apirtroute contains the internal implemetation for RTRoute

Index

• type RouteDiagnostics
• type RouteLeg
• type RouteParams
• type RouteResponse
  • func RTRoute(runtime *apirtinit.MobrouteRuntime, params *RouteParams) (*RouteResponse, error)
• type RouteStopDetails

Types

type RouteDiagnostics

type RouteDiagnostics = diagnosticst.RouteDiagnostics

RouteDiagnostics contains diagnostic information for a routing request measuring number of seconds for specific parts of the pipeline, memory usage, and meta route information.

• The PerfS fields indicate the amount of time taken for each stage.
• The PerfNMem fields indicate the length of the arrays for each SQL query type extracted
• The PerfOptimizedFeeds fields indicated which feed IDs were actually queries (as this is optimized earlier in the pipeline).
• The Routeinfo fields contain various calculated route metalevel diagnostics.

type RouteLeg

type RouteLeg = formatterlegs.RouteLeg

RouteLeg represents a 'leg' in a route which may be one of: transfer, walk, or trip type (see the LegType field).

When the LegType is equal to "trip", all fields prefixed with Trip* will be non-nil / present. A trip leg represents one boarding of a segment of a trip (e.g. a single bus route, or a single train route etc.). Underlying this is flagged by a single trip ID sourced from the stop_times GTFS table.

When the LegType is equal to "walk", all fields prefixed with Walk* will be non-nil / present. A walk leg represents the segment of time walking to the origin station (e.g. with the first trip); or walking from the destination station (e.g. with the last trip). A walk has a correlated distance KM and the walk to/from fields will contain the relevant stop IDs. The walk KM is automatically calculated from the input constraints for walk km / hr.

When the LegType is equal to "transfer", all fields prefixed with Transfer* will be non-nil / present. A transfer leg represents the segment of time to get from one trip leg to another trip leg. Transfers can be sourced from a number of places (e.g. either implicit, feed, or generated) and always have an associated duration. The field TransferDdwell indicates the amount of inactive time in the transfer (waiting / dwelling); while TransferActive indicates active time walking getting from one stop to another.

type RouteParams

type RouteParams struct {
	// Required
	FeedIDs            []int      `json:"feed_ids" validate:"required,gt=0"`                                                                      // Feed IDs to apply
	From               [2]float64 `json:"from" validate:"required,len=2"`                                                                         // Origin for the route in lat, lon format
	To                 [2]float64 `json:"to" validate:"required,len=2"`                                                                           // Destination for the route in lat, lon format
	TransferCategories []string   `json:"transfer_categories" validate:"required,dive,oneof=f i g"`                                               // Transfer categories
	OutputFormats      []string   `json:"output_formats" validate:"required,gt=0,dive,oneof=connections legs geojson mapurl diagnostics request"` // Output formats

	// Non-Required (has default values - see RTRoute logic)
	Time               *time.Time `json:"time" validate:"required"`                                     // Time at which the route should depart (Default: now)
	MaxNTransfers      uint       `json:"max_n_transfers" validate:"required"`                          // Maximum number of transfer to consider for the route (Default: 20)
	MaxTransferSeconds uint       `json:"max_transfer_seconds" validate:"gtfield=MinTransferSeconds"`   // Maximum seconds a transfer can take (Default: 40*60)
	MaxTripSeconds     uint       `json:"max_trip_seconds" validate:"gt=0"`                             // Maximum seconds for a total route (trip) duration (Default: 240*60)
	MaxWalkSeconds     uint       `json:"max_walk_seconds" validate:"gt=0"`                             // Maximum seconds walking on start and end (Default: 20*60)
	MinTransferSeconds uint       `json:"min_transfer_seconds" validate:"required"`                     // Minimum seconds a transfer can take (Default: 3*60)
	WalkspeedKmHr      float64    `json:"walkspeed_km_hr" validate:"gt=0"`                              // Walk speed in km/hr form (Default: 3.5)
	Optimizations      []string   `json:"optimizations" validate:"required,gt=0,dive,oneof=feedsclean"` // Optimizations to apply - advanced functionality (Default: [feedsclean])
}

RouteParams contains the parameters for a given route request for RTRoute. The FeedIDs, From, To, TransferCategories, and Output format fields are required. Other fields are optional and will be filled in with default values if unset.

• Extended information about params (tunables) are available in the Tunables Doc.
• Extended information about output formats are available in the Output Formats Doc.

type RouteResponse

type RouteResponse struct {
	RouteLegs        *[]RouteLeg                        `json:"legs,omitempty"`
	GeoJSON          *[]formattergeojson.GeoJSONFeature `json:"geojson,omitempty"`
	MapURL           *string                            `json:"mapurl,omitempty"`
	Request          *RouteParams                       `json:"request,omitempty"`
	RouteDiagnostics *RouteDiagnostics                  `json:"diagnostics,omitempty"`
	Connections      *[]dbt.ConnectionVerbose           `json:"connections,omitempty"`
}

RouteResponse is the response for a successful RTRoute routing request.

Each field may optionally be present depending on if RouteParams's OutputFormats is set for the associated output format.

The Output Formats Doc has extended information on each output format, a basic overview of each format is as follows:

• RouteLegs: Contains an array of 'legs' for each segment of a calculated trip.
• GeoJSON: GeoJSON created from the RouteLegs, less information then legs but simpler to integrate with other apps that support GeoJSON.
• MapURL: A link to the GeoJSON embeded in hash on geojson.lrdu.org.
• Request: Origin RouteParams directly embedded for simpler testing and replication of request.
• RouteDiagnostics: The RouteDiagnostics contains some simple diagnostics information about the request.
• Connections: Array of raw git.sr.ht/~mil/mobroute/dbt.ConnectionVerbose that were used for the input to the CSA algorithm. This can be helpful for spot debugging.

func RTRoute

func RTRoute(runtime *apirtinit.MobrouteRuntime, params *RouteParams) (*RouteResponse, error)

RTRoute performs point-to-point routing calculations via the Connection Scan Algorithm based on GTFS data extracted from database queries. Effected by routing constraints defined in RouteParams and returns a RouteResponse. The entire routing flow from extracting from the DB the required data for CSA, to running the CSA algorithm, to going back to the DB to pull a few extra fields for presentation, and finally formatting the data into route legs for easy consumption is handled by this function. The underlying methodology used for for routing can be understood by reading the Connection Scan Algorithm paper which this function is an implementation of. The routing dataflow pattern diagram can be helpful in understanding overall dataflow.

Note: provided feed IDs in RouteParams should first be loaded and computed via [RTDatabase].

type RouteStopDetails

type RouteStopDetails = formatterlegs.RouteStopDetails

RouteStopDetails represents a stop within a trip. This allows more fine-grained detailed into each 'stop' in a common trip. Ultimately this correlates to a single connection in the table _ctconn and can be referenced by using the field ConnOID.