Oil price API: pass-through
Pass-throughHow much of a change in crude reaches the pump in a place and how fast, from daily average pump prices, fitted day by day and week by week.
PlansEvery plan
Cost1 call per request
ReturnsOne place, one or every fuel
UpdatedWeekly
What it is for
How much of a change in crude reaches the pump, and how fast, for a country or a state: worked out from stored daily average pump prices, before taxes where we hold the country's taxes and with taxes where we do not (then full pass-through is a cent plus VAT).
Two fits, each for the whole record and the last three years: daily, on 0 to 20 trading days of crude changes, and weekly, on weekly averages and 0 to 8 weeks, which reads better where pump prices run in weekly cycles, as in Australian cities. Each gives the pass-through, the time by which half and nine tenths has come through, rises and falls apart, and where a refined product price is held, the same split into crude and refining. For an EU country the weekly figures from Price breakdown come too, in eu_weekly. Leave out place for the places we hold.
Good for
- How fast pump prices follow crude
- Comparing countries and states
- Whether prices rise faster than they fall
- Telling crude moves from refining moves
pass_throughParameters 3 in the query
| Name | Where and type | Required | What it does | Example |
|---|---|---|---|---|
place | query string | optional | A country, or a country and state, such as fr, es, au-wa or au-nsw; leave out for the list of places. | fr |
fuel | query string | optional | One fuel, such as diesel or gasoline_95; leave out for every fuel the place has. | diesel |
fit | query one of | optional | daily or weekly; leave out for both. One of daily, weekly. | daily |
Try it runs against the live API with your key
No key yet? Get a free one; it is saved in this browser for every page.
The answer 200, application/json
| Field | Type | What it holds | Example |
|---|---|---|---|
place | string | A country, or a country and state such as au-wa | "FR" |
country | string | Two letter country code | "FR" |
region | string | The region, or the town or zone a set price is for | null |
name | string | Our name for it | "France" |
fuel | string | Fuel code; see Fuels and units | "diesel" |
basis | string | before_taxes or with_taxes: the price the fit is on | "before_taxes" |
daily | object | The daily fit, all and last_3_years: pass_through, lag50_days, lag90_days, r2, rises, falls and with_product | {"all":{"points":4960,"from":"2007-01... |
weekly | object | The weekly fit, all and last_3_years: pass_through, lag50_weeks, lag90_weeks, r2, rises, falls and with_product | {"all":{"points":1034,"from":"2007-01... |
eu_weekly | object | For an EU country, the weekly figures from Price breakdown; otherwise null | {"all":{"weeks":1090,"from":"2005-01-... |
Example answer real, from what we hold now; long lists cut to three
GET /v1/passthrough?place=fr&fuel=diesel{ "data": { "place": "FR", "country": "FR", "region": null, "name": "France", "fuel": "diesel", "basis": "before_taxes", "daily": { "all": { "points": 4960, "from": "2007-01-08", "to": "2026-10-27", "pass_through": 0.925, "lag50_days": 3, "lag90_days": 6, "r2": 0.24, "rises": 0.856, "falls": 0.878, "with_product": { "crude_pass_through": 0.857, "crude_lag50_days": 3, "refining_pass_through": 0.226, "refining_lag50_days": 2, "r2": 0.287 } }, "last_3_years": { "points": 755, "from": "2023-10-30", "to": "2026-10-27", "pass_through": 1.013, "lag50_days": 3, "lag90_days": 6, "r2": 0.375, "rises": 0.879, "falls": 0.89, "with_product": { "crude_pass_through": 1.285, "crude_lag50_days": 4, "refining_pass_through": 0.533, "refining_lag50_days": 4, "r2": 0.617 } } }, "weekly": { "all": { "points": 1034, "from": "2007-01-08", "to": "2026-10-26", "pass_through": 0.919, "lag50_weeks": 1, "lag90_weeks": 1, "r2": 0.403, "rises": 0.929, "falls": 0.866, "with_product": { "crude_pass_through": 0.579, "crude_lag50_weeks": 1, "refining_pass_through": 0.832, "refining_lag50_weeks": 1, "r2": 0.507 } }, "last_3_years": { "points": 157, "from": "2023-10-30", "to": "2026-10-26", "pass_through": 1.02, "lag50_weeks": 0, "lag90_weeks": 1, "r2": 0.669, "rises": 0.984, "falls": 0.839 } }, "eu_weekly": { "all": { "weeks": 1090, "from": "2005-01-03", "to": "2026-10-26", "share_of_movement": { "taxes": 0.176, "crude_price": 0.372, "exchange_rate": 0.013, "margin": 0.438, "refining": 0.207, "distribution": 0.231, "unexplained": 0.001 }, "pass_through": 1.068, "lag50_weeks": 0, "lag90_weeks": 1, "r2": 0.462, "rises": { "pass_through": 1.009, "lag50_weeks": 0 }, "falls": { "pass_through": 1.08, "lag50_weeks": 0 } }, "last_3_years": { "weeks": 157, "from": "2023-10-30", "to": "2026-10-26", "share_of_movement": { "taxes": 0.167, "crude_price": 0.418, "exchange_rate": 0.017, "margin": 0.398, "refining": 0.194, "distribution": 0.205, "unexplained": 0 }, "pass_through": 0.875, "lag50_weeks": 0, "lag90_weeks": 1, "r2": 0.584, "rises": { "pass_through": 0.792, "lag50_weeks": 0 }, "falls": { "pass_through": 0.639, "lag50_weeks": 0 } } } }, "meta": { "worked_out_at": "2026-10-30T02:21:15Z", "note": "Pass-through is the cents at the pump for a cent change in crude, after 20 trading days (daily) or 8 weeks (weekly). Worked out from stored prices." } }
Errors every error has the same shape
| HTTP | Code | When | What to do |
|---|---|---|---|
| 401 | unauthorized | No key, or not a valid one | Send your key in the X-API-Key header; your account page shows it. |
| 400 | bad_request | A value is wrong or a required one is missing | The message names the parameter and the form it takes. |
| 422 | unknown_parameter | A parameter this endpoint does not take | Take it out; the parameters this endpoint takes are listed above. |
| 429 | rate_limited | Too many calls this minute | Wait the seconds in the Retry-After header, then call again. |
| 429 | quota_exceeded | Today's calls are used up | Wait for the day to reset at midnight UTC, or move to a larger plan. |
Dates and times are UTC. A point's date is the day its price took effect, or the first day of its week or month for weekly and monthly series. Conversions use each day's own rate, so a converted series moves with both the price and the exchange rate.