Viera Christmas Lights Route Optimizer

Build a fastest-first driving route for holiday light stops in Viera, Florida using OSRM travel-time matrices and Google OR-Tools.

Overview

Viera Christmas Lights Route Optimizer is a Python command-line tool for turning a list of holiday light addresses into a driveable, optimized route. It reads stops from addresses.json, adds your home location from .env, requests travel-time and distance matrices from the OSRM API, solves the route order with OR-Tools, and writes frontend-ready navigation data to navigation_route.json.

The optimizer is duration-based, so it prioritizes the fastest route rather than the shortest mileage.

Features

• Fastest-route optimization for a list of geocoded addresses
• Home starting point loaded from environment variables
• OSRM matrix lookup for real road travel durations and distances
• OR-Tools Traveling Salesman Problem solver
• Full OSRM route geometry in GeoJSON format
• Turn-by-turn leg data for map or navigation frontends
• Local JSON outputs for debugging, reuse, and visualization

Tech Stack

Tool	Purpose
Python	Command-line runtime
OSRM	Road-network travel times, distances, geometry, and steps
Google OR-Tools	Route order optimization
python-dotenv	Local environment configuration
requests	OSRM API calls

Repository Structure

.
|-- assets/
|   `-- logo.svg
|-- main.py
|-- requirements.txt
|-- LICENSE
`-- README.md

Generated local files are not included in the repository:

addresses.json
.env
matrices.json
navigation_route.json

Getting Started

Prerequisites

• Python 3.8 or newer
• Internet access for OSRM API requests
• Geocoded stop data with latitude and longitude values

Installation

Clone the repository:

git clone https://github.com/connorcarro/viera-christmas-lights.git
cd viera-christmas-lights

Create and activate a virtual environment:

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

macOS and Linux:

source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Configuration

Create a .env file in the project root with your starting coordinates:

HOME_LAT=28.266628
HOME_LON=-80.729056

Create an addresses.json file in the project root. Each stop must include an address label, latitude, and longitude:

[
  {
    "address": "123 Example St, Viera, FL",
    "lat": 28.266629,
    "lon": -80.729057
  },
  {
    "address": "456 Holiday Ave, Viera, FL",
    "lat": 28.266630,
    "lon": -80.729058
  }
]

The script automatically inserts your home location as stop 0, so addresses.json should only contain the light-viewing stops.

Usage

Run the optimizer:

python main.py

During execution, the script will:

1. Load home coordinates from .env
2. Load holiday light stops from addresses.json
3. Request OSRM duration and distance matrices
4. Save matrix data to matrices.json
5. Solve the fastest route with OR-Tools
6. Request the final driveable route from OSRM
7. Save navigation data to navigation_route.json

Outputs

matrices.json

Stores the raw OSRM duration and distance matrices. This is useful for debugging, auditing travel-time data, or reusing matrix results during development.

navigation_route.json

Contains the optimized route payload for a frontend map or navigation experience:

{
  "metadata": {
    "cost_type": "DURATION",
    "total_stops": 3,
    "total_distance_meters": 12345.6,
    "total_duration_seconds": 1800.5
  },
  "waypoints": [],
  "route_geometry": {},
  "turn_by_turn_directions": [],
  "summary": {}
}

Data Privacy

The files below may contain private location data and should stay local:

• .env
• addresses.json
• matrices.json
• navigation_route.json

Review your git status before committing to make sure no private route or home-location data is staged.

Troubleshooting

Problem	What to check
Unexpected Error when loading coordinates	Confirm HOME_LAT and HOME_LON exist in .env and are valid numbers.
OSRM timeout or connection error	Check your internet connection and retry. The public OSRM demo server can be temporarily unavailable.
OSRM reports invalid input	Confirm every address object has valid lat and lon values.
Route contains unreachable pairs	Verify coordinates are driveable road locations and not points inside restricted areas, water, or private paths.
Output file is missing	Confirm the script completed successfully and that Python has permission to write in the repository folder.

Limitations

• The project uses the public OSRM demo server, which is best for development and light usage.
• Addresses must already be geocoded. This tool does not convert street addresses into coordinates.
• Optimization starts from home and returns through the generated route order used by OSRM.
• Route quality depends on OSRM coverage and the accuracy of the supplied coordinates.

Contributing

Issues and pull requests are welcome. For changes that affect routing behavior, include a short explanation of the scenario tested and whether the expected route output changed.

License

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