# OilAPI

> Oil and fuel price API: pump prices by country, government set prices, every station where a country publishes them, and crude and product benchmarks back to 1987. JSON over HTTPS, key in a header, MCP server for AI assistants.

- [The full manual](https://oilapi.net/documentation/manual.md): every endpoint, parameter, field and an example answer
- [Agent skill](https://oilapi.net/skill.md)
- [OpenAPI](https://oilapi.net/openapi.json)
- [MCP server](https://oilapi.net/mcp)

## Endpoints

- [List countries, GET /v1/countries](https://oilapi.net/documentation/countries): Every country we price, what we hold for it and how far back it goes
- [Get a country, GET /v1/countries/{country}](https://oilapi.net/documentation/country): One country in full: every series we hold for it and its stations
- [Pump prices, GET /v1/prices/retail](https://oilapi.net/documentation/prices-retail): A country's pump prices: today's for each fuel, or one fuel over a range
- [Government set prices, GET /v1/prices/set](https://oilapi.net/documentation/prices-set): Prices a government has fixed, as each level took effect
- [Find stations, GET /v1/stations](https://oilapi.net/documentation/stations): Stations near a point, or in a country, town or brand, with their prices
- [Get a station, GET /v1/stations/{id}](https://oilapi.net/documentation/station): One station and every price it shows
- [Station price history, GET /v1/stations/{id}/history](https://oilapi.net/documentation/station-history): Every price change at one station
- [List benchmarks, GET /v1/benchmarks](https://oilapi.net/documentation/benchmarks): Crude and product benchmarks with their latest price
- [Benchmark history, GET /v1/benchmarks/{benchmark}](https://oilapi.net/documentation/benchmark): One benchmark day by day, or averaged by week, month or year
- [List series, GET /v1/series](https://oilapi.net/documentation/series): Every series we hold: retail, set, wholesale, crude, supply and more, searchable
- [Series values, GET /v1/series/{series}](https://oilapi.net/documentation/series-values): One series, point by point
- [Currency rates, GET /v1/fx](https://oilapi.net/documentation/fx): Units of a currency per US dollar, day by day
- [Your usage, GET /v1/usage](https://oilapi.net/documentation/usage): Your plan, your calls today and your limits; does not count against them

## Agent skill

- [OilAPI agent skill](https://oilapi.net/.well-known/agent-skills/oilapi/SKILL.md): how agents use OilAPI. Index: https://oilapi.net/.well-known/agent-skills/index.json

## Recipes

- [Cheapest fuel near a user](https://oilapi.net/documentation/cheapest-fuel-near-a-user): The five cheapest diesel stations within 3 km of a point, with how fresh each price is.
- [Track a country's prices](https://oilapi.net/documentation/track-a-countrys-prices): Today's pump prices for a country, then one fuel's history to chart.
- [Compare countries in dollars](https://oilapi.net/documentation/compare-countries-in-dollars): Put any countries side by side in US dollars a litre, each at its own day's rate.
- [Crude against the pump](https://oilapi.net/documentation/crude-against-the-pump): Brent by month next to a country's pump price, to see how much of a litre is crude.

## Guides

- [Quick start](https://oilapi.net/documentation/quick-start): A key, your first call and the answer, in one minute.
- [Authentication](https://oilapi.net/documentation/authentication): Your key, the two ways to send it, and rotating it.
- [Plans and limits](https://oilapi.net/documentation/plans): What each plan reads, and its limits.
- [Rate limits](https://oilapi.net/documentation/rate-limits): Calls a minute, calls a day, and the headers that say where you are.
- [Errors](https://oilapi.net/documentation/errors): Every error code, and what to do about it.
- [Pagination](https://oilapi.net/documentation/pagination): page or cursor, and what meta tells you.
- [Versioning](https://oilapi.net/documentation/versioning): v1 only ever gains fields; what that means for your code.
- [Countries and regions](https://oilapi.net/documentation/countries-and-regions): Country codes, the five regions, and what we hold for each.
- [Fuels and units](https://oilapi.net/documentation/fuels-and-units): Every fuel code, and the units prices come in.
- [Currencies](https://oilapi.net/documentation/currencies): Converting any price, and the rates themselves.
- [Prices in today's money](https://oilapi.net/documentation/todays-money): Any price restated in one month's money, with the country's consumer price index.
- [Dates and times](https://oilapi.net/documentation/dates-and-times): Every date and time is UTC; how ranges and freshness work.
- [History](https://oilapi.net/documentation/history): How far back each series goes, and reading long ranges.
- [MCP server](https://oilapi.net/documentation/mcp): OilAPI inside Claude, ChatGPT, Cursor and Claude Code.
- [MCP tools](https://oilapi.net/documentation/mcp-tools): Every tool the MCP server gives, and the endpoint each calls.
- [Agent skill](https://oilapi.net/documentation/agent-skill): Use with Claude and agents: a SKILL.md that teaches an agent to use OilAPI.
- [API reference](https://oilapi.net/documentation/api-reference): Every endpoint, grouped, with what it takes and returns.
- [Changelog](https://oilapi.net/documentation/changelog): What changed, and when.