GitHub | Documentation | Issue Tracker | PyPI

Python bindings for routx - library for simple routing over OpenStreetMap data.

Routx converts OSM data into a standard weighted directed graph representation, and runs A* to find shortest paths between nodes. Interpretation of OSM data is customizable via profiles. Routx supports one-way streets, access tags (on ways only) and turn restrictions.

pip install routx in a virtual environment.

Precompiled wheels are available for most popular platforms (aarch64, x86-64 × GNU Linux, MacOS and Windows). On anything else, cargo (please don't curl | sh and install from your system's package manager), ninja and C/C++ compiler toolchain are required to properly compile the library.

Of note is the lack of support for musl-based Linux systems, due to lacking Rust support.

import routx

g = routx.Graph()
g.add_from_osm_file("path/to/monaco.pbf", routx.OsmProfile.CAR)

start_node = g.find_nearest_node(43.7384, 7.4246)
end_node = g.find_nearest_node(43.7478, 7.4323)
route = g.find_route(start_node.id, end_node.id)

for node_id in route:
    node = g[node_id]
    print(node.lat, node.lon)

Unless noted otherwise, __init__ methods behave as expected for standard NamedTuple/dataclass/IntEnum objects.

DEFAULT_STEP_LIMIT: Final[int] = 1000000

Recommended A* step limit for routx.Graph.find_route.

class Node(NamedTuple):
    id: int
    osm_id: int
    lat: float
    lon: float

An element of a Graph. A named tuple.

Due to turn restriction processing, one OpenStreetMap node may be represented by multiple nodes in the graph. If that is the case, a "canonical" node (not bound by any turn restriction) will have id == osm_id.

Nodes with id == 0 are used by the underlying library to signify the absence of a node, are considered false-y and must not be used by consumers.

Methods:

• __bool__(self) -> bool - True if id is not zero.

Read-only properties:

• is_canonical: bool - True if id == osm_id.

class Edge(NamedTuple):
    to: int
    cost: float

Outgoing (one-way) connection from a Node. A named tuple.

cost must be greater than the crow-flies distance between the two nodes.

class Graph(MutableMapping[int, Node]):
    pass  # no attributes, constructor accepts no arguments

OpenStreetMap-based network representation as a set of nodes and edges between them.

Node access is implemented through the standard MutableMapping interface from ids (integers) to nodes.

Note that overwriting existing nodes preserves all outgoing and incoming edges. Thus updating a node position might result in violation of the Edge invariant and break route finding. It is discouraged to update nodes, and it is the caller's responsibility not to break this invariant.

Methods (other than the implemented for and inherited from MutableMapping[int, Node]):

• find_nearest_node(lat: float, lon: float) -> Node - find the closest canonical (id == osm_id) Node to the given position.

  This function requires computing distance to every Node in the graph and is not suitable for large graphs or for multiple searches. Use KDTree for faster NN finding.

  If the graph is empty, raises KeyError.

• get_edges(self, from_: int) -> list[Edge] - gets all outgoing edges from a node with a given id.

• get_edge(self, from_: int, to: int) -> float - gets the cost of traversing an edge between nodes with provided ids. Returns positive infinity when the provided edge does not exist.

• set_edge(self, from_: int, to: int, cost: float) -> bool - creates or updates an Edge from one node to another.

  The cost must not be smaller than the crow-flies distance between nodes, as this would violate the A* invariant and break route finding. It is the caller's responsibility to uphold this invariant.

  Returns True if an existing edge was overwritten, False otherwise.

  Note that given an Edge object, this method may be called with graph.set_edge(from_, *edge).

• delete_edge(self, from_: int, to: int, /, missing_ok: bool = True) -> None - ensures an Edge from one node to another does not exist. If no such edge exists and missing_ok is set to False, raises KeyError.

•   find_route(
        self,
        from_: int,
        to: int,
        /,
        without_turn_around: bool = True,
        step_limit: int = DEFAULT_STEP_LIMIT,
    ) -> list[int]
  

  Finds the cheapest way between two nodes using the A* algorithm. Returns a list node IDs of such route. The list may be empty if no route exists.

  from_id must identify a specific node in the graph, and to_id must identify a specific canonical (id == osm_id) node; otherwise KeyError is raised.

  without_turn_around defaults to True and prevents the algorithm from circumventing turn restrictions by suppressing unrealistic turn-around instructions (A-B-A). This introduces an extra dimension to the search space, so if the graph doesn't contain any turn restriction, this parameter should be set to False.

  step_limit limits how many nodes can be expanded during search before raising StepLimitExceeded. Concluding that no route exists requires expanding all nodes accessible from the start, which is usually very time consuming, especially on large datasets.

•   add_from_osm_file(
        self,
        filename: str | bytes | PathLike[str] | PathLike[bytes],
        profile: OsmProfile | OsmCustomProfile,
        /,
        format: OsmFormat = OsmFormat.UNKNOWN,
        bbox: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
    ) -> None
  

  Parses OSM data from the provided file and adds them to this graph.

  profile describes how the OSM data should be interpreted.

  format describes the file format of the input OSM data. Defaults to auto-detection.

  bbox filters features by a specific bounding box, in order: left (min lon), bottom (min lat), right (max lon), top (max lat). Ignored if all values are zero (default).

