Las más baratas de una provincia

Para las gasolineras más baratas de un territorio, usa GET /v1/stations/cheapest con level y code. Para su precio medio frente a España, GET /v1/prices. Y para saber qué provincias o comunidades son más baratas, GET /v1/rankings/regions.

Las más baratas de un territorio

level puede ser community, province o municipality; code es el código INE (o el slug) de la comunidad o provincia, o el id de municipio de la API (ver Conceptos básicos).

curl

# Las 10 gasolineras con la gasolina 95 más barata de la provincia de Valencia
curl "https://api.preciosgasolina.es/v1/stations/cheapest?fuel=gasoline_95&level=province&code=46&limit=10"

JavaScript

const API = "https://api.preciosgasolina.es/v1";

async function get(path, params) {
  const res = await fetch(API + path + "?" + new URLSearchParams(params));
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
  return body;
}

const { data } = await get("/stations/cheapest", { fuel: "gasoline_95", level: "province", code: "46", limit: "10" });
console.log(data.area.name);
data.stations.forEach((s, i) => console.log(i + 1, s.price.toFixed(3), s.name, s.municipality.name));

Python

import requests

API = "https://api.preciosgasolina.es/v1"

def get(path, **params):
    r = requests.get(API + path, params=params, timeout=10)
    body = r.json()
    if not r.ok:
        raise RuntimeError(f'{body["code"]}: {body["detail"]}')
    return body

data = get("/stations/cheapest", fuel="gasoline_95", level="province", code="46", limit=10)["data"]
print(data["area"]["name"])
for i, s in enumerate(data["stations"], 1):
    print(i, f'{s["price"]:.3f}', s["name"], s["municipality"]["name"])

Filtros opcionales: open_24h=true y brand=<slug>. Sin level (o con level=spain) obtienes las más baratas de España; en ese caso Canarias, Ceuta y Melilla van aparte (no pagan el Impuesto sobre Hidrocarburos) salvo que añadas include_low_tax=true, y data.note lo indica.

Precio medio de hoy

GET /v1/prices devuelve, para cada carburante, la media, la mediana, el mínimo, el máximo, el número de gasolineras, la variación frente al día anterior (en %) y la diferencia con la media de España (en %). Con fuel te quedas con uno solo.

curl "https://api.preciosgasolina.es/v1/prices?level=province&code=46&fuel=diesel"

Ejemplo ilustrativo: los valores no son precios reales

{
  "data": {
    "area": { "level": "province", "code": "46", "name": "Valencia", "web_url": "https://preciosgasolina.es/precios-gasolineras/comunitat-valenciana/valencia/" },
    "stations": 612,
    "currency": "EUR",
    "fuels": [
      {
        "fuel": "diesel",
        "label": "Gasóleo A (diésel)",
        "unit": "L",
        "average": 1.462,
        "median": 1.469,
        "minimum": 1.329,
        "maximum": 1.629,
        "stations": 598,
        "change_vs_previous_day_pct": -0.2,
        "spain_average": 1.481,
        "vs_spain_pct": -1.28,
        "cheapest_station_id": 12345,
        "fuel_page_url": "https://preciosgasolina.es/precio-diesel/"
      }
    ]
  },
  "meta": { "…": "…" }
}

cheapest_station_id es el id de la gasolinera más barata: pídela con GET /v1/stations/{id} para ver su ficha completa.

Comparar provincias o comunidades

GET /v1/rankings/regions ordena las provincias (level=province, por defecto) o las comunidades (level=community) de más barata a más cara para un carburante (fuel, por defecto diesel):

curl "https://api.preciosgasolina.es/v1/rankings/regions?level=community&fuel=gasoline_95"

Cada fila trae rank, code, name, average, minimum, maximum, stations, vs_spain_pct, low_tax_area y web_url. Canarias, Ceuta y Melilla se excluyen salvo include_low_tax=true.

Cachea hasta la próxima actualización

Estas respuestas solo cambian cuando hay datos nuevos (dos veces al día). Guárdalas hasta meta.next_update en lugar de repetir la petición: ver Integrar en tu web.

Con el servidor MCP

• find_cheapest_fuel con level y code: «Diésel más barato en Sevilla».
• get_fuel_prices: «Precio medio de la gasolina en Valencia hoy frente a España».
• compare_regions: «¿Qué provincia tiene el diésel más barato?».