ocu.org APIwww.ocu.org ↗
Search gas stations across Spain with real-time fuel prices, coordinates, and distance. Filter by fuel type, brand, and radius via the OCU API.
curl -X GET 'https://api.parse.bot/scraper/546672d3-429f-480d-9229-2d3a739ca054/search_stations?address=Madrid&fuel_type=diesel&radius_km=10' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for gas stations near a location in Spain. Returns real-time fuel prices, station details, coordinates, and distance. Stations are sorted by price (cheapest first). Results are paginated.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-based) for pagination |
| brand | string | Filter by brand code. Empty string for all brands. |
| addressrequired | string | Address, city name, or postal code in Spain (e.g. '28001', 'Madrid', 'Barcelona') |
| fuel_type | string | Fuel type to search for. Accepted values: gasolina_95, gasolina_98, diesel, diesel_premium, glp. Raw codes also accepted: GPR, G98, GOA, GPD, GLP. |
| radius_km | integer | Search radius in kilometers (1-50) |
| tank_capacity | integer | Tank capacity in liters for total cost calculation |
{
"type": "object",
"fields": {
"address": "string - Resolved full address from geocoding",
"latitude": "number - Search center latitude",
"stations": "array of station objects with brand, name, latitude, longitude, distance_km, price_per_liter, price_rating, total_cost_per_tank, street_address, logo_url, directions_url",
"fuel_code": "string - Internal fuel code (e.g. GPR, GOA)",
"fuel_type": "string - Fuel type used in the search",
"longitude": "number - Search center longitude",
"radius_km": "integer - Search radius used",
"postal_code": "string - Postal code of the resolved address",
"total_stations": "integer - Number of stations returned",
"tank_capacity_liters": "integer - Tank capacity used for cost calculation"
},
"sample": {
"data": {
"address": "Madrid, España",
"latitude": 40.4167279,
"stations": [
{
"name": "BALLENOIL (1)",
"brand": "BALLENOIL",
"latitude": 40.41025,
"logo_url": "https://www.ocu.org/-/media/ocu/images/calculators/logo-ballenoil.svg?rev=98af5dee-5c33-4f74-b731-2aa152b4a8eb",
"longitude": -3.717528,
"distance_km": 1.41,
"price_rating": "good",
"directions_url": "https://maps.google.com?daddr=40.41025,-3.717528&dirflg=d",
"street_address": "RONDA SEGOVIA, 37",
"price_per_liter": 1.598,
"total_cost_per_tank": 47.94
}
],
"fuel_code": "GOA",
"fuel_type": "diesel",
"longitude": -3.7032905,
"radius_km": 10,
"postal_code": "",
"total_stations": 205,
"tank_capacity_liters": 30
},
"status": "success"
}
}About the ocu.org API
The OCU gas stations API provides access to real-time fuel prices and station details across Spain through 2 endpoints. The search_stations endpoint returns up to 10 fields per station — including price per liter, price rating, GPS coordinates, and total tank cost — filtered by fuel type (gasolina_95, gasolina_98, diesel, diesel_premium, or glp), brand, and a configurable search radius of 1 to 50 km. The suggest_address endpoint resolves Spanish addresses and postal codes for geocoding before searching.
What the API Returns
The search_stations endpoint accepts an address (city name, street, or postal code) and returns a list of nearby stations sorted by price, cheapest first. Each station object includes brand, name, latitude, longitude, distance_km, price_per_liter, price_rating, and total_cost_per_tank. The response also echoes back the resolved address, postal_code, search latitude/longitude, radius_km, fuel_type, fuel_code, and total_stations count. Pagination is 0-based via the page parameter.
Filtering and Cost Calculation
You can narrow results by passing a brand code and a fuel_type from the supported set: gasolina_95, gasolina_98, diesel, diesel_premium, or glp. Raw internal fuel codes (e.g. GPR, GOA) are also accepted. If you supply a tank_capacity in liters, the API calculates and returns total_cost_per_tank per station, making price comparison across a fill-up straightforward without client-side math.
Address Resolution
Before calling search_stations, the suggest_address endpoint can resolve partial text — a street name, city, or five-digit postal code — into a structured list of suggestions. Each suggestion carries address, latitude, longitude, and postal_code. The total field indicates how many matches were found. This is useful for building autocomplete flows or validating that an input string maps to a real Spanish location before running a station search.
Coverage and Data Source
Data reflects OCU (Organización de Consumidores y Usuarios) fuel price listings, which cover stations throughout Spain. OCU does not publish an official developer API, so this endpoint provides the only programmatic path to this dataset. Coverage is Spain-only; there is no cross-border data for Portugal, France, or other neighboring countries.
- Display the cheapest diesel stations near a user's current location using
latitude/longitudeanddistance_km - Calculate total refueling cost for a fleet vehicle by passing
tank_capacityand comparingtotal_cost_per_tankacross results - Build a brand-specific price tracker by filtering
search_stationswith abrandcode over time - Power a postal-code lookup flow using
suggest_addressto resolve user input before querying station prices - Compare LPG (GLP) station availability and pricing in a given Spanish region by setting
fuel_typetoglp - Identify price_rating distribution across stations in a radius to flag unusually expensive or cheap outlets
- Integrate a refueling cost estimator into a Spanish road-trip planning tool using
radius_kmandprice_per_liter
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does OCU offer an official developer API for fuel price data?+
What does the `price_rating` field in station results mean?+
price_rating field derived from OCU's own classification of how competitive that station's price is relative to others in the area. It is returned alongside price_per_liter so you can compare raw price and OCU's rating independently.How does pagination work for `search_stations`?+
page parameter is 0-based, so passing page=0 returns the first page of results and page=1 returns the second. The response includes total_stations, which tells you how many stations matched so you can determine whether additional pages exist.