Set a fuel surcharge from the diesel price

Read the weekly diesel price

curl -s "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-on-highway-diesel/observations?start=2026-10-19&end=2026-11-03" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "series_id": "fuel-eia-usa-on-highway-diesel",
  "currency": "USD",
  "unit": "us_gallon",
  "unit_key": "gallon",
  "unit_quantity": "1",
  "attribution": "Source: U.S. Energy Information Administration",
  "observations": [
    {
      "period_start": "2026-10-19",
      "period_end": "2026-10-19",
      "price": "6.276",
      "revision": 1
    },
    {
      "period_start": "2026-10-26",
      "period_end": "2026-10-26",
      "price": "6.352",
      "revision": 1
    }
  ],
  "next_cursor": null
}

The series is weekly. Each observation is dated by one day, period_start equal to period_end, and the price is in currency USD per unit us_gallon. The series description says it is the weekly average retail price from a Monday survey, so a week is identified by its Monday. start is inclusive, end is exclusive and both must be sent together.

The response carries an attribution field, "Source: U.S. Energy Information Administration". Show it wherever you show the price, for example in the notes of an invoice or on the rate sheet.

curl -s "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-on-highway-diesel/latest" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "period_start": "2026-10-26",
  "period_end": "2026-10-26",
  "price": "6.352",
  "revision": 1,
  "series_id": "fuel-eia-usa-on-highway-diesel",
  "currency": "USD",
  "unit": "us_gallon",
  "unit_key": "gallon",
  "unit_quantity": "1",
  "attribution": "Source: U.S. Energy Information Administration"
}

/latest returns the newest observation without a date range. The week of 2026-10-26 carries 6.352 USD per gallon.

Set a surcharge from your own table

A fuel surcharge is a percentage added to the base freight charge when diesel is above a trigger price. The table that maps price to percentage belongs to the carrier and its customer. The API does not publish a surcharge schedule. The table in the script below is an example, so replace its numbers with the ones in your contract.

The lookup takes the highest row whose starting price is at or below the diesel price. A price of 6.276 sits in the 6.25 row, so the surcharge is 15.5 percent.

Run the calculation

1. Fetch the weeks The script requests the weeks from 5 October to 1 November 2026. The end date of 2026-11-01 is exclusive, and the last Monday inside the range is 2026-10-26.
2. Look up each week Each weekly price goes through the table. The four weeks return 14.0, 14.0, 15.5 and 15.5 percent.
3. Try a monthly rule The average of the four prices is 6.252 and the table gives 15.5 percent. For the week of 2026-10-05 a weekly rule bills 14.0 percent and the monthly rule bills 15.5 percent.
4. Read the latest The script then reads /latest, applies the table and prints the attribution.
   Python, fuel surcharge from the diesel price

   import os
   import requests
   
   HEAD = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   BASE = "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-on-highway-diesel"
   
   # Your own table: the surcharge percent that starts at each price (USD per US gallon)
   TABLE = [(0.00, 0.0), (4.00, 3.0), (5.00, 8.0), (5.50, 11.0), (6.00, 14.0), (6.25, 15.5), (6.50, 17.0)]
   
   def surcharge(price):
       return max(pct for floor, pct in TABLE if price >= floor)
   
   r = requests.get(BASE + "/observations", params={"start": "2026-10-05", "end": "2026-11-01"},
                    headers=HEAD, timeout=15)
   r.raise_for_status()
   weeks = [(o["period_start"], float(o["price"])) for o in r.json()["observations"]]
   for day, price in weeks:
       print(day, price, f"{surcharge(price)}%")
   
   # Monthly rule: average the weekly prices, then look up the table
   average = sum(price for _, price in weeks) / len(weeks)
   print(f"October average {average:.3f} -> {surcharge(average)}%")
   
   latest = requests.get(BASE + "/latest", headers=HEAD, timeout=15).json()
   price = float(latest["price"])
   print("latest", latest["period_start"], price, f"{surcharge(price)}%", latest["attribution"])

On a base freight charge of 1,200.00 USD, 15.5 percent is a surcharge of 186.00 USD. Round the percentage and the amount the way your contract says.

Check the data before you bill

• The newest period_start is a date you expect. If it is older than your contract allows, hold the invoice and say why.
• The currency is USD and the unit is us_gallon. A table written for litres or another currency would give a wrong percentage if it met these numbers.
• The price converts to a number. It arrives as a string, so convert it once and keep the original text in your log.
• The revision is stored with the price. Every row above shows revision 1, and the stored value lets you explain a later difference.
• The attribution text is on the invoice or rate sheet.

Which price should set the surcharge?

The contract decides, so write the rule down in plain words: the latest week, the average of the weeks in the billing month, or the week before the shipment. The code above does the first two. The third is a lookup by date on the same observations: request the weeks around the ship date with start and end, then pick the Monday that your clause names. Whichever you choose, apply it the same way to every invoice, since a rule that changes between invoices will draw questions from the customer.

Regional series exist too. The id fuel-eia-usa-on-highway-diesel-padd-3 returned 5.951 USD per gallon for the week of 2026-10-26, which the example table would price at 11.0 percent instead of 15.5. If the lanes sit in one region, a regional series can fit better than the national one.

How current is the latest price?

Observations are dated by their Monday, and the newest one can be a week or more behind the current Monday. Apply the table to the latest observation you hold and print its period_start on the invoice, so the customer can see which week set the charge.

Does the API cover diesel outside the US?

This series is for the United States. The listing route GET /v1/commodities/physical/series?commodity=diesel shows what else is published for diesel, with its country, currency and unit. Read those fields before you apply a table written in USD per gallon to another series.