•   add_from_osm_memory(
        self,
        mv: memoryview,
        profile: OsmProfile | OsmCustomProfile,
        /,
        format: OsmFormat = OsmFormat.UNKNOWN,
        bbox: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
    ) -> None
  

  Parses OSM data from the provided contents of a memory file. The buffer must be contiguous and also mutable (for reasons only known to ctypes, because the underlying library takes a const pointer).

  profile describes how the OSM data should be interpreted.

  format describes the file format of the input OSM data. Defaults to auto-detection.

  bbox filters features by a specific bounding box, in order: left (min lon), bottom (min lat), right (max lon), top (max lat). Ignored if all values are zero (default).

class KDTree:
    pass # no attributes, private constructor

Methods:

• find_nearest_node(self, lat: float, lon: float) -> Node - finds the closest node to the provided position and returns its id. Raises KeyError when the k-d tree contains no nodes.

Class Methods:

• KDTree.build(graph: Graph) -> Self - builds a k-d tree with all canonical (id == osm_id) nodes contained in the provided graph.

class OsmProfile(IntEnum):
    CAR = 1
    BUS = 2
    BICYCLE = 3
    FOOT = 4
    RAILWAY = 5
    TRAM = 6
    SUBWAY = 7

Predefined OSM conversion profiles. An IntEnum.

class OsmFormat(IntEnum):
    UNKNOWN = 0
    XML = 1
    XML_GZ = 2
    XML_BZ2 = 3
    PBF = 4

Format of the input OSM file. An IntEnum.

Values:

• UNKNOWN - unknown format - guess based on content.
• XML - force uncompressed OSM XML.
• XML_GZ - force OSM XML with gzip compression.
• XML_BZ2 - force OSM XML with bzip2 compression.
• PBF - force OSM PBF.

class OsmPenalty(NamedTuple):
    key: str
    value: str
    penalty: float

Numeric multiplier for OSM ways with specific keys and values. A named tuple.

Attributes:

• key: str - key of an OSM way for which this penalty applies, used for value comparison (e.g. "highway" or "railway").
• value: str - value under key of an OSM way for which this penalty applies.E.g. "motorway", "residential", or "rail".
• penalty: float - multiplier of the length, to express preference for a specific way. Must be not less than one and be finite.

@dataclass
class OsmCustomProfile:
    name: str
    penalties: list[OsmPenalty]
    access: list[str]
    disallow_motorroad: bool = False
    disable_restrictions: bool = False

Describes how to convert OSM data into a Graph. A dataclass.

If possible, usage of pre-defined OsmProfiles should be preferred. Using custom profile involves reallocation of all arrays and strings two times to match ABIs (first from Python to C, then from C to Rust). This is only a constant cost incurred on call to Graph.add_from_file or Graph.add_from_memory.

Attributes:

• name: str - human readable name of the routing profile, customary the most specific access tag.

  This value is not used for actual OSM data interpretation, except when set to "foot", which adds the following logic:

  • oneway tags are ignored - only oneway:foot tags are considered, except on:
    • highway=footway,
    • highway=path,
    • highway=steps,
    • highway=platform
    • public_transport=platform,
    • railway=platform;
  • only restriction:foot turn restrictions are considered.

• penalties: list[OsmPenalty] - tags of OSM ways which can be used for routing.

  A way is matched against all OsmPenalty objects in order, and once an exact key and value match is found; the way is used for routing, and each connection between two nodes gets a resulting cost equal to the distance between nodes multiplied the penalty.

  All penalties must be normal and not less than zero.

  For example, if there are two penalties:

  1. highway=motorway, penalty=1
  2. highway=trunk, penalty=1.5

  This will result in:

  • a highway=motorway stretch of 100 meters will be used for routing with a cost of 100.
  • a highway=trunk motorway of 100 meters will be used for routing with a cost of 150.
  • a highway=motorway_link or highway=primary won't be used for routing, as they do not any penalty.

• access: list[str] - list of OSM access tags (in order from least to most specific) to consider when checking for road prohibitions.

  This list is used mainly to follow the access tags, but also to follow mode-specific one-way and turn restrictions.

• disallow_motorroad: bool - force no routing over motorroad=yes ways.

• disable_restrictions: bool - force ignoring of turn restrictions.

class OsmLoadingError(ValueError):
    pass  # attributes and constructor the same as for ValueError

Raised with the underlying library has failed to load OSM data data. See logs for details.

class StepLimitExceeded(ValueError):
    pass  # attributes and constructor the same as for ValueError

Raised when Graph.find_route exceeded its step limit.

def earth_distance(
    lat1: float,
    lon1: float,
    lat2: float,
    lon2: float,
) -> float:

Calculates the great-circle distance between two positions using the haversine formula.

Returns the result in kilometers.

routx and routx-python are made available under the MIT license.