Oil price API: find stations

Find stations

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

GEThttps://api.oilapi.net/v1/stations

PlansEvery plan

Cost1 call per request

ReturnsPaged, 50 a page

UpdatedLive, as stations change

What it is for

Stations near a point, or in a country, town or brand, each with every fuel's latest price, when it changed and whether it is stale.

near with radius_km finds stations around a point, nearest first; fuel with sort=price finds the cheapest. Prices unchanged for over 30 days are left out unless include_stale=true.

Good for

The cheapest fuel nearby
Station maps
Comparing brands in a town
Store locators

Also the MCP tool stations_near

Parameters 9 in the query

Name	Where and type	Required	What it does	Example
`near`	query point	optional	latitude,longitude.	`48.8566,2.3522`
`radius_km`	query number	default 5	Radius around near, up to 25 km. Up to 25.	`2`
`country`	query country	optional	Two letter country code, such as fr, gb or ke.	`fr`
`city`	query string	optional	Town or city name.	`Lyon`
`brand`	query string	optional	Brand name.	`TotalEnergies`
`fuel`	query string	optional	Only stations selling this fuel, such as diesel.	`diesel`
`sort`	query one of	optional	distance (with near) or price (with fuel). One of `distance`, `price`.	`price`
`include_stale`	query one of	default false	true also returns prices unchanged for over 30 days, marked stale. One of `true`, `false`.
`currency`	query ISO 4217	optional	Convert every price to this currency on its own day, such as usd.	`usd`
`page, per_page, cursor`	query paging	default 1, 50	See Pagination.	`per_page=100`

Try it runs against the live API with your key

Your API key

No key yet? Get a free one; it is saved in this browser for every page.

near pointlatitude,longituderadius_km numberRadius around near, up to 25 kmcountry countryTwo letter country code, such as fr, gb or kecity stringTown or city namebrand stringBrand namefuel stringOnly stations selling this fuel, such as dieselsort one ofdistance (with near) or price (with fuel)include_stale one oftrue also returns prices unchanged for over 30 days, marked stalecurrency ISO 4217Convert every price to this currency on its own day, such as usd

The answer 200, application/json

Field	Type	What it holds
`id`	string	Our id for the station; it never changes
`brand`	string	The brand, or the name when there is none
`name`	string	Our name for it
`address`	string	Street address
`city`	string	Town or city
`postcode`	string	Postcode
`country`	string	Two letter country code
`lat`	number	Latitude
`lon`	number	Longitude
`distance_km`	number	Distance from near, when given
`prices`	array	Each fuel: price, currency, unit, changed_at and stale

Example answer real, from what we hold now; long lists cut to three

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

{
    "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"
    }
}

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.

Get a stationOne station and every price it shows.GET /v1/stations/{id}Station price historyEvery price change at one station.GET /v1/stations/{id}/history Cheapest fuel near a userThe five cheapest diesel stations within 3 km of a point, with how fresh each price is.Recipe