mobroute

README

Mobroute

Mobroute is a general purpose FOSS public transportation router (e.g. trip planner) Go library and CLI that works by directly ingesting timetable (GTFS) data from transit agencies themselves (sourced from the Mobility Database). After data has been fetched, routing calculations can be run offline, and locally / on-device (as opposed to making a network call). Overall, Mobroute aims to offer an opensource framework (both CLI & library) for integrating data-provider-agnostic GTFS public transit capabilities (integrated GTFS ETL, GTFS multisource support, and routing algorithm) into applications to get users from point-a to point-b via public transit without comprising privacy or user freedoms.

In addition to the Mobroute Go library & CLI, the related subproject, the Transito app offers fully integrated routing functionality on mobile devices (Android & Linux) utilizing Mobroute's Go library.

The Mobroute & Transito projects overall are currently in active development but generally currently usable on mobile & via the CLI and looking for more users & testers. Mobroute & Transito work in many well-connected metros which have publicly available GTFS data, to name a few: Lisbon, NYC, Brussels, Krakow, and Bourges. You can see sample routes at the automated test results page, check for your metro here, and see details on the Transito mobile app here.

Documentation:

• Mobroute Doc: CLI Userguide, Go Library Userguide, Available GTFS Feeds, Tunable Parameters, Development, Contribute, Roadmap
• Project Management: Bugtracker, Mailing List
• CI: Test Results (master), Test Results (by commit), Generated APKs, Builds
• Related: Transito (Mobile App), Mobsql (GTFS-to-SQLite ETL library)

Project Overview / Featureset:

• Well-executed singlemodal public transportation routing via GTFS data
  • Project focuses on implementing only GTFS routing providing for algorithmic & codebase simplicity
  • Other routers bill themselves as "multimodal"; Mobroute is proudly singlemodal (doesn't integrate automobile/OSM/PBF data)
  • Overall.. does one thing well: public transportation routing
• Integration of automatic GTFS dataimport & ETL out-of-the-box via the Mobility Database
  • Frees user from having to source & manually download/import GTFS zip archives
  • System automatically downloads the data needed for a routing requests upon use
  • Supports using multiple GTFS sources independently and in combination for single routing requests
  • See Mobsql for details on ETL pipeline, uses SQLite under the hood
• Efficient algorithmic routing via the Connection Scan Algorithm (CSA)
  • Being a singlemodal router lends Mobroute's design to implementation simplicity
  • The well academically studied CSA algorithm is utilized: see paper details here
  • CSA is non-graphbased, simple, and Mobroute's CSA implementation is well tested
• Targeted to on-device and offline usage
  • Designed to be used on-device and offline once data is fetched
  • Run your routing request right on your mobile device for the privacy conscious
• Fully thought-out small, simple, & modular design supporting library, CLI, & mobile usage
  • Built in Go, the design of the project is small and modular
  • 3 primary components:
    • Mobsql (GTFS-to-SQLite ETL pipeline: CLI + Go Library)
    • Mobroute (Core routing algorithm via CSA: CLI + Go Library)
    • Transito (Graphical mobile application for Android & Linux)
  • Mobsql and Mobroute can be used as both a CLI OR as a Go library in your application
  • Transito, Mobroute's mobile application is written in Go (via Gio) and uses Mobroute's Go Library

Architecture:

The Mobroute project is composed of 3 separate codebases / smaller projects:

• Mobsql: is a GTFS-to-SQL ETL tool which pulls GTFS sources from the MobilityDB into a SQLite database. It exposes both a CLI & a Go library (consumed by Mobroute).
• Mobroute: is the core routing tool. This project handles interfacing the Mobsql Go Library and then once the DB is loaded, opens the DB and performs routing calculations (currently via the Connection Scan Algorithm). It exposes both a CLI & a Go library ( consumed by Transito).
• Transito: is a simple Android & Linux GUI app to use Mobroute. It allows querying from/to via Nominatim and performing routing calculations on-the-go via Mobroute's underlying routing mechanism (note this implicitly integrates Mobsql as well).

Documentation

Overview

Package mobroute is a library allowing you to load GTFS data and perform routing requests against a single or multiple feeds. The core algorithm is based on Connection-Scan-Algorithm (CSA) methodology. The algorithm operates offline once initial data is fetched; and is designed to be used locally and in mobile enviroments. Mobroute can be used to add public routing functionality to existing map & navigation apps or tools. For sample integrations see Transito which demonstrates integrating Mobroute's runtime library functions in a mobile context (Android & Linux).

All public funcionality is exposed through the single mobroute (git.sr.ht/~mil/mobroute) package. Functionality outside of this package should be considered to be implementation details, unstable, and not used by end consumers.

Runtime vs Oneshot Functions

Library functionality is split into two categories:

• Runtime functions (prefixed with RT): These are lower-level functions that allow you to store a single database connection between multiple function calls. All functions are based on a common stored database connection created via an initial RTInitialize() function response.

• Oneshot functions (prefixed with Oneshot): These functions allows you to run route & other requests in a single call. This has the advantage allowing the entire request to be parameterized into single param request object. Doesn't pool the DB connection between requests. DB is opened at the start of each OneshotX function and closed at the end of the funtion

Building

When building you must pass `-tags=sqlite_math_functions` to the `go build` command as this enables the underlying sqlite library to utilize math functions which Mobroute's core logic depends on.

Example:

go build -tags=sqlite_math_functions foo.go

Example Usages

Example usage pattern for Runtime functionality:

// Build via: go build -tags=sqlite_math_functions example.go
package main

import (
	"encoding/json"
	"git.sr.ht/~mil/mobroute"
	"log"
)

func main() {
	var (
		mobrouteRuntime *mobroute.MobrouteRuntime
		routeResult     *mobroute.RouteResponse
		err             error
	)

	// (1) Create a MobrouteRuntime:
	if mobrouteRuntime, err = mobroute.RTInitialize(&mobroute.MobrouteRuntimeConfig{}); err != nil {
		log.Fatal("Failed to initialize Mobroute Runtime")
	}

	// (2) Run a Routing Request:
	if routeResult, err = mobroute.RTRoute(
		mobrouteRuntime,
		&mobroute.RouteParams{
			FeedIDs:            []int{1088},
			From:               [2]float64{50.85728, 4.351426},
			To:                 [2]float64{50.83214, 4.350534},
			TransferCategories: []string{"f", "i"},
			OutputFormats:      []string{"legs", "mapurl"},
		},
	); err != nil {
		log.Fatal("Error running RTRoute", err)
	}

	// (3) Display Result
	jsonLegs, _ := json.Marshal(*routeResult.RouteLegs)
	log.Println("Route Legs:", string(jsonLegs))
	log.Println("Viewable map URL:", *routeResult.MapURL)
}

Example usage pattern for Oneshot functionality:

// Build via: go build -tags=sqlite_math_functions example.go
package main

import (
	"encoding/json"
	"git.sr.ht/~mil/mobroute"
	"log"
)

func main() {
	var (
		routeResult *mobroute.RouteResponse
		err         error
	)

	// (1) Run a Routing Request:
	if routeResult, err = mobroute.OneshotRoute(&mobroute.OneshotRouteRequest{
		RouteParams: &mobroute.RouteParams{
			FeedIDs:            []int{1088},
			From:               [2]float64{50.85728, 4.351426},
			To:                 [2]float64{50.83214, 4.350534},
			TransferCategories: []string{"f", "i"},
			OutputFormats:      []string{"legs", "mapurl"},
		},
	}); err != nil {
		log.Fatal("Error running RTRoute", err)
	}

	// (2) Display Result
	jsonLegs, _ := json.Marshal(*routeResult.RouteLegs)
	log.Println("Route Legs:", string(jsonLegs))
	log.Println("Viewable map URL:", *routeResult.MapURL)
}

Index

• func OneshotMobsql(r *OneshotMobsqlRequest) (any, error)
• type MobrouteRuntime
  • func RTInitialize(params *MobrouteRuntimeConfig) (*MobrouteRuntime, error)
• type MobrouteRuntimeConfig
• type MobsqlRuntimeConfig
• type OneshotMobsqlRequest
• type OneshotRouteRequest
• type RouteDiagnostics
• type RouteLeg
• type RouteParams
• type RouteResponse
  • func OneshotRoute(r *OneshotRouteRequest) (*RouteResponse, error)
  • func RTRoute(runtime *MobrouteRuntime, paramsGiven *RouteParams) (*RouteResponse, error)
• type RouteStopDetails

Functions

func OneshotMobsql

func OneshotMobsql(r *OneshotMobsqlRequest) (any, error)

OneshotDatabase performs a database request via the underlying mobsql API commands. This is essentially just a thin layer to run underlying mobsql API fns).

