# OSM Road Trip Service Documentation

## Overview

The OSM Road Trip Service provides comprehensive road trip planning functionality for theme parks using free OpenStreetMap APIs. It enables users to plan routes between parks, find parks along routes, and optimize multi-park trips.

## Features Implemented

### 1. Core Service Architecture

**Location**: [`parks/services/roadtrip.py`](../../parks/services/roadtrip.py)

The service is built around the `RoadTripService` class which provides all road trip planning functionality with proper error handling, caching, and rate limiting.

### 2. Geocoding Service

Uses **Nominatim** (OpenStreetMap's geocoding service) to convert addresses to coordinates:

```python
from parks.services import RoadTripService

service = RoadTripService()
coords = service.geocode_address("Cedar Point, Sandusky, Ohio")
# Returns: Coordinates(latitude=41.4826, longitude=-82.6862)
```

**Features**:
- Converts any address string to latitude/longitude coordinates
- Automatic caching of geocoding results (24-hour cache)
- Proper error handling for invalid addresses
- Rate limiting (1 request per second)

### 3. Route Calculation

Uses **OSRM** (Open Source Routing Machine) for route calculation with fallback to straight-line distance:

```python
from parks.services.roadtrip import Coordinates

start = Coordinates(41.4826, -82.6862)  # Cedar Point
end = Coordinates(28.4177, -81.5812)    # Magic Kingdom

route = service.calculate_route(start, end)
# Returns: RouteInfo(distance_km=1745.7, duration_minutes=1244, geometry="encoded_polyline")
```

**Features**:
- Real driving routes with distance and time estimates
- Encoded polyline geometry for route visualization
- Fallback to straight-line distance when routing fails
- Route caching (6-hour cache)
- Graceful error handling

### 4. Park Integration

Seamlessly integrates with existing [`Park`](../../parks/models/parks.py) and [`ParkLocation`](../../parks/models/location.py) models:

```python
# Geocode parks that don't have coordinates
park = Park.objects.get(name="Some Park")
success = service.geocode_park_if_needed(park)

# Get park coordinates
coords = park.coordinates  # Returns (lat, lon) tuple or None
```

**Features**:
- Automatic geocoding for parks without coordinates
- Uses existing PostGIS PointField infrastructure
- Respects existing location data structure

### 5. Route Discovery

Find parks along a specific route within a detour distance:

```python
start_park = Park.objects.get(name="Cedar Point")
end_park = Park.objects.get(name="Magic Kingdom")

parks_along_route = service.find_parks_along_route(
    start_park, 
    end_park, 
    max_detour_km=50
)
```

**Features**:
- Finds parks within specified detour distance
- Calculates actual detour cost (not just proximity)
- Uses PostGIS spatial queries for efficiency

### 6. Nearby Park Discovery

Find all parks within a radius of a center park:

```python
center_park = Park.objects.get(name="Disney World")
nearby_parks = service.get_park_distances(center_park, radius_km=100)

# Returns list of dicts with park, distance, and duration info
for result in nearby_parks:
    print(f"{result['park'].name}: {result['formatted_distance']}")
```

**Features**:
- Finds parks within specified radius
- Returns actual driving distances and times
- Sorted by distance
- Formatted output for easy display

### 7. Multi-Park Trip Planning

Plan optimized routes for visiting multiple parks:

```python
parks_to_visit = [park1, park2, park3, park4]
trip = service.create_multi_park_trip(parks_to_visit)

print(f"Total Distance: {trip.formatted_total_distance}")
print(f"Total Duration: {trip.formatted_total_duration}")

for leg in trip.legs:
    print(f"{leg.from_park.name} → {leg.to_park.name}: {leg.route.formatted_distance}")
```

**Features**:
- Optimizes route order using traveling salesman heuristics
- Exhaustive search for small groups (≤6 parks)
- Nearest neighbor heuristic for larger groups
- Returns detailed leg-by-leg information
- Total trip statistics

## API Configuration

### Django Settings

Added to [`thrillwiki/settings.py`](../../thrillwiki/settings.py):

```python
# Road Trip Service Settings
ROADTRIP_CACHE_TIMEOUT = 3600 * 24  # 24 hours for geocoding
ROADTRIP_ROUTE_CACHE_TIMEOUT = 3600 * 6  # 6 hours for routes
ROADTRIP_MAX_REQUESTS_PER_SECOND = 1  # Respect OSM rate limits
ROADTRIP_USER_AGENT = "ThrillWiki Road Trip Planner (https://thrillwiki.com)"
ROADTRIP_REQUEST_TIMEOUT = 10  # seconds
ROADTRIP_MAX_RETRIES = 3
ROADTRIP_BACKOFF_FACTOR = 2
```

### External APIs Used

1. **Nominatim Geocoding**: `https://nominatim.openstreetmap.org/search`
   - Free OpenStreetMap geocoding service
   - Rate limit: 1 request per second
   - Returns JSON with lat/lon coordinates

2. **OSRM Routing**: `http://router.project-osrm.org/route/v1/driving/`
   - Free routing service for driving directions
   - Returns distance, duration, and route geometry
   - Fallback to straight-line distance if unavailable

## Data Models

### Core Data Classes

```python
@dataclass
class Coordinates:
    latitude: float
    longitude: float

@dataclass
class RouteInfo:
    distance_km: float
    duration_minutes: int
    geometry: Optional[str] = None  # Encoded polyline

@dataclass
class RoadTrip:
    parks: List[Park]
    legs: List[TripLeg]
    total_distance_km: float
    total_duration_minutes: int
```

### Integration Points

- **Park Model**: Access via `park.coordinates` property
- **ParkLocation Model**: Uses `point` PointField for spatial data
- **Django Cache**: Automatic caching of API results
- **PostGIS**: Spatial queries for nearby park discovery

## Performance & Caching

### Caching Strategy

1. **Geocoding Results**: 24-hour cache
   - Cache key: `roadtrip:geocode:{hash(address)}`
   - Reduces redundant API calls for same addresses

2. **Route Calculations**: 6-hour cache
   - Cache key: `roadtrip:route:{start_coords}:{end_coords}`
   - Balances freshness with API efficiency

### Rate Limiting

- **1 request per second** to respect OSM usage policies
- Automatic rate limiting between API calls
- Exponential backoff for failed requests
- User-Agent identification as required by OSM

## Error Handling

### Graceful Degradation

1. **Network Issues**: Retry with exponential backoff
2. **Invalid Coordinates**: Fall back to straight-line distance
3. **Geocoding Failures**: Return None, don't crash
4. **Missing Location Data**: Skip parks without coordinates
5. **API Rate Limits**: Automatic waiting and retry

### Logging

Comprehensive logging for debugging and monitoring:
- Successful geocoding/routing operations
- API failures and retry attempts
- Cache hits and misses
- Rate limiting activation

## Testing

### Test Suite

**Location**: [`test_roadtrip_service.py`](../../test_roadtrip_service.py)

Comprehensive test suite covering:
- Geocoding functionality
- Route calculation
- Park integration
- Multi-park trip planning
- Error handling
- Rate limiting
- Cache functionality

### Test Results Summary

- ✅ **Geocoding**: Successfully geocodes theme park addresses
- ✅ **Routing**: Calculates accurate routes with OSRM
- ✅ **Caching**: Properly caches results to minimize API calls
- ✅ **Rate Limiting**: Respects 1 req/sec limit
- ✅ **Trip Planning**: Optimizes multi-park routes
- ✅ **Error Handling**: Gracefully handles failures
- ✅ **Integration**: Works with existing Park/ParkLocation models

## Usage Examples

### Basic Geocoding and Routing

```python
from parks.services import RoadTripService

service = RoadTripService()

# Geocode an address
coords = service.geocode_address("Universal Studios, Orlando, FL")

# Calculate route between two points
from parks.services.roadtrip import Coordinates
start = Coordinates(28.4755, -81.4685)  # Universal
end = Coordinates(28.4177, -81.5812)    # Magic Kingdom

route = service.calculate_route(start, end)
print(f"Distance: {route.formatted_distance}")
print(f"Duration: {route.formatted_duration}")
```

### Working with Parks

```python
# Find nearby parks
disney_world = Park.objects.get(name="Magic Kingdom")
nearby = service.get_park_distances(disney_world, radius_km=50)

for result in nearby[:5]:
    park = result['park']
    print(f"{park.name}: {result['formatted_distance']} away")

# Plan a multi-park trip
florida_parks = [
    Park.objects.get(name="Magic Kingdom"),
    Park.objects.get(name="SeaWorld Orlando"),
    Park.objects.get(name="Universal Studios Florida"),
]

trip = service.create_multi_park_trip(florida_parks)
print(f"Optimized trip: {trip.formatted_total_distance}")
```

### Find Parks Along Route

```python
start_park = Park.objects.get(name="Cedar Point")
end_park = Park.objects.get(name="Kings Island")

# Find parks within 25km of the route
parks_along_route = service.find_parks_along_route(
    start_park, 
    end_park, 
    max_detour_km=25
)

print(f"Found {len(parks_along_route)} parks along the route")
```

## OSM Usage Compliance

### Respectful API Usage

- **Proper User-Agent**: Identifies application and contact info
- **Rate Limiting**: 1 request per second as recommended
- **Caching**: Minimizes redundant API calls
- **Error Handling**: Doesn't spam APIs when they fail
- **Attribution**: Service credits OpenStreetMap data

### Terms Compliance

- Uses free OSM services within their usage policies
- Provides proper attribution for OpenStreetMap data
- Implements reasonable rate limiting
- Graceful fallbacks when services unavailable

## Future Enhancements

### Potential Improvements

1. **Alternative Routing Providers**
   - GraphHopper integration as OSRM backup
   - Mapbox Directions API for premium users

2. **Advanced Trip Planning**
   - Time-based optimization (opening hours, crowds)
   - Multi-day trip planning with hotels
   - Seasonal route recommendations

3. **Performance Optimizations**
   - Background geocoding of new parks
   - Precomputed distance matrices for popular parks
   - Redis caching for high-traffic scenarios

4. **User Features**
   - Save and share trip plans
   - Export to GPS devices
   - Integration with calendar apps

## Dependencies

- **requests**: HTTP client for API calls
- **Django GIS**: PostGIS integration for spatial queries
- **Django Cache**: Built-in caching framework

All dependencies are managed via UV package manager as per project standards.