AI-Friendly Geo routing for Python users, supporting most of the routing tools, including OSRM, Google Maps, Bing Maps, etc. with a unified API.

This package is inspired by geopy. Please help to improve this package by submitting issues and pull requests.

• Free software: MIT license
• Documentation: https://wybert.github.io/georouting

Features

• Support most of the routing services, including Google Maps, Bing Maps, OSRM, etc.
• Provide a unified API for routing services
• Support calculating the travel distance matrix between multiple origins and destinations
• Support calculating the travel distance according to OD pairs.
• Easy to visualize the routing results
• Return the travel distance matrix in a Pandas Dataframe you like
• Return the routing results in a Geopandas GeoDataFrame
• Easy to extend to support more routing services
• AI-friendly documentation with LLMs.txt support

Installation

Using pip

To install georouting, run this command in your terminal:

pip install georouting

or install from GitHub source

pip install git+https://github.com/wybert/georouting.git

If you don't have pip installed, this Python installation guide can guide you through the process.

Using conda

conda install -c conda-forge georouting

or use mamba

mamba install -c conda-forge georouting

Install from sources

The sources for georouting can be downloaded from the Github repo.

You can clone the public repository:

git clone git://github.com/wybert/georouting

Then install it with:

python setup.py install

Running Tests

# Install dev dependencies
pip install -r requirements_dev.txt
# Run all tests
python -m pytest tests/
# Run tests with verbose output
python -m pytest tests/ -v
# Run a specific test
python -m pytest tests/test_georouting.py::test_osrm_router -v

Note: Some tests require API keys. Create a .env file with:

google_key=YOUR_GOOGLE_API_KEY
bing_key=YOUR_BING_API_KEY
esri_key=YOUR_ESRI_API_KEY

The OSRM router tests work without API keys (uses public OSRM server).

Usage

# how to get routing distance matrix from OSRMRouterimportpandasaspddata=pd.read_csv("https://raw.githubusercontent.com/wybert/georouting/main/docs/data/sample_3.csv",index_col=0)
one_od_pair=data.iloc[2]
data.head()
fromgeorouting.routersimportGoogleRouter# create a router object with the google_keyrouter=GoogleRouter(google_key,mode="driving")
# get the route between the origin and destination, this will return a Route object# this will call the Google Maps APIroute=router.get_route([one_od_pair["ZIP_lat"],one_od_pair["ZIP_lon"]],
[one_od_pair["AHA_ID_lat"],one_od_pair["AHA_ID_lon"]])
# Now you can get the distance and duration of the route in meters and secondsprint("Distance: {} meters".format(route.get_distance()))
print("Duration: {} seconds".format(route.get_duration()))
df=route.get_route_geopandas()
df.head()
df.explore(column="speed (m/s)",style_kwds={"weight":11,"opacity":0.8})

TODO

• add extract graph data from osm data, easy way

How to cite

If you use georouting in your research, please consider citing it:

Fu, X. (2023). georouting: AI-friendly geo routing for Python users. Retrieved from https://github.com/wybert/georouting

BibTeX:

@misc{fu_georouting_2023,
author = {Xiaokang Fu},
title = {georouting: AI-friendly geo routing for Python users},
year = {2023},
version = {0.0.8},
howpublished = {\url{https://github.com/wybert/georouting}},
note = {GitHub repository}
}

Once the JOSS paper for georouting is published and assigned a DOI, please cite the JOSS article instead.

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting a pull request.

Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

Documentation Generation

LLMs.txt Files

Georouting provides AI-friendly documentation files following the llms.txt standard. These help AI assistants (Claude, ChatGPT, Cursor, Windsurf) better understand and work with georouting.

• llms.txt - Concise overview (~2KB)
• llms-full.txt - Complete documentation (~55KB)

See the LLMs.txt documentation for usage instructions with various AI tools.

To regenerate after documentation changes:

# Generate the full documentation file by combining all markdown docs
python generate_llms_full.py

Generate API Documentation and Convert Notebooks

Use the generate_api_docs.py script to generate API documentation from source code and convert Jupyter notebooks:

# Install dependencies
pip install pydoc-markdown jupyter nbconvert
# Generate all documentation
python generate_api_docs.py

This script:

• Generates markdown API docs from Python docstrings using pydoc-markdown
• Converts Jupyter notebooks to markdown
• Removes interactive widget divs (folium maps) while keeping tables

Credits

This package was created with Cookiecutter and the giswqs/pypackage project template.