FuelTrackingApp

Django REST API that calculates optimal fuel stops and total trip cost for long-haul truck routes across the US.

Overview

Given a start and destination city, the API queries Google Maps Directions for the route, walks waypoints to find matching gas stations from a local CSV dataset, and returns the cheapest sequence of stops ensuring the truck never exceeds its 450-mile range. Fuel cost is calculated per leg using real station prices from the dataset.

Architecture

FuelTrackingApp/
├── core/
│   ├── geo_service.py         # GeoService — lat/lon → city/state with in-memory cache
│   ├── route_service.py       # RouteService — Google Maps Directions wrapper
│   ├── gas_station_repo.py    # GasStationRepository — CSV loader + proximity filter
│   └── fuel_optimizer.py      # FuelOptimizer — orchestrates stop selection
├── api/
│   ├── views.py               # Django view — delegates to calculate_trip()
│   ├── utils.py               # Core trip calculation logic
│   ├── urls.py                # URL routing
│   └── fuel-prices-for-be-assessment.csv
├── fuel_api/                  # Django project settings
├── tests/
│   └── test_fuel_optimizer.py # pytest unit tests (no API key needed)
├── requirements.txt
└── manage.py

Design Patterns

• Repository — GasStationRepository abstracts CSV loading and proximity filtering behind load() and filter_along_route()
• Service Layer — GeoService, RouteService, and FuelOptimizer each own exactly one concern, making them independently testable and replaceable
• Facade — the Django view delegates entirely to calculate_trip(), keeping HTTP logic separate from business logic

Tech Stack

• Python 3.10+
• Django 3.2 — web framework
• Django REST Framework — JSON API response handling
• Google Maps Directions API — route calculation and waypoints
• Google Maps Geocoding API — coordinate-to-city resolution
• pandas — CSV gas station data loading and filtering
• geopy — geodesic distance calculations
• polyline — Google Maps route polyline decoding
• pytest — unit testing

Installation

git clone https://github.com/DaoudSabat/FuelTrackingApp.git
cd FuelTrackingApp
pip install -r requirements.txt

Set your environment variables:

# Windows
set GOOGLE_MAPS_API_KEY=your_key_here
set DJANGO_SECRET_KEY=your_secret_key_here

# macOS / Linux
export GOOGLE_MAPS_API_KEY=your_key_here
export DJANGO_SECRET_KEY=your_secret_key_here

Run the server:

python manage.py migrate
python manage.py runserver

Usage

GET /api/calculate_trip/?start=Dallas,TX&finish=Los+Angeles,CA

{
  "total_distance_miles": 1432.5,
  "estimated_travel_time": "21 hours 14 mins",
  "fuel_stops": [
    {
      "name": "LOVES TRAVEL STOP #123",
      "city": "El Paso",
      "state": "TX",
      "fuel_price_per_gallon": 3.89,
      "fuel_needed_gallons": 45.0,
      "total_cost": 175.05,
      "miles_traveled": 450.0
    }
  ],
  "total_fuel_cost": 558.20
}

Tests

pytest tests/ -v

All tests mock the Google Maps API and CSV reader — no API key or network required.

License

MIT