Oil price API: list countries
List countriesEvery country we price, what we hold for it and how far back it goes.
PlansEvery plan
Cost1 call per request
ReturnsEvery country in one call
UpdatedHourly
What it is for
The list to start from: every country we hold prices for, what kind (stations, pump averages, set prices, taxes), how many fuels and stations, the first year on record and how often its prices change.
Narrow it with region. The answer is small and changes slowly, so it is safe to keep for a day.
Good for
- A country picker for your app
- Which countries have station by station prices
- How far back history goes before you ask for it
coverageParameters 1 in the query
| Name | Where and type | Required | What it does | Example |
|---|---|---|---|---|
region | query one of | optional | Only this region. One of europe, americas, asia_pacific, middle_east, africa. | europe |
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 |
|---|---|---|---|
country | string | Two letter country code | "AL" |
name | string | Our name for it | "Albania" |
region | string | The region, or the town or zone a set price is for | "europe" |
holds | object | What we hold: stations, pump_averages, set_prices, taxes | {"stations":false,"pump_averages":fal... |
fuels | integer | How many fuels we price there | 2 |
stations | integer | How many stations we read | 0 |
since | integer | The first year on record | 2026 |
cadence | string | live, daily, weekly or monthly | "monthly" |
last_change | string | When a price last changed | "2026-10-01T00:00:00Z" |
Example answer real, from what we hold now; long lists cut to three
GET /v1/countries?region=europe{ "data": [ { "country": "AL", "name": "Albania", "region": "europe", "holds": { "stations": false, "pump_averages": false, "set_prices": true, "taxes": false }, "fuels": 2, "stations": 0, "since": 2026, "cadence": "monthly", "last_change": "2026-10-01T00:00:00Z" }, { "country": "AT", "name": "Austria", "region": "europe", "holds": { "stations": true, "pump_averages": true, "set_prices": false, "taxes": true }, "fuels": 5, "stations": 2029, "since": 2005, "cadence": "live", "last_change": "2026-10-29T21:47:01Z" }, { "country": "AZ", "name": "Azerbaijan", "region": "europe", "holds": { "stations": false, "pump_averages": false, "set_prices": true, "taxes": false }, "fuels": 3, "stations": 0, "since": 2026, "cadence": "monthly", "last_change": "2026-10-01T00:00:00Z" } ], "meta": { "count": 43 } }
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.