Diesel Price API: Real-Time Fuel Data for Trucking & Fleet Software

import requests
from datetime import datetime
from typing import Optional

class FuelSurchargeCalculator:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.oilpriceapi.com/v1"
        self.headers = {"Authorization": f"Token {api_key}"}

        # Standard surcharge formula parameters
        self.base_fuel_price = 1.25  # Historical baseline (DOE average)
        self.surcharge_per_dollar = 0.01  # 1 cent per dollar above baseline

    def get_current_diesel(self, region: str = "NATIONAL") -> float:
        """Get current diesel price for region."""
        code = f"US_DIESEL_{region.upper()}_USD"
        response = requests.get(
            f"{self.base_url}/prices/latest",
            params={"by_code": code},
            headers=self.headers
        )
        return response.json()["data"]["price"]

    def calculate_surcharge_percent(self, diesel_price: float) -> float:
        """Calculate fuel surcharge percentage."""
        if diesel_price <= self.base_fuel_price:
            return 0.0
        overage = diesel_price - self.base_fuel_price
        surcharge = overage * self.surcharge_per_dollar * 100
        return round(surcharge, 2)

    def get_surcharge_by_region(self):
        """Get fuel surcharges for all PADD regions."""
        regions = [
            "NATIONAL", "PADD1A", "PADD1B", "PADD1C",
            "PADD2", "PADD3", "PADD4", "PADD5", "CALIFORNIA"
        ]

        surcharges = {}
        for region in regions:
            price = self.get_current_diesel(region)
            surcharge = self.calculate_surcharge_percent(price)
            surcharges[region] = {
                "diesel_price": price,
                "surcharge_percent": surcharge
            }

        return surcharges

    def calculate_lane_fuel_cost(
        self,
        origin_region: str,
        dest_region: str,
        miles: float,
        mpg: float = 6.5
    ) -> dict:
        """Calculate fuel cost for a lane."""
        gallons_needed = miles / mpg

        origin_price = self.get_current_diesel(origin_region)
        dest_price = self.get_current_diesel(dest_region)
        avg_price = (origin_price + dest_price) / 2

        return {
            "miles": miles,
            "mpg": mpg,
            "gallons_needed": round(gallons_needed, 1),
            "avg_diesel_price": round(avg_price, 3),
            "estimated_fuel_cost": round(gallons_needed * avg_price, 2),
            "origin_region": origin_region,
            "dest_region": dest_region
        }

# Usage
calculator = FuelSurchargeCalculator("YOUR_API_KEY")

# Get current fuel surcharges by region
surcharges = calculator.get_surcharge_by_region()
print("Regional Fuel Surcharges:")
for region, data in surcharges.items():
    print(f"  {region}: ${data['diesel_price']:.3f}/gal → {data['surcharge_percent']}%")

# Calculate fuel cost for a specific lane
lane = calculator.calculate_lane_fuel_cost(
    origin_region="PADD3",  # Houston
    dest_region="PADD1B",   # New York
    miles=1750,
    mpg=6.5
)
print(f"\nHouston → New York ({lane['miles']} mi):")
print(f"  Fuel needed: {lane['gallons_needed']} gallons")
print(f"  Avg price: ${lane['avg_diesel_price']}/gal")
print(f"  Fuel cost: ${lane['estimated_fuel_cost']}")

def estimate_route_fuel_cost(origin_padd, dest_padd, miles, mpg=6.5):
    """Estimate fuel cost for a trucking route."""
    origin_price = get_diesel_price(origin_padd)
    dest_price = get_diesel_price(dest_padd)

    # Average of origin and destination regions
    avg_price = (origin_price + dest_price) / 2

    gallons = miles / mpg
    fuel_cost = gallons * avg_price

    return {
        "miles": miles,
        "gallons": round(gallons, 1),
        "fuel_cost": round(fuel_cost, 2),
        "cost_per_mile": round(fuel_cost / miles, 3)
    }

def calculate_driver_reimbursement(fill_region, gallons):
    """Calculate driver reimbursement based on regional diesel price."""
    regional_price = get_diesel_price(fill_region)
    reimbursement = gallons * regional_price
    return round(reimbursement, 2)

def adjust_carrier_rate(base_rate, current_diesel, baseline_diesel=2.50):
    """Adjust carrier rate based on fuel price change."""
    fuel_change = (current_diesel - baseline_diesel) / baseline_diesel
    adjustment_factor = 0.30  # Fuel is ~30% of carrier costs

    rate_adjustment = base_rate * fuel_change * adjustment_factor
    adjusted_rate = base_rate + rate_adjustment

    return {
        "base_rate": base_rate,
        "current_diesel": current_diesel,
        "rate_adjustment": round(rate_adjustment, 2),
        "adjusted_rate": round(adjusted_rate, 2)
    }