Travecto

Optimizes travel routes using Google Maps Geocoding API and the traveling salesman problem solver from OR-Tools.

⚙️ Features

• Solves the traveling salesman problem for optimal route planning.
• Geocodes place names using Google Maps API with intelligent fallback strategies.
• Caches geocoding results to minimize API calls.
• Supports mandatory locations per day with automatic clustering.
• Calculates realistic travel times based on mixed Metro and walking transportation.
• Generates interactive route maps with satellite and street view options.
• Handles Unicode normalization for international place names.
• Configurable rate limiting with exponential backoff retry logic.
• TOML-based configuration for easy customization.

⚠️ Disclaimers

• Google API Key Required: This tool requires a valid Google Maps Geocoding API key. Pricing applies based on usage (Google offers 10,000 requests per month free).
• Transportation Model: Travel time calculations assume a mixed Metro/walking model optimized for the Paris Metro system. Accuracy may vary for other transportation systems.
• Rate Limiting: Default rate limit is set to 50 QPS to stay within Google API limits. Adjust based on your API quota.
• Licensing Restrictions: Google's terms are notably restrictive. Geocoding results cannot be stored permanently outside of Google's services. You may cache results for up to 30 days for performance, but permanent storage is only allowed if data is displayed on a Google map and used within Google's ecosystem, which is not the case for Travecto as it uses Folium, which uses Leaflet for displaying maps.

🚀 Installation

With PyPI

pip install travecto

With pipx

pipx install travecto

With Conda

conda create -n travecto python=3.9 -y # up to 3.13
conda activate travecto
pip install travecto

From Source

git clone https://github.com/Inc44/Travecto.git
cd Travecto

To install the package:

pip install .

To install only the dependencies:

pip install -r requirements.txt

If you install only the dependencies, run the program using python -m travecto.cli (or python -OO travecto/cli.py) instead of the travecto command.

🛠️ Build from Source

pip install build
python -m build

📦 Publish

pip install twine
twine upload dist/*

🧾 Configuration

Set environment variable:

setx /M GOOGLE_MAPS_API_KEY your_api_key
setx /M THUNDERFOREST_API_KEY your_api_key

For Linux/macOS:

echo 'export GOOGLE_MAPS_API_KEY="your_api_key"' >> ~/.bashrc # or ~/.zshrc
echo 'export THUNDERFOREST_API_KEY="your_api_key"' >> ~/.bashrc # or ~/.zshrc

Or create a .env file or modify /etc/environment:

GOOGLE_MAPS_API_KEY=your_api_key
THUNDERFOREST_API_KEY=your_api_key

Check by restarting the terminal and using:

echo %GOOGLE_MAPS_API_KEY%
echo %THUNDERFOREST_API_KEY%

For Linux/macOS:

echo $GOOGLE_MAPS_API_KEY
echo $THUNDERFOREST_API_KEY

📖 Usage Examples

Basic Route Planning

Calculate optimal routes for all configured cities:

python -m travecto

Same but loading .env file:

python -m dotenv -f /path/to/.env run -- travecto

Generate Interactive Maps

Create HTML maps showing optimized routes:

python -m travecto --maps

Custom Configuration

Use custom configuration file:

python -m travecto --input config.toml

Custom Output Directory

Save maps to specific directory:

python -m travecto --maps --output html

🎨 Command-Line Arguments

Argument	Description
-i, --input <path>	Path to the TOML configuration file. Default: demo.toml.
-o, --output <path>	Directory for map files. Default: routes.
--maps	Generate interactive HTML maps for visualization.
--workers <n>	Number of OR-Tools search workers. Default: 32.
--loglevel <level>	Set logging level (NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: ERROR.

🎯 Motivation

Planning efficient tourist routes in large cities like Paris requires solving complex optimization problems. Traditional route planners fail to optimize across multiple locations or lack the flexibility for mandatory stops. Google Maps supports a maximum of 10 destinations and MapQuest supports a maximum of 26 addresses. So in the summer of 2025, as I had a need for about 80 stops, I decided to create this tool to solve multi-day touring itineraries using proven algorithms while maintaining practical transportation models for European cities.

🐛 Bugs

Not yet found.

⛔ Known Limitations

• Geocoding heavily depends on Google Maps API quality and may fail for very obscure locations; therefore, adding a postal code at the end of the destination name or defining renaming patterns is recommended.
• The transportation model assumes a uniform Metro/walking mix, which may not reflect actual city-specific conditions.
• OR-Tools TSP solver may not find globally optimal solutions for very large datasets within time limits.
• If you don't like the current selection of tile providers for Map, Satellite, and Transport, or they don't work for your region, modify the code by replacing them with others available at: Leaflet Provider Demo.
• Serving pre-compressed .br, .zstd, .gz, and .deflate files on an Apache server is not possible because the Cloudflare proxy dynamically recompresses responses when Automatic HTTPS Rewrites are used.

🚧 TODO

• Original-Order Mode (No Optimization).
• Minimize-Time Mode: Use minutes instead of km.
• Per-Mode Speeds.
• Real-Time Transit Integration.
• Mixed Transportation Modes.
• Periodic Stops: Restaurant and home stops.
• Target Time: Opening, closing, and visit windows.
• Multi-Objective Optimization: Enable optimization for factors beyond distance, such as opening hours, crowd levels, and personal preferences.
• routing_parameters_pb.jl: Explore the configuration available for search_params.
• More Maps: Topology, cycling, and dark mode versions.
• Security, Abuse Prevention, Quota Handling.
• Hide Internal Functions: __all__ or underscore prefix.
• Tests.

🙏 Thanks

Creators of:

• Python
• Google Maps Platform
• OR-Tools
• aiohttp
• Folium
• Tenacity

🤝 Contribution

Contributions, suggestions, and new ideas are heartily welcomed. If you're considering significant modifications, please initiate an issue for discussion before submitting a pull request.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

💖 Support