Logistics Fuel Cost API

import requests
from datetime import datetime
from typing import Dict, List

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

        # Industry standard fuel efficiency rates (miles per gallon)
        self.mpg_standards = {
            'dry_van': 6.5,
            'reefer': 5.8,
            'flatbed': 6.2,
            'tanker': 5.5,
            'ltl': 7.0,
            'sprinter_van': 14.0,
            'box_truck': 10.0
        }

    def get_diesel_price(self) -> float:
        """Get current diesel price."""
        response = requests.get(
            f'{self.base_url}/prices/latest',
            params={'by_code': 'DIESEL_USD'},
            headers=self.headers
        )
        data = response.json()
        return data['data']['price']

    def calculate_lane_fuel_cost(self, distance_miles: float,
                                  equipment_type: str = 'dry_van') -> Dict:
        """Calculate fuel cost for a specific lane."""
        mpg = self.mpg_standards.get(equipment_type, 6.5)
        diesel_price = self.get_diesel_price()

        gallons_needed = distance_miles / mpg
        fuel_cost = gallons_needed * diesel_price
        cost_per_mile = fuel_cost / distance_miles

        return {
            'distance_miles': distance_miles,
            'equipment_type': equipment_type,
            'mpg': mpg,
            'gallons_needed': round(gallons_needed, 2),
            'diesel_price': diesel_price,
            'total_fuel_cost': round(fuel_cost, 2),
            'cost_per_mile': round(cost_per_mile, 3)
        }

    def calculate_fuel_surcharge(self, base_fuel_price: float,
                                  distance_miles: float,
                                  base_surcharge_per_mile: float = 0.0) -> Dict:
        """Calculate fuel surcharge based on current vs base fuel price."""
        current_price = self.get_diesel_price()
        price_difference = current_price - base_fuel_price

        # Standard surcharge calculation: price difference * miles / mpg
        standard_mpg = 6.0  # Industry standard for surcharge calculations
        surcharge = (price_difference / standard_mpg) * distance_miles

        # Alternative: per-mile surcharge based on price tiers
        if current_price <= base_fuel_price:
            tier_surcharge_per_mile = base_surcharge_per_mile
        elif current_price <= base_fuel_price + 0.50:
            tier_surcharge_per_mile = base_surcharge_per_mile + 0.05
        elif current_price <= base_fuel_price + 1.00:
            tier_surcharge_per_mile = base_surcharge_per_mile + 0.12
        else:
            tier_surcharge_per_mile = base_surcharge_per_mile + 0.20

        return {
            'base_fuel_price': base_fuel_price,
            'current_fuel_price': current_price,
            'price_difference': round(price_difference, 3),
            'distance_miles': distance_miles,
            'calculated_surcharge': round(surcharge, 2),
            'tier_surcharge_per_mile': tier_surcharge_per_mile,
            'tier_surcharge_total': round(tier_surcharge_per_mile * distance_miles, 2)
        }

    def estimate_shipment_fuel_cost(self, shipments: List[Dict]) -> Dict:
        """Estimate total fuel cost for multiple shipments."""
        diesel_price = self.get_diesel_price()
        total_miles = 0
        total_gallons = 0
        total_fuel_cost = 0

        shipment_details = []
        for shipment in shipments:
            mpg = self.mpg_standards.get(shipment.get('equipment', 'dry_van'), 6.5)
            miles = shipment['distance_miles']
            gallons = miles / mpg
            fuel_cost = gallons * diesel_price

            total_miles += miles
            total_gallons += gallons
            total_fuel_cost += fuel_cost

            shipment_details.append({
                'shipment_id': shipment.get('id', 'unknown'),
                'origin': shipment.get('origin', ''),
                'destination': shipment.get('destination', ''),
                'distance_miles': miles,
                'fuel_cost': round(fuel_cost, 2)
            })

        return {
            'diesel_price': diesel_price,
            'total_miles': total_miles,
            'total_gallons': round(total_gallons, 2),
            'total_fuel_cost': round(total_fuel_cost, 2),
            'average_cost_per_mile': round(total_fuel_cost / total_miles, 3) if total_miles > 0 else 0,
            'shipments': shipment_details
        }

    def get_price_trend(self, days: int = 30) -> Dict:
        """Get fuel price trend for forecasting."""
        endpoint = 'past_week' if days <= 7 else 'past_month' if days <= 30 else 'past_year'
        response = requests.get(
            f'{self.base_url}/prices/{endpoint}',
            params={'by_code': 'DIESEL_USD', 'interval': '1d'},
            headers=self.headers
        )
        data = response.json()
        prices = [p['price'] for p in data['data']['prices']]

        current = prices[0]
        avg = sum(prices) / len(prices)
        change = current - prices[-1]
        change_pct = (change / prices[-1]) * 100

        return {
            'current_price': current,
            'period_average': round(avg, 3),
            'period_low': min(prices),
            'period_high': max(prices),
            'price_change': round(change, 3),
            'change_pct': round(change_pct, 2),
            'trend': 'rising' if change_pct > 2 else 'falling' if change_pct < -2 else 'stable',
            'volatility': round((max(prices) - min(prices)) / avg * 100, 2)
        }

# Usage example
logistics = LogisticsFuelManager('YOUR_API_KEY')

# Calculate fuel cost for a lane
lane_cost = logistics.calculate_lane_fuel_cost(
    distance_miles=1500,
    equipment_type='reefer'
)
print(f"Lane fuel cost: ${lane_cost['total_fuel_cost']}")

# Calculate fuel surcharge
surcharge = logistics.calculate_fuel_surcharge(
    base_fuel_price=3.00,
    distance_miles=1500
)
print(f"Fuel surcharge: ${surcharge['calculated_surcharge']}")