ivanbelenky/us-routing: us cached road graph, freeways, primary and secondary roads

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.

You can install US Routing using pip:

or using poetry:

git clone https://github.com/ivanbelenky/us-routing.git
cd us-routing
poetry install

Here’s a quick example of how to use US Routing:

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)

• 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)

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()

To set up the development environment:

1. Clone the repository
2. Install Poetry: pip install poetry
3. Install dependencies: poetry install

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")

Contributions are welcome! Please feel free to submit a Pull Request.

Keep your files stored safely and securely with the SanDisk 2TB Extreme Portable SSD. With over 69,505 ratings and an impressive 4.6 out of 5 stars, this product has been purchased over 8K+ times in the past month. At only $129.99, this Amazon’s Choice product is a must-have for secure file storage.

Help keep private content private with the included password protection featuring 256-bit AES hardware encryption. Order now for just $129.99 on Amazon!

Help Power Techcratic’s Future – Scan To Support

If Techcratic’s content and insights have helped you, consider giving back by supporting the platform with crypto. Every contribution makes a difference, whether it’s for high-quality content, server maintenance, or future updates. Techcratic is constantly evolving, and your support helps drive that progress.

As a solo operator who wears all the hats, creating content, managing the tech, and running the site, your support allows me to stay focused on delivering valuable resources. Your support keeps everything running smoothly and enables me to continue creating the content you love. I’m deeply grateful for your support, it truly means the world to me! Thank you!