{ "openapi": "3.1.0", "info": { "title": "OilAPI", "version": "1.0.0", "description": "Oil and fuel prices: pump prices, set prices, stations and benchmarks." }, "servers": [ { "url": "https://api.oilapi.net" } ], "security": [ { "key": [] }, { "bearer": [] } ], "paths": { "/v1/countries": { "get": { "operationId": "countries", "summary": "Every country we price, what we hold for it and how far back it goes", "tags": [ "Coverage" ], "parameters": [ { "name": "region", "in": "query", "required": false, "description": "Only this region", "schema": { "type": "string", "enum": [ "europe", "americas", "asia_pacific", "middle_east", "africa" ] } } ], "externalDocs": { "url": "https://oilapi.net/documentation/countries" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/countries/{country}": { "get": { "operationId": "country", "summary": "One country in full: every series we hold for it and its stations", "tags": [ "Coverage" ], "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" } } ], "externalDocs": { "url": "https://oilapi.net/documentation/country" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/prices/retail": { "get": { "operationId": "prices_retail", "summary": "A country's pump prices: today's for each fuel, or one fuel over a range", "tags": [ "Prices" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Two letter country code, such as fr, gb or ke", "schema": { "type": "string" } }, { "name": "fuel", "in": "query", "required": false, "description": "One fuel, such as diesel or gasoline_95; leave out for every fuel now", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "interval", "in": "query", "required": false, "description": "Which published series to read when a country has more than one", "schema": { "type": "string", "enum": [ "day", "week", "month" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } }, { "name": "real", "in": "query", "required": false, "description": "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", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Most recent points when no from is given", "schema": { "type": "integer", "default": 100 } } ], "externalDocs": { "url": "https://oilapi.net/documentation/prices-retail" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/prices/set": { "get": { "operationId": "prices_set", "summary": "Prices a government has fixed, as each level took effect", "tags": [ "Prices" ], "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Two letter country code, such as fr, gb or ke", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "A town or zone, where prices are set by place; leave out for the national price or the fullest record", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "The prices in force on this date; leave out for now", "schema": { "type": "string", "format": "date" } }, { "name": "currency", "in": "query", "required": false, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://oilapi.net/documentation/prices-set" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/stations": { "get": { "operationId": "stations", "summary": "Stations near a point, or in a country, town or brand, with their prices", "tags": [ "Stations" ], "parameters": [ { "name": "near", "in": "query", "required": false, "description": "latitude,longitude", "schema": { "type": "string" } }, { "name": "radius_km", "in": "query", "required": false, "description": "Radius around near, up to 25 km", "schema": { "type": "number", "default": 5 } }, { "name": "country", "in": "query", "required": false, "description": "Two letter country code, such as fr, gb or ke", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "Town or city name", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Brand name", "schema": { "type": "string" } }, { "name": "fuel", "in": "query", "required": false, "description": "Only stations selling this fuel, such as diesel", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "distance (with near) or price (with fuel)", "schema": { "type": "string", "enum": [ "distance", "price" ] } }, { "name": "include_stale", "in": "query", "required": false, "description": "true also returns prices unchanged for over 30 days, marked stale", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "currency", "in": "query", "required": false, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://oilapi.net/documentation/stations" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/stations/{id}": { "get": { "operationId": "station", "summary": "One station and every price it shows", "tags": [ "Stations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://oilapi.net/documentation/station" }, "responses": { "200": { "description": "OK", "content": { "application/json": {} } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/stations/{id}/history": { "get": { "operationId": "station_history", "summary": "Every price change at one station", "tags": [ "Stations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fuel", "in": "query", "required": false, "description": "One fuel; leave out for all", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "currency", "in": "query", "required": false, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://oilapi.net/documentation/station-history" }, "responses": { "200": { "description": "OK", "content": { "application/json": {} } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/benchmarks": { "get": { "operationId": "benchmarks", "summary": "Crude and product benchmarks with their latest price", "tags": [ "Markets" ], "parameters": [], "externalDocs": { "url": "https://oilapi.net/documentation/benchmarks" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/benchmarks/{benchmark}": { "get": { "operationId": "benchmark", "summary": "One benchmark day by day, or averaged by week, month or year", "tags": [ "Markets" ], "parameters": [ { "name": "benchmark", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "interval", "in": "query", "required": false, "description": "day, week, month or year", "schema": { "type": "string", "enum": [ "day", "week", "month", "year" ], "default": "day" } }, { "name": "from", "in": "query", "required": false, "description": "First date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "currency", "in": "query", "required": false, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } }, { "name": "real", "in": "query", "required": false, "description": "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", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Most recent points when no from is given", "schema": { "type": "integer", "default": 100 } } ], "externalDocs": { "url": "https://oilapi.net/documentation/benchmark" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/series": { "get": { "operationId": "series", "summary": "Every series we hold: retail, set, wholesale, crude, supply and more, searchable", "tags": [ "Series" ], "parameters": [ { "name": "family", "in": "query", "required": false, "description": "retail, crude, refined, jet, marine, lpg, structure, tax, fundamentals, cpi, edible, lubricant", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Two letter country code, such as fr, gb or ke", "schema": { "type": "string" } }, { "name": "product", "in": "query", "required": false, "description": "Product code, such as diesel", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Words in the series name", "schema": { "type": "string" } } ], "externalDocs": { "url": "https://oilapi.net/documentation/series" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/series/{series}": { "get": { "operationId": "series_values", "summary": "One series, point by point", "tags": [ "Series" ], "parameters": [ { "name": "series", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "currency", "in": "query", "required": false, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } }, { "name": "real", "in": "query", "required": false, "description": "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", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Most recent points when no from is given", "schema": { "type": "integer", "default": 100 } } ], "externalDocs": { "url": "https://oilapi.net/documentation/series-values" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/fx": { "get": { "operationId": "fx", "summary": "Units of a currency per US dollar, day by day", "tags": [ "Markets" ], "parameters": [ { "name": "currency", "in": "query", "required": true, "description": "Convert every price to this currency on its own day, such as usd", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last date, YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Most recent days when no from is given", "schema": { "type": "integer", "default": 30 } } ], "externalDocs": { "url": "https://oilapi.net/documentation/fx" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/usage": { "get": { "operationId": "usage", "summary": "Your plan, your calls today and your limits; does not count against them", "tags": [ "Account" ], "parameters": [], "externalDocs": { "url": "https://oilapi.net/documentation/usage" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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": [] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "key": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "bearer": { "type": "http", "scheme": "bearer" } }, "responses": { "Error": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "plan": { "type": "string" }, "docs": { "type": "string" } } } } } } } } } } }