--- name: oilapi description: Read oil and fuel prices with OilAPI: pump prices and government set prices by country, the cheapest stations near a point, and crude and product benchmarks back to 1987. Use when a task needs a fuel or oil price, a price history, or stations near a place. --- # OilAPI OilAPI gives oil and fuel prices for every country it can read: each country's pump prices, the prices governments set, every station's price where a country publishes them, and crude and product benchmarks back to 1987. It is run by DeveloperData.net. ## When to use it - Use it for a fuel or oil price now or in the past, a comparison between countries, or the cheapest stations near a place. - Do not use it for oil company finances, futures prices or shipping. It holds prices, not news. ## Access - A free key comes with an account at https://oilapi.net/signup (sign in with Google; no card). - Base address `https://api.oilapi.net/v1`. Send the key in a header: `X-API-Key: ` or `Authorization: Bearer `. A key in the address is refused. - Every answer is `{"data": ..., "meta": {...}}`. ## The calls that answer most questions ### What we hold for each country ``` curl -G "https://api.oilapi.net/v1/countries" \ -d region=europe \ -H "X-API-Key: YOUR_API_KEY" ``` ```json { "data": [ { "country": "AT", "name": "Austria", "region": "europe", "holds": { "stations": true, "pump_averages": true, "set_prices": false, "taxes": true }, "fuels": 5, "stations": 2003, "since": 2005, "cadence": "live", "last_change": "2026-10-28T22:47:02Z" } ], "meta": { "count": 37 } } ``` ### A country's pump prices now ``` curl -G "https://api.oilapi.net/v1/prices/retail" \ -d country=fr \ -H "X-API-Key: YOUR_API_KEY" ``` ```json { "data": { "country": "ES", "fuels": [ { "fuel": "diesel", "kind": "average", "interval": "week", "date": "2026-10-19", "price": 1.88922125, "unit": "litre", "currency": "EUR" }, { "fuel": "fuel_oil_high_sulphur", "kind": "average", "interval": "week", "date": "2026-10-19", "price": 661.21, "unit": "tonne", "currency": "EUR" }, { "fuel": "gasoline_95", "kind": "average", "interval": "week", "date": "2026-10-19", "price": 1.780474317, "unit": "litre", "currency": "EUR" } ] }, "meta": { "count": 5 } } ``` Add `fuel` and `from` for one fuel's history, and `currency=usd` to compare countries. ### Prices a government sets ``` curl -G "https://api.oilapi.net/v1/prices/set" \ -d country=ke \ -H "X-API-Key: YOUR_API_KEY" ``` ```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-28", "region": null } } ``` Where prices are set by town or zone, add `region`. ### The cheapest stations near a point ``` curl -G "https://api.oilapi.net/v1/stations" \ -d near=48.8566,2.3522 -d radius_km=3 -d fuel=diesel -d sort=price \ -H "X-API-Key: YOUR_API_KEY" ``` ```json { "data": [ { "id": "st_gtydfc3d", "brand": null, "name": null, "address": "8,10,10bis Rue Bailleul", "city": "Paris", "postcode": "75001", "region": null, "country": "FR", "lat": 48.861, "lon": 2.341, "distance_km": 0.95, "prices": [ { "fuel": "diesel", "price": 2.68, "currency": "EUR", "unit": "litre", "changed_at": "2026-10-06T15:57:24Z", "stale": false } ] } ], "meta": { "count": 1, "next_cursor": null, "page": 1, "per_page": 2, "total": 1, "total_pages": 1, "next_page": null, "prev_page": null, "unit": "litre" } } ``` ### Brent and the other benchmarks ``` curl -G "https://api.oilapi.net/v1/benchmarks/brent" \ -d interval=month -d limit=3 \ -H "X-API-Key: YOUR_API_KEY" ``` ```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 } } ``` ## MCP server `https://oilapi.net/mcp`, with sign-in for Claude and ChatGPT connectors or the key as a Bearer header. Tools: `coverage`, `price_now`, `set_prices`, `stations_near`, `benchmarks`, `price_history`, `convert`. ## Limits - The free key: 50 calls a day, 10 a minute, prices as they stood at the end of yesterday (UTC), 30 days of history. - Paid plans read today's prices and further back; `meta.delayed_to` and `meta.history_from` say when a plan held something back. - Every answer carries `X-RateLimit-Remaining` and `X-Quota-Remaining`. Times are UTC. ## Errors `{"error": {"code": "...", "message": "...", "docs": "..."}}` with the status: - 400 `bad_request`, 422 `unknown_parameter`: fix the call as the message says. - 401 `unauthorized`: no key, or not a valid one. - 404 `not_found`: no such record; an empty list is a 200. - 429 `rate_limited` or `quota_exceeded`: wait for `Retry-After`, do not retry at once. ## A typical workflow 1. Call `/v1/countries` to see what is held for the country and how far back it goes. 2. Call `/v1/prices/retail` (or `/v1/prices/set` for a set price country) for the price now. 3. For a place, call `/v1/stations` with `near`, `fuel` and `sort=price`. 4. Add `currency=usd` when comparing countries, and say which unit and date each price is for. 5. If `meta` says the plan held something back, tell the person rather than guessing. The full manual: https://oilapi.net/documentation/manual.md