Graph utilities¶

Low-level access to Valhalla's tiled, hierarchical graph: tile identifiers, tile-to-coordinate math, and direct edge geometry retrieval via a configured GraphReader.

GraphUtils ¶

GraphUtils(config: Union[Path, str, dict])

Bases: _GraphUtils

Utility class for accessing Valhalla graph data structures.

Provides low-level access to graph tiles and edges using Valhalla's tiled routing data. Supports retrieving edge shapes and other graph properties.

Configuration can be provided as:

Path to a JSON config file
JSON string
Python dict

For dict input, the config is serialized to JSON internally.

Initialize GraphUtils with Valhalla configuration.

PARAMETER	DESCRIPTION
`config`	Valhalla configuration as Path, JSON string, or dict. Must contain valid mjolnir.tile_extract or mjolnir.tile_dir. TYPE: `Union[Path, str, dict]`

RAISES	DESCRIPTION
`RuntimeError`	When config is invalid or cannot be parsed
`TypeError`	When config is not Path, str, or dict
`AttributeError`	When config is missing required mjolnir settings
`FileNotFoundError`	When config file or tile data doesn't exist

get_edge_shape ¶

get_edge_shape(edge_id: GraphId) -> list[tuple[float, float]]

Get the shape (polyline) for an edge as a list of (lon, lat) tuples.

PARAMETER	DESCRIPTION
`edge_id`	GraphId of the edge TYPE: `GraphId`

RETURNS	DESCRIPTION
`list[tuple[float, float]]`	List of (lon, lat) tuples representing the edge geometry

RAISES	DESCRIPTION
`RuntimeError`	When the tile or edge is not found

GraphId `module-attribute` ¶

GraphId = GraphId

get_tile_base_lon_lat ¶

get_tile_base_lon_lat(graph_id: GraphId) -> tuple

Get the geographic coordinate of the south-western corner of this graph_id's tile.

PARAMETER	DESCRIPTION
`graph_id`	The tile's or object's GraphId TYPE: `GraphId`

RETURNS	DESCRIPTION
`tuple`	The lon/lat coordinate of the SW corner of the tile

get_tile_id_from_lon_lat ¶

get_tile_id_from_lon_lat(level: int, coord: tuple) -> GraphId

Get the tile at this hierarchy level and geographic coordinate.

PARAMETER	DESCRIPTION
`level`	The hierarchy level of the searched tiles. TYPE: `int`
`coord`	The geographic coordinate to intersect with tiles. TYPE: `tuple`

RETURNS	DESCRIPTION
`GraphId`	GraphId of found tile.

RAISES	DESCRIPTION
`ValueError`	When the level or coord are invalid.

get_tile_ids_from_bbox ¶

get_tile_ids_from_bbox(minx: float, miny: float, maxx: float, maxy: float, levels: Sequence[int] = []) -> list[GraphId]

Returns all tiles GraphIds for the specified levels (default: all), which intersect the bbox.

PARAMETER	DESCRIPTION
`minx`	The bbox's minimum longitude. TYPE: `float`
`miny`	The bbox's minimum latitude. TYPE: `float`
`maxx`	The bbox's maximum longitude. TYPE: `float`
`maxy`	The bbox's maximum latitude. TYPE: `float`
`levels`	The hierarchy levels for which to find tiles. TYPE: `Sequence[int]` DEFAULT: `[]`

RETURNS	DESCRIPTION
`list[GraphId]`	The list of tile GraphIds which intersect the bounding box

RAISES	DESCRIPTION
`ValueError`	When the level(s) or coord are invalid.

get_tile_ids_from_ring ¶

get_tile_ids_from_ring(ring_coords: Sequence[tuple], levels: Sequence[int] = []) -> list[GraphId]

Returns all tile GraphIds for the specified levels (default: all), which intersect or are contained within the polygon ring. The ring is assumed and coerced to be an outer ring. It's automatically closed if the last coordinate does not match the first.

PARAMETER	DESCRIPTION
`ring_coords`	List of (lon, lat) tuples forming a closed ring (polygon boundary). Must have at least 3 coordinates. TYPE: `Sequence[tuple]`
`levels`	The hierarchy levels for which to find tiles. TYPE: `Sequence[int]` DEFAULT: `[]`

RETURNS	DESCRIPTION
`list[GraphId]`	The list of tile GraphIds which intersect or are inside the ring.

RAISES	DESCRIPTION
`ValueError`	When the level(s), coords, or ring size are invalid.