API Documentation

Endpoints

Configured base URL: https://routefuel-api.onrender.com

GET /api/v1/health/

Liveness check. Returns status and service.

POST /api/v1/routes/

Driving route, resolved locations, geometry and provider metadata.

POST /api/v1/routes/optimize/

Driving route plus fuel stops, purchases and fuel-cost summary.

Optimize a route

Required: start and finish as City, ST, City, State, or latitude/longitude objects. Coordinates must be within the 50 US states or DC.

{
  "start": "Dallas, TX",
  "finish": "Atlanta, GA",
  "vehicle": {
    "range_miles": 500,
    "mpg": 10,
    "starting_fuel_gallons": 50
  },
  "geometry_detail": "simplified"
}

Optional vehicle settings: range_miles (above 0, up to 5000), mpg (above 0, up to 200), starting_fuel_gallons (0 to range ÷ MPG), starting_fuel_price_per_gallon ($0.50–$20.00, up to 8 decimals). Numeric vehicle fields must be JSON numbers; price accepts a string or number.

Optional stop_policy.min_savings_per_stop: above $0 and up to $1,000, at most 2 decimals. geometry_detail accepts full or simplified.

Reading results

Money, fuel prices and gallons are decimal strings. Fuel purchases exclude the value of starting fuel. Display estimated_total_fuel_cost only when estimated_total_fuel_cost_status is calculated; otherwise use cost_note.

Route geometry uses [longitude, latitude]. Driving time excludes stops. Station coordinates mark approximate town locations; address and road access must be checked separately.

Errors

{"error":{"code":"location_not_found","message":"Human-readable explanation.","details":{"field":"start"}}}

Validation: 400. Location or infeasible route: 422. Provider errors: 502 / 503 / 504. Unexpected server errors: 500. The client allows 30 seconds for route requests.

The complete source of truth is docs/api-contract.md. Import docs/postman/RouteFuel.postman_collection.json into Postman for executable examples.