georouting

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 112 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![georouting](https://raw.githubusercontent.com/wybert/georouting/main/docs/img/georouting.png)

[![image](https://img.shields.io/pypi/v/georouting.svg)](https://pypi.python.org/pypi/georouting)
[![image](https://img.shields.io/conda/vn/conda-forge/georouting.svg)](https://anaconda.org/conda-forge/georouting)
[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/wybert/georouting/blob/main/docs/usage.ipynb)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![image](https://github.com/wybert/georouting/workflows/docs/badge.svg)](https://wybert.github.io/georouting/)
[![image](https://github.com/wybert/georouting/workflows/build/badge.svg)](https://github.com/wybert/georouting/actions?query=workflow%3Abuild)
[![image](https://img.shields.io/twitter/follow/fxk123?style=social)](https://twitter.com/fxk123)
[![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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](https://geopy.readthedocs.io/en/stable/). Please help to improve this package by submitting issues and pull requests.

-   Free software: MIT license
-   Documentation: [https://wybert.github.io/georouting](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](https://wybert.github.io/georouting/llms-txt/) support

## Installation

### Using pip

To install georouting, run this command in your terminal:

```bash
pip install georouting
```

or install from GitHub source

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

If you don't have [pip](https://pip.pypa.io) installed, this [Python installation guide](http://docs.python-guide.org/en/latest/starting/installation/) 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

```bash
# 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

```python

# 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:

```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](docs/contributing.md) before submitting a pull request.

Please note that this project is released with a [Code of Conduct](CODE_OF_CONDUCT.MD). 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](https://llmstxt.org/). These help AI assistants (Claude, ChatGPT, Cursor, Windsurf) better understand and work with georouting.

- **[llms.txt](https://wybert.github.io/georouting/llms.txt)** - Concise overview (~2KB)
- **[llms-full.txt](https://wybert.github.io/georouting/llms-full.txt)** - Complete documentation (~55KB)

See the [LLMs.txt documentation](https://wybert.github.io/georouting/llms-txt/) for usage instructions with various AI tools.

To regenerate after documentation changes:

```bash
# 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:

```bash
# 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](https://github.com/cookiecutter/cookiecutter) and the [giswqs/pypackage](https://github.com/giswqs/pypackage) project template.

georouting

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README