# OilAPI manual

Oil and fuel prices for every country we can read: pump prices, government set prices, every station where a country publishes them, and crude and product benchmarks back to 1987.

- Base address: https://api.oilapi.net/v1
- Key: send `X-API-Key: YOUR_API_KEY` or `Authorization: Bearer YOUR_API_KEY`. A key in the address is refused.
- Every answer: `{"data": ..., "meta": {...}}`, or `{"error": {"code", "message", "docs"}}`.
- Prices are in the country's own currency and unit; add `currency=usd` to convert at each day's rate.
- MCP server: https://oilapi.net/mcp (tools listed below).

## Quick start

### Get a key

Sign in at [oilapi.net/signup](https://oilapi.net/signup). Your free key is made at once and saved in this browser, so every Try it on these pages runs with it.

### Make your first call

Ask for a country's pump prices now:

```
curl -G "https://api.oilapi.net/v1/prices/retail" \
  -d country=gb \
  -H "X-API-Key: YOUR_API_KEY"
```

Every answer has the same shape: `data`, then `meta` with the count and any notes about your plan.

### Where next

[List countries](https://oilapi.net/documentation/countries) shows what we hold for each country, [Find stations](https://oilapi.net/documentation/stations) finds the cheapest pumps near a point, and [Benchmark history](https://oilapi.net/documentation/benchmark) gives Brent and WTI back to 1987. The [recipes](https://oilapi.net/documentation/cheapest-fuel-near-a-user) put calls together.

## Authentication

### Sending your key

Send it in a header, one of these two:

```
X-API-Key: YOUR_API_KEY
```

```
Authorization: Bearer YOUR_API_KEY
```

A key in the address (`?key=`) is refused with a 400, so it never lands in a log.

### Your key

One key per account, made when you sign up. It follows your plan: change plan and the same key reads what the new plan allows on its next call. We keep only a fingerprint of it, so a lost key cannot be shown again.

### Rotating

Rotate from [your account](https://oilapi.net/account/keys). You get a new key at once, shown one time; the old one keeps working for 24 hours, so your code can switch without a gap.

## Plans and limits

### What every plan reads

Every plan reads every endpoint. What differs is how fresh and how deep: the free key reads prices as they stood at the end of yesterday (UTC), and each plan reads back as far as its history allows. A call past your history gets the part you can read, with `meta.history_from` and a note.

### The plans

| Plan| Price| Calls a day| Calls a minute| Prices| History |
|---|---|---|---|---|---|
| Free key| Free| 50| 10| Yesterday| 30 days |
| Live| $29 a month| 10,000| 60| Today| 2 years |
| Complete| $99 a month| 100,000| 300| Today| Full record |
| Analyst| $249 a month| 500,000| 1,000| Today| Full record |

Annual plans cost 10 months. See [pricing](https://oilapi.net/pricing).

## Rate limits

### Two limits

Each plan has calls a minute and calls a day (the free key: 10 and 50). The day resets at 00:00 UTC.

### The headers

| Header| What it says |
|---|---|
| `X-RateLimit-Limit`| Calls a minute on your plan |
| `X-RateLimit-Remaining`| Left this minute |
| `X-RateLimit-Reset`| When the minute resets, in Unix seconds |
| `X-Quota-Remaining`| Calls left today |

### Past a limit

You get a 429: `rate_limited` for the minute, `quota_exceeded` for the day, each with `Retry-After`. [Your usage](https://oilapi.net/documentation/usage) shows where you stand and does not count.

## Errors

### The shape

```
{"error": {"code": "unknown_parameter", "message": "...", "docs": "https://oilapi.net/documentation/errors"}}
```

The code is fixed forever and meant for your code; the message is for people.

### Every code

| Code| Status| What to do |
|---|---|---|
| `bad_request`| 400| A value is wrong or missing. The message says which and what is expected. |
| `unknown_parameter`| 422| A parameter this endpoint does not take. The message lists the ones it does. |
| `unauthorized`| 401| No key, or a key that is not valid. Send it in X-API-Key. |
| `upgrade_required`| 403| Your plan does not include this. The error names the plan that does. |
| `not_found`| 404| No record by that id or name, or no such endpoint. An empty list is a 200, never a 404. |
| `rate_limited`| 429| Too many calls this minute. Wait for Retry-After seconds. |
| `quota_exceeded`| 429| Today's calls are used up. They reset at 00:00 UTC. |
| `server_error`| 500| Our side went wrong. It is logged; try again shortly. |

## Pagination

### Pages

Lists take `page` (from 1) and `per_page`. A paged call returns in `meta`: `count`, `page`, `per_page`, `total`, `total_pages`, `next_page` and `prev_page` (null at the ends).

### Cursors

Every list also returns `next_cursor`. Following it returns only `count` and `next_cursor`, which keeps long walks fast. When `next_cursor` is null you have it all.

## Versioning

### The promise

Every address starts `/v1`. Within v1 we add fields, endpoints and parameters, and never rename or remove one. Read the fields you need and let new ones pass.

### Codes and names

Error codes, fuel codes, country codes and station ids never change meaning. A new fuel gets a new code.

### Where changes are listed

Every change is on the [changelog](https://oilapi.net/documentation/changelog), newest first.

## Countries and regions

### Codes

Countries go by their two letter code in lower or upper case: `fr`, `GB`. [List countries](https://oilapi.net/documentation/countries) takes `region`: `europe`, `americas`, `asia_pacific`, `middle_east`, `africa`.

### Every country we price

| Code| Country| Region| What we hold| Since |
|---|---|---|---|---|
| `al`| [Albania](https://oilapi.net/prices/albania)| Europe| set prices| 2026 |
| `dz`| [Algeria](https://oilapi.net/prices/algeria)| Africa| set prices| 2026 |
| `ao`| [Angola](https://oilapi.net/prices/angola)| Africa| set prices| 2026 |
| `ag`| [Antigua and Barbuda](https://oilapi.net/prices/antigua-and-barbuda)| Americas| set prices| 2026 |
| `au`| [Australia](https://oilapi.net/prices/australia)| Asia Pacific| stations, averages| 2001 |
| `at`| [Austria](https://oilapi.net/prices/austria)| Europe| stations, averages, taxes| 2005 |
| `az`| [Azerbaijan](https://oilapi.net/prices/azerbaijan)| Europe| set prices| 2026 |
| `bh`| [Bahrain](https://oilapi.net/prices/bahrain)| Middle East| set prices| 2026 |
| `bd`| [Bangladesh](https://oilapi.net/prices/bangladesh)| Asia Pacific| set prices| 2026 |
| `bb`| [Barbados](https://oilapi.net/prices/barbados)| Americas| set prices| 2026 |
| `by`| [Belarus](https://oilapi.net/prices/belarus)| Europe| set prices| 2026 |
| `be`| [Belgium](https://oilapi.net/prices/belgium)| Europe| averages, set prices, taxes| 2005 |
| `bj`| [Benin](https://oilapi.net/prices/benin)| Africa| set prices| 2026 |
| `bt`| [Bhutan](https://oilapi.net/prices/bhutan)| Asia Pacific| set prices| 2026 |
| `bo`| [Bolivia](https://oilapi.net/prices/bolivia)| Americas| set prices| 2026 |
| `ba`| [Bosnia and Herzegovina](https://oilapi.net/prices/bosnia-and-herzegovina)| Europe| set prices| 2026 |
| `bw`| [Botswana](https://oilapi.net/prices/botswana)| Africa| set prices| 2026 |
| `br`| [Brazil](https://oilapi.net/prices/brazil)| Americas| stations| 2004 |
| `bg`| [Bulgaria](https://oilapi.net/prices/bulgaria)| Europe| averages, taxes| 2008 |
| `bf`| [Burkina Faso](https://oilapi.net/prices/burkina-faso)| Africa| set prices| 2026 |
| `bi`| [Burundi](https://oilapi.net/prices/burundi)| Africa| set prices| 2026 |
| `cv`| [Cabo Verde](https://oilapi.net/prices/cabo-verde)| Africa| set prices| 2026 |
| `kh`| [Cambodia](https://oilapi.net/prices/cambodia)| Asia Pacific| set prices| 2026 |
| `cm`| [Cameroon](https://oilapi.net/prices/cameroon)| Africa| set prices| 2026 |
| `ca`| [Canada](https://oilapi.net/prices/canada)| Americas| stations, averages| 1979 |
| `cf`| [Central African Republic](https://oilapi.net/prices/central-african-republic)| Africa| set prices| 2026 |
| `td`| [Chad](https://oilapi.net/prices/chad)| Africa| set prices| 2026 |
| `cn`| [China](https://oilapi.net/prices/china)| Asia Pacific| set prices| 2026 |
| `co`| [Colombia](https://oilapi.net/prices/colombia)| Americas| stations| 2022 |
| `km`| [Comoros](https://oilapi.net/prices/comoros)| Africa| set prices| 2026 |
| `cg`| [Congo](https://oilapi.net/prices/congo)| Africa| set prices| 2026 |
| `cr`| [Costa Rica](https://oilapi.net/prices/costa-rica)| Americas| set prices| 2026 |
| `hr`| [Croatia](https://oilapi.net/prices/croatia)| Europe| stations, averages, set prices, taxes| 2013 |
| `cy`| [Cyprus](https://oilapi.net/prices/cyprus)| Europe| averages, taxes| 2005 |
| `cz`| [Czechia](https://oilapi.net/prices/czechia)| Europe| averages, taxes| 2005 |
| `ci`| [Côte d'Ivoire](https://oilapi.net/prices/cote-divoire)| Africa| set prices| 2026 |
| `cd`| [DR Congo](https://oilapi.net/prices/dr-congo)| Africa| set prices| 2026 |
| `dk`| [Denmark](https://oilapi.net/prices/denmark)| Europe| averages, taxes| 2005 |
| `dj`| [Djibouti](https://oilapi.net/prices/djibouti)| Africa| set prices| 2026 |
| `dm`| [Dominica](https://oilapi.net/prices/dominica)| Americas| set prices| 2026 |
| `do`| [Dominican Republic](https://oilapi.net/prices/dominican-republic)| Americas| set prices| 2026 |
| `ec`| [Ecuador](https://oilapi.net/prices/ecuador)| Americas| set prices| 2026 |
| `eg`| [Egypt](https://oilapi.net/prices/egypt)| Africa| set prices| 2026 |
| `sv`| [El Salvador](https://oilapi.net/prices/el-salvador)| Americas| set prices| 2026 |
| `gq`| [Equatorial Guinea](https://oilapi.net/prices/equatorial-guinea)| Africa| set prices| 2026 |
| `ee`| [Estonia](https://oilapi.net/prices/estonia)| Europe| averages, taxes| 2005 |
| `sz`| [Eswatini](https://oilapi.net/prices/eswatini)| Africa| set prices| 2026 |
| `et`| [Ethiopia](https://oilapi.net/prices/ethiopia)| Africa| set prices| 2026 |
| `fj`| [Fiji](https://oilapi.net/prices/fiji)| Asia Pacific| set prices| 2026 |
| `fi`| [Finland](https://oilapi.net/prices/finland)| Europe| averages, taxes| 2005 |
| `fr`| [France](https://oilapi.net/prices/france)| Europe| stations, averages, taxes| 2005 |
| `ga`| [Gabon](https://oilapi.net/prices/gabon)| Africa| set prices| 2026 |
| `gm`| [Gambia](https://oilapi.net/prices/gambia)| Africa| set prices| 2026 |
| `ge`| [Georgia](https://oilapi.net/prices/georgia)| Europe| set prices| 2026 |
| `de`| [Germany](https://oilapi.net/prices/germany)| Europe| averages, taxes| 2005 |
| `gh`| [Ghana](https://oilapi.net/prices/ghana)| Africa| set prices| 2026 |
| `gr`| [Greece](https://oilapi.net/prices/greece)| Europe| averages, taxes| 2005 |
| `gt`| [Guatemala](https://oilapi.net/prices/guatemala)| Americas| set prices| 2026 |
| `gn`| [Guinea](https://oilapi.net/prices/guinea)| Africa| set prices| 2026 |
| `gy`| [Guyana](https://oilapi.net/prices/guyana)| Americas| set prices| 2026 |
| `ht`| [Haiti](https://oilapi.net/prices/haiti)| Americas| set prices| 2026 |
| `hn`| [Honduras](https://oilapi.net/prices/honduras)| Americas| set prices| 2026 |
| `hk`| [Hong Kong](https://oilapi.net/prices/hong-kong)| Asia Pacific| averages| 2026 |
| `hu`| [Hungary](https://oilapi.net/prices/hungary)| Europe| averages, taxes| 2005 |
| `in`| [India](https://oilapi.net/prices/india)| Asia Pacific| set prices| 2026 |
| `id`| [Indonesia](https://oilapi.net/prices/indonesia)| Asia Pacific| set prices| 2026 |
| `iq`| [Iraq](https://oilapi.net/prices/iraq)| Middle East| set prices| 2026 |
| `ie`| [Ireland](https://oilapi.net/prices/ireland)| Europe| averages, taxes| 2005 |
| `il`| [Israel](https://oilapi.net/prices/israel)| Middle East| set prices| 2026 |
| `it`| [Italy](https://oilapi.net/prices/italy)| Europe| averages, taxes| 2005 |
| `jp`| [Japan](https://oilapi.net/prices/japan)| Asia Pacific| averages, taxes| 1990 |
| `jo`| [Jordan](https://oilapi.net/prices/jordan)| Middle East| set prices| 2026 |
| `kz`| [Kazakhstan](https://oilapi.net/prices/kazakhstan)| Asia Pacific| set prices| 2026 |
| `ke`| [Kenya](https://oilapi.net/prices/kenya)| Africa| set prices| 2024 |
| `xk`| [Kosovo](https://oilapi.net/prices/kosovo)| Europe| averages| 2002 |
| `kw`| [Kuwait](https://oilapi.net/prices/kuwait)| Middle East| set prices| 2026 |
| `kg`| [Kyrgyzstan](https://oilapi.net/prices/kyrgyzstan)| Asia Pacific| set prices| 2026 |
| `la`| [Laos](https://oilapi.net/prices/laos)| Asia Pacific| set prices| 2026 |
| `lv`| [Latvia](https://oilapi.net/prices/latvia)| Europe| averages, taxes| 2005 |
| `lb`| [Lebanon](https://oilapi.net/prices/lebanon)| Middle East| set prices| 2010 |
| `ls`| [Lesotho](https://oilapi.net/prices/lesotho)| Africa| set prices| 2009 |
| `lr`| [Liberia](https://oilapi.net/prices/liberia)| Africa| set prices| 2026 |
| `lt`| [Lithuania](https://oilapi.net/prices/lithuania)| Europe| averages, taxes| 2005 |
| `lu`| [Luxembourg](https://oilapi.net/prices/luxembourg)| Europe| averages, set prices, taxes| 2005 |
| `mo`| [Macao](https://oilapi.net/prices/macao)| Asia Pacific| set prices| 2026 |
| `mg`| [Madagascar](https://oilapi.net/prices/madagascar)| Africa| set prices| 2026 |
| `mw`| [Malawi](https://oilapi.net/prices/malawi)| Africa| set prices| 2026 |
| `my`| [Malaysia](https://oilapi.net/prices/malaysia)| Asia Pacific| averages| 2017 |
| `mv`| [Maldives](https://oilapi.net/prices/maldives)| Asia Pacific| set prices| 2026 |
| `ml`| [Mali](https://oilapi.net/prices/mali)| Africa| set prices| 2026 |
| `mt`| [Malta](https://oilapi.net/prices/malta)| Europe| averages, set prices, taxes| 2005 |
| `mr`| [Mauritania](https://oilapi.net/prices/mauritania)| Africa| set prices| 2026 |
| `mu`| [Mauritius](https://oilapi.net/prices/mauritius)| Africa| set prices| 2011 |
| `mx`| [Mexico](https://oilapi.net/prices/mexico)| Americas| stations, averages| 2026 |
| `md`| [Moldova](https://oilapi.net/prices/moldova)| Europe| set prices| 2026 |
| `me`| [Montenegro](https://oilapi.net/prices/montenegro)| Europe| set prices| 2026 |
| `ma`| [Morocco](https://oilapi.net/prices/morocco)| Africa| set prices| 2026 |
| `mz`| [Mozambique](https://oilapi.net/prices/mozambique)| Africa| set prices| 2026 |
| `mm`| [Myanmar](https://oilapi.net/prices/myanmar)| Asia Pacific| set prices| 2026 |
| `na`| [Namibia](https://oilapi.net/prices/namibia)| Africa| set prices| 2026 |
| `np`| [Nepal](https://oilapi.net/prices/nepal)| Asia Pacific| set prices| 2026 |
| `nl`| [Netherlands](https://oilapi.net/prices/netherlands)| Europe| averages, taxes| 2005 |
| `ne`| [Niger](https://oilapi.net/prices/niger)| Africa| set prices| 2026 |
| `ng`| [Nigeria](https://oilapi.net/prices/nigeria)| Africa| set prices| 2026 |
| `mk`| [North Macedonia](https://oilapi.net/prices/north-macedonia)| Europe| set prices| 2026 |
| `no`| [Norway](https://oilapi.net/prices/norway)| Europe| averages| 1986 |
| `om`| [Oman](https://oilapi.net/prices/oman)| Middle East| set prices| 2026 |
| `pk`| [Pakistan](https://oilapi.net/prices/pakistan)| Asia Pacific| averages, set prices| 2006 |
| `ps`| [Palestine](https://oilapi.net/prices/palestine)| Middle East| set prices| 2026 |
| `pa`| [Panama](https://oilapi.net/prices/panama)| Americas| set prices| 2026 |
| `pg`| [Papua New Guinea](https://oilapi.net/prices/papua-new-guinea)| Asia Pacific| set prices| 2026 |
| `pe`| [Peru](https://oilapi.net/prices/peru)| Americas| averages| 2026 |
| `ph`| [Philippines](https://oilapi.net/prices/philippines)| Asia Pacific| set prices| 2026 |
| `pl`| [Poland](https://oilapi.net/prices/poland)| Europe| averages, taxes| 2005 |
| `pt`| [Portugal](https://oilapi.net/prices/portugal)| Europe| stations, averages, taxes| 2005 |
| `qa`| [Qatar](https://oilapi.net/prices/qatar)| Middle East| set prices| 2026 |
| `ro`| [Romania](https://oilapi.net/prices/romania)| Europe| averages, taxes| 2008 |
| `ru`| [Russia](https://oilapi.net/prices/russia)| Europe| set prices| 2026 |
| `rw`| [Rwanda](https://oilapi.net/prices/rwanda)| Africa| set prices| 2026 |
| `lc`| [Saint Lucia](https://oilapi.net/prices/saint-lucia)| Americas| set prices| 2026 |
| `vc`| [Saint Vincent and the Grenadines](https://oilapi.net/prices/saint-vincent-and-the-grenadines)| Americas| set prices| 2026 |
| `ws`| [Samoa](https://oilapi.net/prices/samoa)| Asia Pacific| set prices| 2026 |
| `sa`| [Saudi Arabia](https://oilapi.net/prices/saudi-arabia)| Middle East| set prices| 2026 |
| `sn`| [Senegal](https://oilapi.net/prices/senegal)| Africa| set prices| 2026 |
| `rs`| [Serbia](https://oilapi.net/prices/serbia)| Europe| set prices| 2026 |
| `sl`| [Sierra Leone](https://oilapi.net/prices/sierra-leone)| Africa| set prices| 2026 |
| `sg`| [Singapore](https://oilapi.net/prices/singapore)| Asia Pacific| averages| 2015 |
| `sk`| [Slovakia](https://oilapi.net/prices/slovakia)| Europe| averages, taxes| 2005 |
| `si`| [Slovenia](https://oilapi.net/prices/slovenia)| Europe| stations, averages, taxes| 2005 |
| `sb`| [Solomon Islands](https://oilapi.net/prices/solomon-islands)| Asia Pacific| set prices| 2026 |
| `za`| [South Africa](https://oilapi.net/prices/south-africa)| Africa| set prices, taxes| 2021 |
| `es`| [Spain](https://oilapi.net/prices/spain)| Europe| stations, averages, taxes| 2005 |
| `lk`| [Sri Lanka](https://oilapi.net/prices/sri-lanka)| Asia Pacific| set prices| 2026 |
| `sd`| [Sudan](https://oilapi.net/prices/sudan)| Africa| set prices| 2026 |
| `sr`| [Suriname](https://oilapi.net/prices/suriname)| Americas| set prices| 2026 |
| `se`| [Sweden](https://oilapi.net/prices/sweden)| Europe| averages, taxes| 2005 |
| `ch`| [Switzerland](https://oilapi.net/prices/switzerland)| Europe| averages| 1993 |
| `tw`| [Taiwan](https://oilapi.net/prices/taiwan)| Asia Pacific| averages| 1999 |
| `tz`| [Tanzania](https://oilapi.net/prices/tanzania)| Africa| set prices| 2026 |
| `th`| [Thailand](https://oilapi.net/prices/thailand)| Asia Pacific| averages, taxes| 2018 |
| `tl`| [Timor-Leste](https://oilapi.net/prices/timor-leste)| Asia Pacific| stations| 2026 |
| `tg`| [Togo](https://oilapi.net/prices/togo)| Africa| set prices| 2026 |
| `to`| [Tonga](https://oilapi.net/prices/tonga)| Asia Pacific| set prices| 2026 |
| `tt`| [Trinidad and Tobago](https://oilapi.net/prices/trinidad-and-tobago)| Americas| set prices| 2026 |
| `tn`| [Tunisia](https://oilapi.net/prices/tunisia)| Africa| set prices| 2026 |
| `tr`| [Türkiye](https://oilapi.net/prices/t-rkiye)| Europe| set prices| 2026 |
| `ug`| [Uganda](https://oilapi.net/prices/uganda)| Africa| set prices| 2026 |
| `ua`| [Ukraine](https://oilapi.net/prices/ukraine)| Europe| set prices| 2026 |
| `ae`| [United Arab Emirates](https://oilapi.net/prices/united-arab-emirates)| Middle East| set prices| 2026 |
| `gb`| [United Kingdom](https://oilapi.net/prices/united-kingdom)| Europe| stations, averages, taxes| 2003 |
| `us`| [United States](https://oilapi.net/prices/united-states)| Americas| averages| 1990 |
| `uy`| [Uruguay](https://oilapi.net/prices/uruguay)| Americas| set prices, taxes| 2022 |
| `uz`| [Uzbekistan](https://oilapi.net/prices/uzbekistan)| Asia Pacific| set prices| 2026 |
| `vu`| [Vanuatu](https://oilapi.net/prices/vanuatu)| Asia Pacific| set prices| 2026 |
| `vn`| [Vietnam](https://oilapi.net/prices/vietnam)| Asia Pacific| set prices| 2026 |
| `zm`| [Zambia](https://oilapi.net/prices/zambia)| Africa| set prices| 2026 |
| `zw`| [Zimbabwe](https://oilapi.net/prices/zimbabwe)| Africa| set prices| 2026 |

## Fuels and units

### Fuel codes

Use the code in `fuel` on any call. Each country sells its own set; [Get a country](https://oilapi.net/documentation/country) lists the ones we hold for it.

| Code| Name| What it is| Countries |
|---|---|---|---|
| `diesel`| Diesel| Road diesel, B7 or the local blend| 145 |
| `gasoline_95`| Petrol 95| Unleaded 95 RON| 64 |
| `gasoline`| Petrol| The country's standard petrol| 55 |
| `kerosene`| Kerosene| Lamp and heating kerosene| 36 |
| `heating_oil`| Heating oil| Heating oil for homes| 29 |
| `fuel_oil_high_sulphur`| Fuel oil high sulphur| Heavy fuel oil, high sulphur| 27 |
| `lpg`| LPG| Autogas| 22 |
| `gasoline_super`| Petrol super| Super grade petrol, usually 95 RON| 18 |
| `gasoline_92`| Petrol 92| 92 RON petrol| 12 |
| `fuel_oil_low_sulphur`| Fuel oil low sulphur| Heavy fuel oil, low sulphur| 10 |
| `gasoline_98`| Petrol 98| Premium unleaded 98 RON| 10 |
| `gasoline_regular`| Regular| Regular grade (87 AKI in North America)| 10 |
| `gasoline_premium`| Premium| Premium grade (91 to 93 AKI in North America)| 8 |
| `diesel_premium`| Diesel premium| Premium additised diesel| 6 |
| `lpg_autogas`| Lpg autogas| Autogas| 5 |
| `cng`| Cng| Compressed natural gas, a kilogram| 4 |
| `gasoline_91`| Petrol 91| Regular unleaded 91 RON| 4 |
| `lpg_household`| Lpg household| Bottled gas for homes| 4 |
| `e85`| E85| Up to 85% ethanol, for flex fuel engines| 3 |
| `gasoline_100`| Petrol 100| 100 RON premium petrol| 3 |
| `gasoline_95_e10`| Petrol 95 E10| 95 RON with up to 10% ethanol| 3 |
| `gasoline_95_premium`| Petrol 95 premium| Premium additised 95 RON| 3 |
| `gasoline_special`| Petrol special| Special grade petrol| 3 |
| `biodiesel`| Biodiesel| Biodiesel or a high biodiesel blend| 2 |
| `diesel_agricultural`| Diesel agricultural| Marked diesel for farm and off road use| 2 |
| `gasoline_90`| Petrol 90| 90 RON petrol| 2 |
| `gasoline_93`| Petrol 93| 93 RON petrol| 2 |
| `gasoline_97`| Petrol 97| 97 RON petrol| 2 |
| `gasoline_midgrade`| Petrol midgrade| Mid grade (89 AKI in North America)| 2 |
| `gasoline_super_95`| Petrol super 95| Super grade 95 RON| 2 |
| `cng_m3`| Cng m3| Compressed natural gas, a cubic metre| 2 |
| `biodiesel_b20`| Biodiesel b20| Diesel with up to 20% biodiesel| 1 |
| `diesel_0001s`| Diesel 0001s| Diesel with up to 0.001% sulphur| 1 |
| `diesel_005s`| Diesel 005s| Diesel with up to 0.05% sulphur| 1 |
| `diesel_20l`| Diesel 20l| | 1 |
| `diesel_auto`| Diesel auto| Road diesel| 1 |
| `diesel_b10`| Diesel b10| Diesel with up to 10% biodiesel| 1 |
| `diesel_b20`| Diesel b20| Diesel with up to 20% biodiesel| 1 |
| `diesel_b7`| Diesel b7| Diesel with up to 7% biodiesel| 1 |
| `diesel_blue`| Diesel blue| Marked diesel at a lower tax, for farms and boats| 1 |
| `diesel_dex`| Diesel dex| The top grade diesel| 1 |
| `diesel_dexlite`| Diesel dexlite| Mid grade diesel| 1 |
| `diesel_high_speed`| Diesel high speed| High speed diesel for road vehicles| 1 |
| `diesel_light`| Diesel light| Light diesel oil| 1 |
| `diesel_optimum`| Diesel optimum| Premium diesel| 1 |
| `diesel_regular`| Diesel regular| Regular road diesel| 1 |
| `diesel_renewable`| Diesel renewable| Renewable diesel (HVO)| 1 |
| `diesel_super`| Diesel super| Super grade diesel| 1 |
| `diesel_ulsd`| Diesel ulsd| Ultra low sulphur diesel| 1 |
| `gasohol`| Gasohol| Petrol with ethanol, usually 10%| 1 |
| `gasohol_91`| Gasohol 91| 91 RON with up to 10% ethanol| 1 |
| `gasohol_95`| Gasohol 95| 95 RON with up to 10% ethanol| 1 |
| `gasohol_95_premium`| Gasohol 95 premium| Premium 95 RON with up to 10% ethanol| 1 |
| `gasohol_e10_ron95_iii`| Gasohol e10 ron95 iii| 95 RON with up to 10% ethanol, Euro III standard| 1 |
| `gasohol_e10_ron95_v`| Gasohol e10 ron95 v| 95 RON with up to 10% ethanol, Euro V standard| 1 |
| `gasohol_e20`| Gasohol e20| Petrol with up to 20% ethanol| 1 |
| `gasohol_e5_ron92`| Gasohol e5 ron92| 92 RON with up to 5% ethanol| 1 |
| `gasohol_e85`| Gasohol e85| Up to 85% ethanol, for flex fuel engines| 1 |
| `gasoline_80`| Petrol 80| Low grade 80 RON petrol| 1 |
| `gasoline_95_20l`| Petrol 95 20l| | 1 |
| `gasoline_95_lrp`| Petrol 95 lrp| Lead replacement 95 RON, for older engines| 1 |
| `gasoline_98_20l`| Petrol 98 20l| | 1 |
| `gasoline_98_e10`| Petrol 98 e10| 98 RON with up to 10% ethanol| 1 |
| `gasoline_98_premium`| Petrol 98 premium| Premium additised 98 RON| 1 |
| `gasoline_99_premium`| Petrol 99 premium| Premium 99 RON| 1 |
| `gasoline_all_grades`| Petrol all grades| The average across every grade| 1 |
| `gasoline_e10`| E10| Petrol with up to 10% ethanol| 1 |
| `gasoline_ecopais`| Petrol ecopais| The standard national blend| 1 |
| `gasoline_eplus_91`| Petrol eplus 91| 91 RON, enhanced grade| 1 |
| `gasoline_extra`| Petrol extra| Extra grade, the higher of two grades| 1 |
| `gasoline_improved`| Petrol improved| Improved grade petrol| 1 |
| `gasoline_jayyid_91`| Petrol jayyid 91| 91 RON, the standard grade| 1 |
| `gasoline_lrp`| Petrol lrp| Lead replacement petrol, sold until the early 2000s| 1 |
| `gasoline_m91`| Petrol m91| 91 RON, as the country names it| 1 |
| `gasoline_m95`| Petrol m95| 95 RON, as the country names it| 1 |
| `gasoline_mumtaz_95`| Petrol mumtaz 95| 95 RON, the premium grade| 1 |
| `gasoline_octane`| Petrol octane| High octane grade| 1 |
| `gasoline_pertalite`| Petrol pertalite| 90 RON, the subsidised grade| 1 |
| `gasoline_pertamax`| Petrol pertamax| 92 RON, the non subsidised grade| 1 |
| `gasoline_pertamax_turbo`| Petrol pertamax turbo| 98 RON, the top grade| 1 |
| `gasoline_plus_91`| Petrol plus 91| 91 RON, plus grade| 1 |
| `gasoline_premium_91`| Petrol premium 91| Premium 91 RON| 1 |
| `gasoline_premium_97`| Petrol premium 97| Premium 97 RON| 1 |
| `gasoline_premium_full_service`| Petrol premium full service| Premium grade, attendant served| 1 |
| `gasoline_regular_full_service`| Petrol regular full service| Regular grade, attendant served| 1 |
| `gasoline_renewable`| Petrol renewable| Petrol made in part from renewable sources| 1 |
| `gasoline_special_95`| Petrol special 95| Special grade 95 RON| 1 |
| `gasoline_standard`| Petrol standard| Standard grade petrol| 1 |
| `gasoline_super_98`| Petrol super 98| Super grade 98 RON| 1 |
| `gasoline_two_stroke`| Petrol two stroke| Two stroke mix for small engines| 1 |
| `gasoline_ultra_98`| Petrol ultra 98| Top grade 98 RON| 1 |
| `gasoline_unleaded`| Petrol unleaded| Unleaded petrol| 1 |
| `lpg_autogas_station`| Lpg autogas station| Autogas at the pump| 1 |
| `lpg_butane_industrial`| Lpg butane industrial| Butane for industry| 1 |
| `lpg_cylinder_15kg`| Lpg cylinder 15kg| Bottled gas, a 15 kg cylinder| 1 |
| `lpg_propane_butane_industrial`| Lpg propane butane industrial| Propane and butane mix for industry| 1 |
| `lpg_propane_industrial`| Lpg propane industrial| Propane for industry| 1 |
| `marine_diesel_heavy`| Marine diesel heavy| Heavy marine diesel for ships| 1 |
| `marine_diesel_light`| Marine diesel light| Light marine diesel for boats| 1 |
| `propane`| Propane| Propane| 1 |
| `propane_residential`| Propane residential| Propane delivered to homes| 1 |
| `ethanol`| Ethanol| Hydrated ethanol sold at the pump| 1 |
| `lpg_kg`| Lpg kg| Bottled gas, a kilogram| 1 |
| `diesel_s50`| Diesel s50| Low sulphur diesel, 50 ppm| 1 |
| `diesel_s10`| Diesel s10| Ultra low sulphur diesel, 10 ppm| 1 |
| `bioethanol`| Bioethanol| Ethanol blend| 1 |
| `gasoline_regular_plain`| Petrol regular plain| Regular grade without ethanol| 1 |
| `diesel_bio_regular`| Diesel bio regular| Diesel with biodiesel| 1 |
| `gasoline_premium_plain`| Petrol premium plain| Premium grade without ethanol| 1 |
| `diesel_acem`| Diesel acem| Low sulphur diesel| 1 |
| `gasoline_regular_imported`| Petrol regular imported| Regular grade, imported| 1 |
| `diesel_bioacem`| Diesel bioacem| Low sulphur diesel with biodiesel| 1 |
| `diesel_acpm`| Diesel acpm| Standard diesel| 1 |
| `low_aromatic`| Low aromatic| Low aromatic petrol for remote areas| 1 |
| `e10`| E10| Petrol with up to 10% ethanol| 1 |
| `gasoline_additive`| Petrol additive| Petrol with a detergent additive| 1 |
| `gasoline_opal`| Petrol opal| Low aromatic petrol for remote areas| 1 |
| `gasoline_super_e5`| Super E5| 95 RON with up to 5% ethanol| 1 |
| `lng`| Lng| Liquefied natural gas, a kilogram| 1 |
| `diesel_hvo`| Diesel hvo| Renewable diesel (HVO)| 1 |

### Units

| Unit| Where |
|---|---|
| `litre`| Pump and station prices in nearly every country |
| `gallon`| US pump prices and US product benchmarks |
| `barrel`| Crude benchmarks: Brent and WTI |

### Converting

Add `currency=usd` (or any code) to convert every price at its own day's rate. The original price and currency stay beside it.

```
curl -G "https://api.oilapi.net/v1/prices/retail" \
  -d country=fr \
  -d currency=usd \
  -H "X-API-Key: YOUR_API_KEY"
```

## Currencies

### Converting a price

Add `currency` to any price call to convert every price at the rate of its own day; the answer keeps the original price and currency beside it.

### The rates

[Currency rates](https://oilapi.net/documentation/fx) gives units of a currency per US dollar. About 30 major currencies are daily; every other currency is quarterly, and a price in one of them is converted at the latest quarter's rate. The answer's `interval` says which.

```
curl -G "https://api.oilapi.net/v1/fx" \
  -d currency=eur \
  -d limit=30 \
  -H "X-API-Key: YOUR_API_KEY"
```

## Prices in today's money

### Restating a price

Add `real=latest` to a pump price, benchmark or series call, and every price is restated in the money of the newest month the country's consumer price index has. Or name a month, `real=2020-01`, to see every price in that month's money. Each point keeps the price as it was beside it, as `original`.

```
curl -G "https://api.oilapi.net/v1/prices/retail" \
  -d country=gb \
  -d fuel=diesel \
  -d from=2020-01-01 \
  -d real=latest \
  -H "X-API-Key: YOUR_API_KEY"
```

### How it is worked out

A price is multiplied by the index for the month you name and divided by the index for the price's own month. An index comes out some weeks after its month ends, so a price newer than the index uses its latest month; the answer's `meta.real` says which month the index reaches. Dollar benchmarks with no country, such as Brent, use the United States' index.

### With a currency

With `currency` as well, the price is restated in its own currency first, then converted at the rate of the month you name, not of each day, so the whole series reads in one month's money and one currency.

### The indexes

Every country's index is a series of its own, monthly, such as `cpi.gb`, in [Series values](https://oilapi.net/documentation/series-values). A country with no index answers `422 no_index`.

## Dates and times

### Formats

Dates are `YYYY-MM-DD`; times are ISO 8601 in UTC, such as `2026-10-28T03:12:09Z`.

### Ranges

`from` and `to` include both ends. Without `from`, a series call returns its most recent `limit` points.

### What each date means

| Field| Means |
|---|---|
| `changed_at`| When a station's price last changed; over 30 days ago, the price is marked `stale` |
| `effective_from`| When a set price took effect |
| `date`| The day a published average or close is for; a weekly point is dated its last day |
| `period`| The week, month or year an average covers |

## History

### Finding a series

Every series we hold is in [List series](https://oilapi.net/documentation/series) with its first and last date and how many points it has. Read one with [Series values](https://oilapi.net/documentation/series-values), giving `from` and `to`.

### How far back

Crude benchmarks go back to 1987, and pump prices as far as each country's record goes. How far your plan reads is on [plans and limits](https://oilapi.net/documentation/plans); the Analyst plan adds nightly bulk files.

## MCP server

### The address

The MCP server is at `https://oilapi.net/mcp`. It gives your assistant the tools on [MCP tools](https://oilapi.net/documentation/mcp-tools), and every call runs on your key, your plan and your limits.

### Claude and ChatGPT

Add a custom connector with the address above. Your assistant asks you to sign in with your OilAPI account and press Allow. No key to paste; the assistant gets a key of its own, which you can remove from [Keys](https://oilapi.net/account/keys).

### Claude Code

```
claude mcp add --transport http oilapi https://oilapi.net/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

### Cursor

```
{
    "mcpServers": {
        "oilapi": {
            "url": "https://oilapi.net/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
            }
        }
    }
}
```

### An example

Ask "cheapest diesel near the centre of Paris right now?" and the assistant calls `stations_near` with the point, the fuel and a radius, then answers from what comes back.

## Agent skill

### Use with Claude and agents

Download the skill: a short guide written for AI agents, with the base address, how to send the key, the calls that answer most questions, the limits and the errors. Save it as `~/.claude/skills/oilapi/SKILL.md`, or upload it as a skill in Claude's settings.

### Where agents find it

It is at `/.well-known/agent-skills/oilapi/SKILL.md`, listed in [the discovery index](https://oilapi.net/.well-known/agent-skills/index.json), and at [/skill.md](https://oilapi.net/skill.md).

### Everything else for agents

Point an agent at [the full manual](https://oilapi.net/documentation/manual.md), [llms.txt](https://oilapi.net/llms.txt) or [the OpenAPI file](https://oilapi.net/openapi.json).

## Changelog

| Date| What changed |
|---|---|
| 28 Oct 2026| The API opens: coverage, pump and set prices, stations near a point, benchmarks, every series, currencies and usage. |
| 28 Oct 2026| The MCP server at https://oilapi.net/mcp, with sign-in for Claude and ChatGPT connectors. |
| 28 Oct 2026| Set prices by town or zone: /v1/prices/set takes region. |
| 29 Oct 2026| Prices in today's money: real= on pump prices, benchmarks and series, with a monthly consumer price index for 190 countries. |
| 29 Oct 2026| US weekly supply: crude and product stocks, refinery runs, production, trade and products supplied, back to 1982. |
| 29 Oct 2026| New countries: Jamaica (weekly ex-refinery prices and taxes), Lebanon (set prices since 2010), Peru (daily national prices) and Timor-Leste (every station, daily). |
| 29 Oct 2026| Lesotho: set pump prices back through their history. |
| 29 Oct 2026| Canada, Ontario: weekly pump prices in 14 cities and the provincial averages since 1990, for petrol, diesel, auto propane and furnace oil. |
| 29 Oct 2026| Switzerland: monthly national petrol and diesel prices since 1993, and heating oil by delivery size since 2000. |
| 29 Oct 2026| Mauritius: set petrol and diesel prices since December 2011, from each pricing decision. |
| 29 Oct 2026| Pakistan: daily pump prices of petrol, high speed diesel, light diesel oil and kerosene since 2006, from each price change. |
| 29 Oct 2026| Uruguay: set retail petrol, diesel and kerosene prices by month since 2022, and ex-plant prices in the price structure. |
| 29 Oct 2026| Singapore: average retail prices of 98, 95 and 92 petrol, diesel and bottled gas, monthly since 2015. |
| 29 Oct 2026| OPEC reference basket: monthly averages since November 2024, kept current each month. |
| 29 Oct 2026| New Zealand: daily estimated cost of refined fuel with taxes for 91, 95 and diesel, since February 2026. |
| 29 Oct 2026| Lebanon: set petrol and diesel prices carried on monthly from November 2025, per 20 litres as the ministry states them. |
| 30 Oct 2026| Belgium: the official daily maximum prices of 95 and 98 petrol, diesel, LPG, heating gasoil by delivery size and kerosene, from October 2025 and kept each day. |
| 30 Oct 2026| Greece: daily average prices of 95 and 100 petrol, diesel, autogas and heating diesel in all 51 prefectures and nationally, filling back through history. |
| 30 Oct 2026| Kosovo: yearly average consumer prices of petrol and diesel, 2002 to 2024. |
| 30 Oct 2026| Peru: daily national median pump prices of every fuel and the 10 kg LPG cylinder since March 2026, now worked out from every outlet's reported price each day. |
| 30 Oct 2026| Queensland: every station price change now runs from December 2018 to August 2026, and carries on as each month is published. |
| 30 Oct 2026| Western Australia: every station's daily price since January 2001 (petrol 91, 95, 98 and 100, E10, E85, diesel, premium diesel, B20, LPG and the old lead replacement petrol), including the 220 or so regional stations that joined in May 2026. |
| 30 Oct 2026| Daily average pump prices worked out from every station's price in force: France and Spain since 2007, Western Australia since 2001, New South Wales since 2016 and Queensland since 2018, with Portugal, Croatia, Slovenia, Mexico and Quebec growing from their live prices; each with the number of stations it averages (retail.<place>.stations_daily.<fuel>, coverage.<place>.stations_daily.<fuel>). |
| 30 Oct 2026| Price breakdown for every EU country, petrol 95 and diesel, weekly since 2005: the crude oil cost, the refining margin and the distribution margin a litre, which with the taxes add up to the pump price (structure.<cc>.crude_cost, .refining, .distribution and .margin, then .<fuel>). |

v1 only ever gains fields: nothing is renamed or removed.

## Endpoints

### List countries: GET /v1/countries

Every country we price, what we hold for it and how far back it goes.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `region` | string | no | Only this region (one of: europe, americas, asia_pacific, middle_east, africa) |

Returns: `country` (string), `name` (string), `region` (string), `holds` (object), `fuels` (integer), `stations` (integer), `since` (integer), `cadence` (string), `last_change` (string)

Example: `GET /v1/countries?region=europe`

```json
{
    "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": 2030,
            "since": 2005,
            "cadence": "live",
            "last_change": "2026-10-29T22:47:00Z"
        },
        {
            "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
    }
}
```

### Get a country: GET /v1/countries/{country}

One country in full: every series we hold for it and its stations.

Returns: `country` (string), `name` (string), `stations` (integer), `series` (array)

Example: `GET /v1/countries/mx`

```json
{
    "data": {
        "country": "MX",
        "name": "Mexico",
        "stations": 13858,
        "series": [
            {
                "series": "coverage.mx.stations_daily.diesel",
                "name": "Mexico diesel, stations in the daily average",
                "family": "coverage",
                "product": "diesel",
                "country": "MX",
                "region": null,
                "market": "stations_count",
                "unit": "stations",
                "currency": "",
                "interval": "day",
                "first_date": "2026-10-22",
                "last_date": "2026-10-29",
                "points": 8
            },
            {
                "series": "coverage.mx.stations_daily.gasoline_premium",
                "name": "Mexico gasoline premium, stations in the daily average",
                "family": "coverage",
                "product": "gasoline_premium",
                "country": "MX",
                "region": null,
                "market": "stations_count",
                "unit": "stations",
                "currency": "",
                "interval": "day",
                "first_date": "2026-10-22",
                "last_date": "2026-10-29",
                "points": 8
            },
            {
                "series": "coverage.mx.stations_daily.gasoline_regular",
                "name": "Mexico gasoline regular, stations in the daily average",
                "family": "coverage",
                "product": "gasoline_regular",
                "country": "MX",
                "region": null,
                "market": "stations_count",
                "unit": "stations",
                "currency": "",
                "interval": "day",
                "first_date": "2026-10-22",
                "last_date": "2026-10-29",
                "points": 8
            }
        ]
    },
    "meta": {
        "count": 72
    }
}
```

### Pump prices: GET /v1/prices/retail

A country's pump prices: today's for each fuel, or one fuel over a range.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `country` | country | yes | Two letter country code, such as fr, gb or ke |
| `fuel` | string | no | One fuel, such as diesel or gasoline_95; leave out for every fuel now |
| `from` | date | no | First date, YYYY-MM-DD |
| `to` | date | no | Last date, YYYY-MM-DD |
| `interval` | string | no | Which published series to read when a country has more than one (one of: day, week, month) |
| `currency` | currency | no | Convert every price to this currency on its own day, such as usd |
| `real` | string | no | Restate every price in the money of one month with the country's consumer price index: latest, or a month as YYYY-MM such as 2020-01 |
| `limit` | integer | no | Most recent points when no from is given |

Returns: `country` (string), `fuel` (string), `interval` (string), `unit` (string), `currency` (string), `values` (array)

Example: `GET /v1/prices/retail?country=mx`

```json
{
    "data": {
        "country": "MX",
        "fuels": [
            {
                "fuel": "diesel",
                "kind": "average",
                "interval": "day",
                "date": "2026-10-29",
                "price": 26.9903,
                "unit": "litre",
                "currency": "MXN"
            },
            {
                "fuel": "gasoline_premium",
                "kind": "average",
                "interval": "day",
                "date": "2026-10-29",
                "price": 28.5914,
                "unit": "litre",
                "currency": "MXN"
            },
            {
                "fuel": "gasoline_regular",
                "kind": "average",
                "interval": "day",
                "date": "2026-10-29",
                "price": 23.6972,
                "unit": "litre",
                "currency": "MXN"
            }
        ]
    },
    "meta": {
        "count": 3
    }
}
```

### Government set prices: GET /v1/prices/set

Prices a government has fixed, as each level took effect.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `country` | country | yes | Two letter country code, such as fr, gb or ke |
| `region` | string | no | A town or zone, where prices are set by place; leave out for the national price or the fullest record |
| `date` | date | no | The prices in force on this date; leave out for now |
| `currency` | currency | no | Convert every price to this currency on its own day, such as usd |

Returns: `fuel` (string), `price` (number), `currency` (string), `unit` (string), `effective_from` (string), `previous` (number), `change` (number)

Example: `GET /v1/prices/set?country=hr`

```json
{
    "data": [
        {
            "fuel": "diesel_blue",
            "price": 1.38,
            "currency": "EUR",
            "unit": "litre",
            "effective_from": "2026-10-01",
            "previous": 0.84,
            "change": 0.54
        }
    ],
    "meta": {
        "count": 1,
        "as_of": "2026-10-29",
        "region": null
    }
}
```

### Find stations: GET /v1/stations

Stations near a point, or in a country, town or brand, with their prices.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `near` | point | no | latitude,longitude |
| `radius_km` | number | no | Radius around near, up to 25 km |
| `country` | country | no | Two letter country code, such as fr, gb or ke |
| `city` | string | no | Town or city name |
| `brand` | string | no | Brand name |
| `fuel` | string | no | Only stations selling this fuel, such as diesel |
| `sort` | string | no | distance (with near) or price (with fuel) (one of: distance, price) |
| `include_stale` | string | no | true also returns prices unchanged for over 30 days, marked stale (one of: true, false) |
| `currency` | currency | no | Convert every price to this currency on its own day, such as usd |

Returns: `id` (string), `brand` (string), `name` (string), `address` (string), `city` (string), `postcode` (string), `country` (string), `lat` (number), `lon` (number), `distance_km` (number), `prices` (array)

Example: `GET /v1/stations?near=48.8566,2.3522&radius_km=2&fuel=diesel&sort=price&per_page=2`

```json
{
    "data": [],
    "meta": {
        "count": 0,
        "next_cursor": null,
        "page": 1,
        "per_page": 2,
        "total": 0,
        "total_pages": 1,
        "next_page": null,
        "prev_page": null,
        "unit": "litre"
    }
}
```

### Get a station: GET /v1/stations/{id}

One station and every price it shows.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `currency` | currency | no | Convert every price to this currency on its own day, such as usd |

Returns: `id` (string), `brand` (string), `name` (string), `address` (string), `city` (string), `country` (string), `lat` (number), `lon` (number), `prices` (array)

### Station price history: GET /v1/stations/{id}/history

Every price change at one station.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `fuel` | string | no | One fuel; leave out for all |
| `from` | date | no | First date, YYYY-MM-DD |
| `to` | date | no | Last date, YYYY-MM-DD |
| `currency` | currency | no | Convert every price to this currency on its own day, such as usd |

Returns: `fuel` (string), `price` (number), `currency` (string), `changed_at` (string)

### List benchmarks: GET /v1/benchmarks

Crude and product benchmarks with their latest price.

Returns: `benchmark` (string), `name` (string), `unit` (string), `currency` (string), `price` (number), `date` (string)

Example: `GET /v1/benchmarks`

```json
{
    "data": [
        {
            "benchmark": "brent",
            "name": "Brent crude, spot",
            "unit": "barrel",
            "currency": "USD",
            "price": 123.1,
            "date": "2026-10-27",
            "since": "1987-05-20"
        },
        {
            "benchmark": "wti",
            "name": "WTI crude, Cushing spot",
            "unit": "barrel",
            "currency": "USD",
            "price": 103.37,
            "date": "2026-10-27",
            "since": "1986-01-02"
        },
        {
            "benchmark": "gasoline_nyh",
            "name": "Conventional gasoline, New York Harbor spot",
            "unit": "gallon",
            "currency": "USD",
            "price": 2.819,
            "date": "2026-10-27",
            "since": "1986-06-02"
        }
    ],
    "meta": {
        "count": 12
    }
}
```

### Benchmark history: GET /v1/benchmarks/{benchmark}

One benchmark day by day, or averaged by week, month or year.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `interval` | string | no | day, week, month or year (one of: day, week, month, year) |
| `from` | date | no | First date, YYYY-MM-DD |
| `to` | date | no | Last date, YYYY-MM-DD |
| `currency` | currency | no | Convert every price to this currency on its own day, such as usd |
| `real` | string | no | Restate every price in the money of one month with the country's consumer price index: latest, or a month as YYYY-MM such as 2020-01 |
| `limit` | integer | no | Most recent points when no from is given |

Returns: `benchmark` (string), `unit` (string), `currency` (string), `values` (array)

Example: `GET /v1/benchmarks/brent?interval=month&limit=3`

```json
{
    "data": {
        "benchmark": "brent",
        "name": "Brent crude, spot",
        "interval": "month",
        "unit": "barrel",
        "currency": "USD",
        "values": [
            {
                "period": "2026-08",
                "average": 91.076,
                "high": 96.92,
                "low": 86.47,
                "days": 20
            },
            {
                "period": "2026-09",
                "average": 114.1591,
                "high": 130.8,
                "low": 96.02,
                "days": 22
            },
            {
                "period": "2026-10",
                "average": 124.83,
                "high": 135.51,
                "low": 114.82,
                "days": 19
            }
        ]
    },
    "meta": {
        "count": 3
    }
}
```

### List series: GET /v1/series

Every series we hold: retail, set, wholesale, crude, supply and more, searchable.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `family` | string | no | retail, crude, refined, jet, marine, lpg, structure, tax, fundamentals, cpi, edible, lubricant |
| `country` | country | no | Two letter country code, such as fr, gb or ke |
| `product` | string | no | Product code, such as diesel |
| `q` | string | no | Words in the series name |

Returns: `series` (string), `name` (string), `family` (string), `product` (string), `country` (string), `unit` (string), `currency` (string), `interval` (string), `first_date` (string), `last_date` (string), `points` (integer)

Example: `GET /v1/series?family=crude&per_page=2`

```json
{
    "data": [
        {
            "series": "crude.average.monthly",
            "name": "Crude oil, average of Brent, Dubai and WTI, monthly",
            "family": "crude",
            "product": "crude_average",
            "country": null,
            "region": null,
            "market": "Monthly average",
            "unit": "barrel",
            "currency": "USD",
            "interval": "month",
            "first_date": "1960-01-01",
            "last_date": "2026-09-01",
            "points": 801
        },
        {
            "series": "crude.brent.europe",
            "name": "Brent crude oil, spot",
            "family": "crude",
            "product": "crude_brent",
            "country": null,
            "region": null,
            "market": "Europe",
            "unit": "barrel",
            "currency": "USD",
            "interval": "day",
            "first_date": "1987-05-20",
            "last_date": "2026-10-27",
            "points": 9117
        }
    ],
    "meta": {
        "count": 2,
        "next_cursor": "bzI",
        "page": 1,
        "per_page": 2,
        "total": 7,
        "total_pages": 4,
        "next_page": 2,
        "prev_page": null
    }
}
```

### Series values: GET /v1/series/{series}

One series, point by point.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `from` | date | no | First date, YYYY-MM-DD |
| `to` | date | no | Last date, YYYY-MM-DD |
| `currency` | currency | no | Convert every price to this currency on its own day, such as usd |
| `real` | string | no | Restate every price in the money of one month with the country's consumer price index: latest, or a month as YYYY-MM such as 2020-01 |
| `limit` | integer | no | Most recent points when no from is given |

Returns: `series` (string), `unit` (string), `currency` (string), `values` (array)

Example: `GET /v1/series/crude.brent.europe?limit=5`

```json
{
    "data": {
        "series": "crude.brent.europe",
        "name": "Brent crude oil, spot",
        "family": "crude",
        "product": "crude_brent",
        "country": null,
        "region": null,
        "market": "Europe",
        "unit": "barrel",
        "currency": "USD",
        "interval": "day",
        "first_date": "1987-05-20",
        "last_date": "2026-10-27",
        "points": 9117,
        "values": [
            {
                "date": "2026-10-21",
                "value": 117.37
            },
            {
                "date": "2026-10-22",
                "value": 125.39
            },
            {
                "date": "2026-10-23",
                "value": 128.3
            }
        ]
    },
    "meta": {
        "count": 5
    }
}
```

### Currency rates: GET /v1/fx

Units of a currency per US dollar, day by day.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `currency` | currency | yes | Convert every price to this currency on its own day, such as usd |
| `from` | date | no | First date, YYYY-MM-DD |
| `to` | date | no | Last date, YYYY-MM-DD |
| `limit` | integer | no | Most recent days when no from is given |

Returns: `currency` (string), `values` (array)

Example: `GET /v1/fx?currency=eur&limit=3`

```json
{
    "data": {
        "currency": "EUR",
        "interval": "day",
        "values": [
            {
                "date": "2026-10-27",
                "per_usd": 0.89686098654709
            },
            {
                "date": "2026-10-28",
                "per_usd": 0.89823048594269
            },
            {
                "date": "2026-10-29",
                "per_usd": 0.8984725965858
            }
        ]
    },
    "meta": {
        "count": 3
    }
}
```

### Your usage: GET /v1/usage

Your plan, your calls today and your limits; does not count against them.

Returns: `plan` (string), `calls_today` (integer), `calls_month` (integer), `limits` (object), `reads` (object)

Example: `GET /v1/usage`

```json
{
    "data": {
        "plan": "Free key",
        "calls_today": 12,
        "calls_month": 214,
        "limits": {
            "calls_a_day": 50,
            "calls_a_minute": 10,
            "day_resets_at": "2026-10-30T00:00:00Z"
        },
        "reads": {
            "prices_up_to": "the end of yesterday (UTC)",
            "history_from": "2026-09-29"
        }
    },
    "meta": []
}
```

## Recipes

### Cheapest fuel near a user

The five cheapest diesel stations within 3 km of a point, with how fresh each price is.

1. Ask for stations near the point, cheapest first. Give the point, a radius and the fuel, and sort by price. Each station comes with its price and when it last changed.

```
curl -G "https://api.oilapi.net/v1/stations" \
  -d near=48.8566,2.3522 \
  -d radius_km=3 \
  -d fuel=diesel \
  -d sort=price \
  -d per_page=5 \
  -H "X-API-Key: YOUR_API_KEY"
```

2. Show how fresh each price is. Every price carries changed_at. Show "changed 12 minutes ago" so people trust the number. A price unchanged for over 30 days is left out, since the station has most likely closed; add include_stale=true to see those too, each marked stale.

3. Open one station. When someone taps a station, read it by its id for every fuel it sells.

```
curl "https://api.oilapi.net/v1/stations/st_7qk3m2xa" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Track a country's prices

Today's pump prices for a country, then one fuel's history to chart.

1. Read every fuel now. Leave out fuel to get each fuel the country publishes, with its date and whether it is an average or a set price.

```
curl -G "https://api.oilapi.net/v1/prices/retail" \
  -d country=de \
  -H "X-API-Key: YOUR_API_KEY"
```

2. Read one fuel over time. Give a fuel and a start date for every point since; the answer says how often the country publishes.

```
curl -G "https://api.oilapi.net/v1/prices/retail" \
  -d country=de \
  -d fuel=diesel \
  -d from=2024-01-01 \
  -H "X-API-Key: YOUR_API_KEY"
```

3. Keep it current. Call again once a day, or as often as the interval in the answer; points never change once published.

### Compare countries in dollars

Put any countries side by side in US dollars a litre, each at its own day's rate.

1. Ask each country in dollars. Add currency=usd. Each price converts at its own day's rate, with the original beside it.

```
curl -G "https://api.oilapi.net/v1/prices/retail" \
  -d country=fr \
  -d currency=usd \
  -H "X-API-Key: YOUR_API_KEY"
```

2. Compare per litre. Prices come per litre almost everywhere; where a country prices by the gallon the answer says so in unit.

3. See the rates themselves. Currency rates gives units per US dollar day by day, if you would rather convert yourself.

```
curl -G "https://api.oilapi.net/v1/fx" \
  -d currency=eur \
  -d limit=30 \
  -H "X-API-Key: YOUR_API_KEY"
```

### Crude against the pump

Brent by month next to a country's pump price, to see how much of a litre is crude.

1. Brent, averaged by month. Benchmark history averages by week, month or year, with the high and low of each.

```
curl -G "https://api.oilapi.net/v1/benchmarks/brent" \
  -d interval=month \
  -d from=2020-01-01 \
  -H "X-API-Key: YOUR_API_KEY"
```

2. The pump price, in dollars. Ask the country's price over the same months in US dollars.

```
curl -G "https://api.oilapi.net/v1/prices/retail" \
  -d country=gb \
  -d fuel=diesel \
  -d from=2020-01-01 \
  -d currency=usd \
  -H "X-API-Key: YOUR_API_KEY"
```

3. Put them on one scale. A barrel is 158.99 litres: divide Brent by it for the crude in each litre. The rest is tax, refining, transport and margin.

## MCP tools

Server: https://oilapi.net/mcp (JSON-RPC over HTTP POST; Bearer key, or OAuth sign-in for Claude and ChatGPT connectors).

- `coverage`: Every country we price, what we hold for it and how far back it goes. Calls `GET /v1/countries`.
- `price_now`: A country's pump prices: today's for each fuel, or one fuel over a range. Calls `GET /v1/prices/retail`.
- `set_prices`: Prices a government has fixed, as each level took effect. Calls `GET /v1/prices/set`.
- `stations_near`: Stations near a point, or in a country, town or brand, with their prices. Calls `GET /v1/stations`.
- `benchmarks`: Crude and product benchmarks with their latest price. Calls `GET /v1/benchmarks`.
- `price_history`: One benchmark day by day, or averaged by week, month or year. Calls `GET /v1/benchmarks/{benchmark}`.
- `convert`: Units of a currency per US dollar, day by day. Calls `GET /v1/fx`.