API Documentation

This module provides algorithms for multimodal transit routing, isochrone generation, and travel-time matrix calculations. It includes functions to:

• Find optimal routes combining walking and public transit (find_route()).

• Compute routes from a single origin to multiple destinations (find_routes_one_to_many()).

• Generate isochrones to visualize travel-time polygons (calculate_isochrone()).

• Calculate travel-time matrices for multiple points (travel_time_matrix()).

• Perform time-range routing to find journeys across a range of departure times (range_multimodal_routing()).

The module also defines several classes, including:

• TransitPoint: A Python wrapper for geographic points connected to the transit network, used as origins or destinations in routing operations.

• TransitModel: A unified model integrating street networks and public transit schedules for multimodal routing.

• RangeRoutingResult: A result object for time-range multimodal routing.

Examples

from ferrobus import create_transit_model, find_route, create_transit_point

# Create a transit model
model = create_transit_model(
    osm_path="path/to/roads.osm.pbf",
    gtfs_dirs=["path/to/gtfs"],
    max_transfer_time=1800,
    date=None  # Use current date
)

# Create transit points
origin = create_transit_point(lat=59.85, lon=30.22, transit_model=model)
destination = create_transit_point(lat=59.97, lon=30.50, transit_model=model)

# Find the optimal route
route = find_route(
    transit_model=model,
    start_point=origin,
    end_point=destination,
    departure_time=43200,  # 12:00 noon in seconds
    max_transfers=3
)

print(f"Travel time: {route['travel_time_seconds'] / 60:.1f} minutes")
print(f"Number of transfers: {route['transfers']}")

API Reference

Routing Functions

ferrobus.find_route	Find an optimal route between two points in a transit network
ferrobus.find_routes_one_to_many	Find routes from one point to multiple destinations
ferrobus.pareto_range_multimodal_routing
ferrobus.range_multimodal_routing
ferrobus.detailed_journey	Find a detailed journey between two points in a transit network
ferrobus.parallel_detailed_journeys	Find detailed journeys from one point to multiple destinations in parallel

Isochrone and Matrix Functions

ferrobus.calculate_isochrone	Calculate an isochrone from a single starting point
ferrobus.calculate_bulk_isochrones	Calculate isochrones from multiple starting points in batch mode
ferrobus.calculate_percent_access_isochrone	Calculate percentage-based accessibility across multiple departure times
ferrobus.travel_time_matrix	Computes a matrix of travel times between all points in the input set in parallel.
ferrobus.travel_time_statistics	Computes travel time statistics from each point to all targets in parallel.

Utility Functions

ferrobus.create_transit_model	Create a unified transit model from OSM and GTFS data
ferrobus.create_transit_point	Create a transit point at specified geographic coordinates
ferrobus.create_isochrone_index	Create a spatial index for isochrone calculations

Classes

class ferrobus.TransitModel

TransitModel

A unified transit model that integrates both the street network (OSM) and public transit schedules (GTFS) for multimodal routing.

This model serves as the foundation for all routing operations, containing the complete graph representation of both networks with interconnections between transit stops and the street network.

Core components:

• Street network for walking/access paths

• Transit stops, routes and schedules

• Transfer connections between stops

• Spatial indices for efficient lookups

Example:

model = create_transit_model("path/to/osm.pbf", ["path/to/gtfs"], None, 1800)
transit_point = create_transit_point(lat, lon, model, 1200, 10)

feeds_info()

Get information about the GTFS feeds in the transit model

Returns a summary of the GTFS feeds included in the transit model, such as feed names, versions, and other metadata. The output is formatted as a JSON string, similar to the GTFS feed_info.txt.

Returns:

A JSON string containing information about the GTFS feeds.

Return type:

str

Example

info = model.feeds_info()
print(json.loads(info))
# Example output:
# [
#     {
#         "feed_publisher_name": "City Transit",
#         "feed_publisher_url": "http://citytransit.example.com",
#         "feed_lang": "en",
#         "feed_start_date": "2025-01-01",
#         "feed_end_date": "2025-12-31",
#         "feed_version": "2025.04"
#     }
# ]

route_count()

Get total route count of all feeds in the model

stop_count()

Get total stop count of all feeds in the model

class ferrobus.TransitPoint(lat, lon, transit_model, max_walking_time=1200, max_nearest_stops=10)

A geographic location connected to the transit network with pre-calculated access paths to nearby transit stops and the street network.

TransitPoint serves as the fundamental origin/destination entity for all routing operations. Each point maintains a list of nearby transit stops with walking times, enabling efficient multimodal journey planning without recomputing access paths for every query.

Example

# Create a transit point at specific coordinates
point = ferrobus.create_transit_point(
    lat=52.5200,
    lon=13.4050,
    transit_model=model,
    max_walking_time=900,  # Maximum walking time in seconds
    max_nearest_stops=5    # Maximum number of nearby stops to consider
)

# Use the point for routing
route = ferrobus.find_route(model, stёart_point, end_point, departure_time)

The max_walking_time parameter controls how far the point can connect to the transit network, while max_nearest_stops limits the number of stops considered during routing.

coordinates()

Get the coordinates of this transit point

nearest_stops()

class ferrobus.RangeRoutingResult

as_json()

departure_times()

median_travel_time()

travel_times()

class ferrobus.IsochroneIndex

A spatial index structure for highly efficient isochrone calculations in transit networks.

Traditional isochrone generation involves computationally expensive geometric operations such as buffering network edges and performing unary unions on complex polygons. This approach often becomes prohibitively slow for interactive applications or batch processing multiple isochrones.

IsochroneIndex solves this problem by pre-processing the transit network into a hexagonal grid system (H3 cells) that can be rapidly queried and merged during isochrone generation. This provides orders-of-magnitude performance improvements by avoiding expensive geometric operations at query time.

Rather than working with precise network geometry during isochrone calculations, this index:

1. Discretizes the geographic area into hexagonal cells

2. Pre-computes network connectivity at cell boundaries

3. Enables fast cell-based isochrone expansion

4. Dissolves contiguous cells during final isochrone generation

This approach trades some precision (based on cell resolution) for dramatic performance improvements, making it practical for interactive applications.

Example

index = create_isochrone_index(model, area_wkt, 8, 1200);
isochrone = calculate_isochrone(py, model, point, departure, 3, 1800, index);

# The resulting isochrone is a WKT string representing the polygon
print(isochrone)
>>> MULTIPOLYGON ((...))

References

For more information about the H3 hexagonal grid system used in this module, see the H3 documentation.

is_empty()

Check if the isochrone index is empty

Determines whether the isochrone index contains any cells.

Returns:

True if the index is empty, False otherwise.

Return type:

bool

len()

Get the number of cells in the isochrone index

Returns the total number of hexagonal cells stored in the isochrone index.

Returns:

The number of cells in the index.

Return type:

int

resolution()

Get the resolution of the isochrone index

Returns the resolution of the H3 hexagonal grid used in the isochrone index. Higher resolutions correspond to smaller hexagonal cells.

Returns:

The resolution of the hexagonal grid (0-15).

Return type:

int