Show HN: US Routing – Python library for fast local routing in the United States
US Routing
US Routing is a Python library for fast local routing in the United States. It’s useful when approximations are acceptable. It bootstraps from the North American Roads dataset.
Installation
You can install US Routing using pip:
or using poetry:
git clone https://github.com/ivanbelenky/us-routing.git
cd us-routing
poetry install
Usage
Here’s a quick example of how to use US Routing:
#POINT (-74.0013209995546 40.74648499998924) -> POINT (-74.0054249996425 40.74097199980971) (0.6799999999999999 km) 9TH AV, SP_TH_MA, 72 km/h
#POINT (-74.0054249996425 40.74097199980971) -> POINT (-74.00819599956175 40.74211600011984) (0.27 km) W 14TH ST, SP_TH_MA, 72 km/h
#POINT (-74.00819599956175 40.74211600011984) -> POINT (-74.0090509998795 40.74090099973697) (0.16 km) 10TH AV, SP_TH_MA, 72 km/h
# …]
# Route between zip codes
r = get_route(‘10001’, ‘60007’)
print(r.total_distance, r.duration)
# Output:
# 1315.910000000001 13:20:26.827392
# Route between coordinates, will raise ValueError if closest node in the graph is too far from the location
try:
r = get_route((40.7128, -74.0060), (34.0522, -118.2437), d_threshold=0.00001)
print(r.total_distance, r.duration)
except ValueError as e:
print(e)
# Node 2bd87209-d2fe-4f41-a89f-29104aeb5cf9 is too far from location point=
r = get_route((-74.0060, 40.7128), (-118.2437, 34.0522), d_threshold=10)
# and for sure you can mix stuff up
r = get_route((40.7128, -74.0060), “seattle”, d_threshold=15)
“>
from us_routing import get_route # Route between two cities r = get_route('New York', 'Los Angeles', edge_distance="DURATION") print(r.total_distance, r.duration) # Output in km of course: # 4434.759999999997 1 day, 20:46:24.499959 # Print route steps print(r) # Output: [ #POINT (-73.99811899964011 40.7508730002449) -> POINT (-74.0013209995546 40.74648499998924) (0.5700000000000001 km) 9TH AV, SP_TH_MA, 72 km/h #POINT (-74.0013209995546 40.74648499998924) -> POINT (-74.0054249996425 40.74097199980971) (0.6799999999999999 km) 9TH AV, SP_TH_MA, 72 km/h #POINT (-74.0054249996425 40.74097199980971) -> POINT (-74.00819599956175 40.74211600011984) (0.27 km) W 14TH ST, SP_TH_MA, 72 km/h #POINT (-74.00819599956175 40.74211600011984) -> POINT (-74.0090509998795 40.74090099973697) (0.16 km) 10TH AV, SP_TH_MA, 72 km/h # ...] # Route between zip codes r = get_route('10001', '60007') print(r.total_distance, r.duration) # Output: # 1315.910000000001 13:20:26.827392 # Route between coordinates, will raise ValueError if closest node in the graph is too far from the location try: r = get_route((40.7128, -74.0060), (34.0522, -118.2437), d_threshold=0.00001) print(r.total_distance, r.duration) except ValueError as e: print(e) # Node 2bd87209-d2fe-4f41-a89f-29104aeb5cf9 is too far from location point=zip_code=None admin=None name=None r = get_route((-74.0060, 40.7128), (-118.2437, 34.0522), d_threshold=10) # and for sure you can mix stuff up r = get_route((40.7128, -74.0060), "seattle", d_threshold=15)
Features
- Fast routing between US locations (cities, zip codes, or coordinates)
- Multiple routing options by default (shortest distance, fastest time)
- Detailed route information (distance, duration, states traversed)
Data Source
The routing data is based on the North American Roads dataset. The library includes functionality to download and process this data:
from us_routing import download_north_american_roads download_north_american_roads()
Development
To set up the development environment:
- Clone the repository
- Install Poetry:
pip install poetry - Install dependencies:
poetry install
Custom Routers
This package provides a BaseRouter class that you can use to build your own custom routing graphs. It exposes a very simple API to create routers from shapefiles containing multiple geometries and optional attributes for those geometries. It looks something like this:
geometries: Sequence[LineString | MultiLineString] geometries_data: Optional[Sequence[Dict[str, Any]]] = None # should be serializable # Optional arguments to define how attributes are compared and set to the edges of the graph edge_attr_equal: Optional[Callable[[Any, Any], bool]] = ... edge_attr_setter: Optional[Callable[[Any, Any], dict[str, Any]]] = ... router = BaseRouter.from_geometries(geometries, geometries_data, edge_attr_equal, edge_attr_setter) router.serialize("path_to_save")
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
