Django REST Framework · OSRM · Fuel-price optimizer

Architecture console for route fuel planning.

This page explains how the backend turns a start and destination into a route, finds fuel stations near that route, optimizes stops by price and reachability, and returns a JSON fuel plan. It can also call the local API directly.

System Architecture

Client Request

Receives JSON with start, destination, and optional vehicle settings.

Validation

FuelPlanRequestSerializer accepts address strings or USA-bounded coordinate objects.

Location + Route

Address inputs resolve through local city/state cache or Census, then OSRM returns GeoJSON route geometry.

Station Corridor

Active imported stations are filtered by route bounding box, projected to route miles, and clipped by corridor distance.

Fuel Optimizer

A reachable-stop planner buys enough fuel to reach cheaper downstream fuel, the destination, or the best reachable fallback.

Storage

Fuel data

Imported CSV rows become FuelStation records with price, identity, active state, and geocoding metadata.

External providers

OSRM + Census

OSRM calculates the route. Census handles freeform address geocoding and batch station geocoding when import runs with network access.

Fallbacks

GeoNames city data

Simple City, ST inputs and unmatched station rows can use city/state coordinates to avoid avoidable coverage gaps.

Live API Console

Run Django first with python manage.py runserver. For same-origin browser calls, open this page at /static/routing/architecture-api-demo.html on the same host and port as the Django server.

Request

API endpoint URL JSON payload

Response

Idle

Distance-

Total cost-

Stops-

Submit a request to inspect the API response.

Endpoint Contract

Accepted request fields

Field	Type	Rules
`start`	string or coordinate object	Required. String must be nonblank. Coordinates must be within broad USA bounds.
`destination`	string or coordinate object	Required. Same validation as `start`.
`corridor_miles`	integer	Optional. Defaults to 10. Maximum is 25.
`max_range_miles`	integer	Optional. Defaults to 500. Cannot exceed 500.
`miles_per_gallon`	decimal	Optional. Defaults to 10.00. Minimum is 1.

Response shape

route includes route distance and OSRM GeoJSON LineString geometry.
fuel_plan includes selected stops, gallons, cost, total gallons, total cost, MPG, range, and currency.
starting_fuel_assumption prices fuel needed before the first selected station when the station dataset starts away from the origin.
warnings reports planner assumptions such as needing enough starting fuel to reach the first selected station.
metadata.routing_provider identifies the routing provider as osrm.

400

Invalid request

Missing fields, invalid location types, out-of-range coordinates, or unsupported parameter values.

422

Planning failed

location_not_found or no_feasible_fuel_plan when the route exists but station coverage cannot satisfy range constraints.

503

Provider unavailable

routing_unavailable when OSRM or geocoding provider calls fail unexpectedly.

Operations

Setup commands

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py import_fuel_prices fuel-prices-for-be-assessment.csv --skip-geocoding
python manage.py runserver

Important assumptions

The default vehicle range is 500 miles and the default fuel economy is 10 MPG.
The planner does not grant free starting fuel; full route gallons are represented in totals.
Imported stations must be active and geocoded to participate in planning.
Live calls depend on OSRM availability unless tests or local code inject a fake router.