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 OSRMRouter
import pandas as pd
data = 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()

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.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 seconds
print("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.