Production-quality Django API that plans a driving route between two US locations, returns map geometry, and recommends cost-optimal fuel stops along the route based on the provided fuel price dataset.
Spotter is useful as a reference implementation for route-aware optimization, GeoJSON API responses, and isolating external geocoding and routing providers behind testable service boundaries.
- Plan a US driving route from start to finish (address string or coordinates)
- Return route geometry as GeoJSON suitable for map rendering
- Recommend cost-optimal fuel stops for a vehicle with a 500-mile range and 10 MPG
- Calculate total fuel spend at recommended stops
- Fast responses with one routing API call per request (plus optional geocoding when addresses are supplied)
- Route planning makes one OSRM call for coordinate inputs; response time also depends on the public routing service
- Consistent error handling, request IDs, health checks, throttling, and automated tests
- Interactive web UI with live map, route visualization, and fuel stop details
| Layer | Choice |
|---|---|
| Framework | Django 6.1.2 (current stable series) |
| API | Django REST Framework |
| Database | SQLite (development / assessment) |
| Routing | OSRM public API |
| Geocoding | Local US city cache, then Photon/Nominatim for addresses |
| Fuel station geocoding | Offline GeoNames seed (data/geocode_seed.json) |
| HTTP client | httpx |
| Tests | pytest, pytest-django |
| Lint/format | ruff |
| CI | GitHub Actions |
| Containers | Docker + Docker Compose |
The project follows a layered design with clear domain boundaries:
API View (apps/routing/views.py)
↓
RoutePlannerService (orchestration)
↓
├── GeocodingClient (local/Photon/Nominatim) - start/finish only
├── RoutingClient (OSRM) - one call per request
├── FuelStationRepository - local DB lookup
└── FuelOptimizer - minimum-cost refueling
Key design choices
- External API minimization: If clients send coordinates, the API makes exactly one external call (OSRM). Cached US city/state inputs need no external geocoding; other addresses may require Photon or Nominatim calls before the one OSRM call.
- Fuel prices are local: The assessment CSV is loaded into SQLite with coordinates resolved offline from GeoNames, avoiding runtime geocoding for ~6,800 stations.
- Fuel optimization: Stations along the route corridor are projected onto the route, then a fuel-aware greedy algorithm buys enough to reach a cheaper station, or fills the tank when no cheaper station is reachable. Fuel remaining from the initial tank and earlier purchases is carried forward.
- Dependency injection: Clients and repositories are injectable for testing.
Cost and location assumptions: The initial tank is full and already paid for, so total_fuel_cost_usd counts refills during the trip; total_gallons_consumed covers the full route. The supplied CSV has no station coordinates. The offline seed uses locality-level locations, so stops and detours are approximate rather than turn-by-turn station entrances. Public OSRM, Photon, and Nominatim services are rate-limited and do not provide a production SLA.
Spotter/
├── apps/
│ ├── core/ # Shared constants, geo utils, health check, middleware
│ ├── fuel/ # Fuel models, repository, optimizer, CSV loader
│ └── routing/ # OSRM client, route planner service, API endpoints
├── config/ # Django settings and root URLs
├── data/
│ └── geocode_seed.json
├── scripts/
│ └── build_geocode_seed.py
├── fuel-prices-for-be-assessment.csv
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── requirements.txt
- Python 3.12+
- Make (optional, recommended)
git clone https://github.com/SIBTAIN-ASAD/Spotter.git
cd Spotter
make setup
make devmake setup will:
- Create a virtual environment
- Install dependencies
- Copy
.env.exampleto.env - Run migrations
- Load fuel stations from the CSV
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py load_fuel_stations
python manage.py runserverOpen the interactive map UI at http://127.0.0.1:8000/ (API remains at /api/v1/).
If you replace the fuel CSV or want to refresh coordinates:
python scripts/build_geocode_seed.py
python manage.py load_fuel_stations --clearSee .env.example for all supported settings:
| Variable | Description | Default |
|---|---|---|
SECRET_KEY |
Django secret key | required |
DEBUG |
Debug mode | True |
ALLOWED_HOSTS |
Allowed hostnames | localhost,127.0.0.1 |
OSRM_BASE_URL |
OSRM router base URL | https://router.project-osrm.org |
NOMINATIM_BASE_URL |
Nominatim base URL | https://nominatim.openstreetmap.org |
NOMINATIM_USER_AGENT |
Required Nominatim UA | project identifier |
VEHICLE_RANGE_MILES |
Max range on full tank | 500 |
VEHICLE_MPG |
Fuel efficiency | 10 |
ROUTE_CORRIDOR_MILES |
Max distance from route to consider a station | 50 |
HTTP_TIMEOUT_SECONDS |
External HTTP timeout | 15 |
FUEL_PRICES_CSV_PATH |
Fuel CSV path | fuel-prices-for-be-assessment.csv |
make test
# or
pytestmake lint
make formatmake docker-up
# API available at http://localhost:8000
make docker-downGET /
Interactive route planner with Leaflet map, trip stats, and clickable fuel stop list.
GET /api/v1/health/
POST /api/v1/routes/plan/
Request body
{
"start": "New York, NY",
"finish": {"lat": 38.9072, "lng": -77.0369, "label": "Washington, DC"}
}Both start and finish accept either:
- a US address string, or
- an object with
lat/latitudeandlng/longitude
Successful response (200)
{
"start": {"label": "New York, NY", "location": {"type": "Point", "coordinates": [-74.006, 40.7128]}},
"finish": {"label": "Washington, DC", "location": {"type": "Point", "coordinates": [-77.0369, 38.9072]}},
"route": {"type": "LineString", "coordinates": [[...]]},
"map": {"type": "FeatureCollection", "features": [...]},
"distance_miles": 225.5,
"duration_seconds": 14400.0,
"fuel_stops": [
{
"station_id": 123,
"name": "Example Travel Center",
"retail_price": 3.10,
"gallons_purchased": 20.0,
"fuel_cost_usd": 62.0,
"location": {"type": "Point", "coordinates": [-75.1652, 39.9526]}
}
],
"total_fuel_cost_usd": 62.0,
"total_gallons_consumed": 22.55,
"vehicle": {"range_miles": 500, "mpg": 10},
"request_id": "..."
}Error response shape
{
"error": {
"code": "validation_error",
"message": "...",
"details": {...}
},
"request_id": "..."
}Common status codes:
400validation errors422business-rule violations (e.g. unreachable destination)502upstream invalid response503upstream unavailable
| Decision | Rationale |
|---|---|
| OSRM for routing | Free, fast, widely used, single-call route + geometry |
| Offline fuel geocoding | Avoids thousands of runtime geocoding calls and rate limits |
| Fuel-aware greedy optimizer | Carries remaining fuel between stops and minimizes purchases under range constraints |
| SQLite | Zero-config for assessment reviewers |
| GeoJSON map payload | Directly usable by map clients (Leaflet, Mapbox GL, etc.) |
- The vehicle starts with a full tank; fuel cost counts purchases at recommended stops only.
- For trips under 500 miles, no fuel stops are required and fuel cost is
$0.00. - Fuel stations are matched to routes using city/state coordinates (GeoNames), not exact street addresses.
- When multiple price records exist for the same station, the lowest price is used.
- Only US locations are supported.
- City-level geocoding is less precise than street-level geocoding, but is reliable and fast for corridor matching.
- The optimizer carries fuel between stops, never exceeds tank capacity, and counts only new purchases toward fuel spend. Per-stop costs are rounded to cents and summed; total gallons represents fuel consumed over the whole route.
- Public OSRM/Nominatim endpoints are suitable for assessment/demo usage; production would use self-hosted or paid providers.
- ~128 city/state pairs in the CSV could not be matched to GeoNames exactly.
- Public geocoding/routing APIs may rate-limit heavy usage.
- No authentication is implemented (not required by the assessment).
- Self-hosted OSRM / Pelias / Nominatim instances
- PostGIS for spatial indexing and exact corridor queries
- Caching of route responses
- OpenAPI schema generation with
drf-spectacular - Authentication and per-user rate limits
- Secrets loaded from environment variables
.envexcluded from version control- DRF throttling enabled
- Production security headers configured when
DEBUG=False - Error responses avoid stack traces and internal details
- Unit tests for geo utilities and fuel optimizer
- API tests with mocked planner for validation and error handling
- Integration test for route planner with stubbed routing client and seeded DB stations
- External APIs mocked at service boundaries; no live network dependency in CI