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/testgeorouting.py::testosrm_router -v

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

googlekey=YOURGOOGLEAPIKEY
bingkey=YOURBINGAPIKEY
esrikey=YOURESRIAPIKEY

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

Usage

# how to get routing distance matrix from OSRMRouter
import pandas as pd
data = pd.readcsv("https://raw.githubusercontent.com/wybert/georouting/main/docs/data/sample3.csv",index_col=0)
oneodpair = data.iloc[2]
data.head()
from georouting.routers import GoogleRouter 
create a router object with the google_key
 router = 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 API
 route = router.getroute([oneodpair["ZIPlat"],oneodpair["ZIP_lon"]],                            [oneodpair["AHAIDlat"],oneodpair["AHAIDlon"]]) 
Now you can get the distance and duration of the route in meters and seconds
 print("Distance: {} meters".format(route.get_distance())) print("Duration: {} seconds".format(route.get_duration()))

df= route.getroutegeopandas() 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{fugeorouting2023,
  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)

To regenerate after documentation changes:

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

Generate API Documentation and Convert Notebooks

Use the generateapidocs.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 generateapidocs.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.