OCU APIocu.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.
What is the OCU 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.
curl -X GET 'https://api.parse.bot/scraper/546672d3-429f-480d-9229-2d3a739ca054/search_stations?page=0&address=28001&fuel_type=diesel&radius_km=5&tank_capacity=30' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace ocu-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""OCU Spain Gas Station Finder — find cheapest fuel near any Spanish location."""
from parse_apis.ocu_spain_gas_station_finder_api import OCU, FuelType, AddressNotFound
client = OCU()
# Autocomplete an address to confirm geocoding works.
suggestion = client.addresssuggestions.search(query="28001", limit=3).first()
if suggestion:
print(suggestion.address, suggestion.latitude, suggestion.longitude)
# Search cheapest diesel stations near Madrid's center.
for station in client.stations.search(address="Madrid", fuel_type=FuelType.DIESEL, radius_km=10, limit=5):
print(station.brand, station.price_per_liter, station.distance_km, station.street_address)
# Drill into one station for details.
top = client.stations.search(address="Barcelona", fuel_type=FuelType.GASOLINA_95, limit=1).first()
if top:
print(top.name, top.price_per_liter, top.price_rating, top.directions_url)
# Handle a bad address gracefully.
try:
client.stations.search(address="xyznonexistent99999", limit=1).first()
except AddressNotFound as exc:
print(f"Address not found: {exc.address}")
print("exercised: stations.search / addresssuggestions.search / AddressNotFound error")
Search for gas stations near a location in Spain. Returns real-time fuel prices, station details, coordinates, and distance from search center. Stations are sorted by price (cheapest first). Each station includes brand, name, coordinates, street address, distance, price per liter, a price rating (good/average/expensive), total cost per tank, logo URL, and a Google Maps directions link. Pagination is 0-based. An unresolvable address returns stale_input.
| 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 sorted by price ascending",
"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": "28001 Madrid, España",
"latitude": 40.426175,
"stations": [
{
"name": "BALLENOIL (1)",
"brand": "BALLENOIL",
"latitude": 40.41025,
"logo_url": "https://www.ocu.org/-/media/ocu/images/calculators/logo-ballenoil.svg",
"longitude": -3.717528,
"distance_km": 3.27,
"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.378,
"total_cost_per_tank": 41.34
}
],
"fuel_code": "GPR",
"fuel_type": "gasolina_95",
"longitude": -3.685144,
"radius_km": 5,
"postal_code": "28001",
"total_stations": 68,
"tank_capacity_liters": 30
},
"status": "success"
}
}About the OCU API
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.
The OCU API is a managed, monitored endpoint for ocu.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ocu.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official ocu.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.