Types

type MobrouteRuntime

type MobrouteRuntime = apirtinit.MobrouteRuntime

MobrouteRuntime contains the database connection & MobsqlRuntime.

func RTInitialize

func RTInitialize(params *MobrouteRuntimeConfig) (*MobrouteRuntime, error)

RTInitialize initializes a MobrouteRuntime which contains a passthrough to the MobsqlRuntime & some additional metadata.

type MobrouteRuntimeConfig

type MobrouteRuntimeConfig = apirtinit.MobrouteRuntimeConfig

MobrouteRuntimeConfig contains the MobsqlRuntimeConfig & potentially in the future some other Mobroute-specific properties for the common DB connection & Mobroute params.

type MobsqlRuntimeConfig

type MobsqlRuntimeConfig = apirtinit.MobsqlRuntimeConfig

MobsqlRuntimeConfig is just an alias for Mobsql's RuntimeConfig, see mobsql.RuntimeConfig for further documentation.

type OneshotMobsqlRequest

type OneshotMobsqlRequest = apioneshot.OneshotMobsqlRequest

OneshotMobsqlRequest groups both the MobrouteRuntimeConfig and MobsqlParams for the mobsql request

type OneshotRouteRequest

type OneshotRouteRequest = apioneshot.OneshotRouteRequest

OneShotRouteRequest groups both the MobrouteRuntimeConfig and RouteParams

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.

type RouteLeg

type RouteLeg = formatterlegs.RouteLeg

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

The Leg* properties are always present, Trip*, Transfer*, and Walk* fields may be nonnil depending on the LegType field.

type RouteParams

type RouteParams = apirtroute.RouteParams

RouteParams contains the parameters for a given route request.

type RouteResponse

type RouteResponse = apirtroute.RouteResponse

RouteResponse is the response for a successful routing request.

func OneshotRoute

func OneshotRoute(r *OneshotRouteRequest) (*RouteResponse, error)

OneshotRoute performs routing in a one-shot / single function fashion. All parameters for the entire request are passed in the OneShotRouteRequest.

func RTRoute

func RTRoute(runtime *MobrouteRuntime, paramsGiven *RouteParams) (*RouteResponse, error)

Route performs the routing logic, extracting from the DB the required data for CSA, running the CSA algorithm, going back to the DB to pull a few extra fields for presentation, and finally formatting the data into route legs for easy consumption.

type RouteStopDetails

type RouteStopDetails = formatterlegs.RouteStopDetails

RouteStopDetails represents a stop within a trip.