Conceptos básicos

La API y el servidor MCP usan identificadores estables para los carburantes, los territorios, las gasolineras, las marcas, las carreteras y las rutas. Esta página explica cada uno y cómo obtenerlo con /v1/search y /v1/territories.

Carburantes

El parámetro fuel acepta seis identificadores:

fuel	Carburante	Unidad del precio
gasoline_95	Gasolina 95 E5	€/L
gasoline_98	Gasolina 98 E5	€/L
diesel	Gasóleo A (diésel)	€/L
diesel_premium	Gasóleo premium	€/L
lpg	GLP (autogás)	€/L
cng	GNC (gas natural comprimido)	€/kg

Cada respuesta indica la unidad en unit (L o kg) y la moneda en currency (EUR).

Productos

Además de los seis carburantes, el Ministerio publica otros productos que solo comunican algunas gasolineras. Se consultan con GET /v1/products/{id} (o la herramienta MCP get_product_prices):

id	Producto
adblue	AdBlue
diesel_b	Gasóleo B (agrícola)
hvo	HVO (diésel renovable)
lng	GNL (gas natural licuado)
gasoline_95_e10	Gasolina 95 E10
gasoline_98_e10	Gasolina 98 E10

Los datos de productos solo cubren las gasolineras que comunican su precio al Ministerio, no todas las que los venden.

Niveles territoriales y códigos

Muchos endpoints aceptan un territorio con dos parámetros: level y code.

level	code	Ejemplo
spain	no hace falta	España entera (es el valor por defecto)
community	código INE de la comunidad autónoma (2 cifras) o su slug	13 o comunidad-de-madrid
province	código INE de la provincia (2 cifras) o su slug	28 o madrid
municipality	id de municipio de la API	el code que devuelven /v1/search o /v1/territories

Los códigos INE de comunidades y provincias son los oficiales del Instituto Nacional de Estadística (28 = Madrid, 46 = Valencia, 08 = Barcelona…). Puedes escribirlos con o sin cero a la izquierda (8 o 08).

Municipios: usa el id de la API

El code de un municipio no es su código INE: es el identificador interno que devuelven /v1/search (campo code de los resultados de tipo municipio) y /v1/territories?level=municipality&parent=<provincia>. Búscalo siempre con uno de esos dos endpoints.

Canarias, Ceuta y Melilla

Canarias, Ceuta y Melilla no pagan el Impuesto sobre Hidrocarburos, así que sus precios no son comparables con los del resto de España. En los rankings nacionales de «más baratas» (/v1/stations/cheapest sin territorio y /v1/rankings/regions) van aparte salvo que pidas include_low_tax=true. Las gasolineras y comunidades de esas zonas llevan low_tax_area: true.

Gasolineras

Cada gasolinera tiene:

• id: el identificador del Ministerio (IDEESS), un número entero. Es estable.
• Slug: la última parte de su web_url (https://preciosgasolina.es/gasolineras/<slug>/).

GET /v1/stations/{id} y GET /v1/stations/{id}/history aceptan cualquiera de los dos.

Marcas, carreteras y rutas

• Marcas: slug en minúsculas con guiones (repsol, ballenoil…). Lista completa en GET /v1/brands.
• Carreteras: slug del código de la carretera en minúsculas (a-3, ap-7, n-340). Lista en GET /v1/roads.
• Rutas del catálogo: slug de la ruta de preciosgasolina.es. Búscalas con GET /v1/routes.
• Contenido: type (guide, post o route) + slug. Búscalo con GET /v1/content.

Cómo obtener los identificadores

Desde un texto: /v1/search

Convierte un nombre, un código postal o una gasolinera en identificadores. Acepta q (de 2 a 100 caracteres) y limit (1–20, por defecto 8).

curl

curl "https://api.preciosgasolina.es/v1/search?q=getafe"

JavaScript

const res = await fetch("https://api.preciosgasolina.es/v1/search?q=" + encodeURIComponent("getafe"));
const { data } = await res.json();
const municipio = data.results.find((r) => r.type === "municipality");
console.log(municipio.level, municipio.code); // → "municipality", "<id>"

Python

import requests

data = requests.get("https://api.preciosgasolina.es/v1/search", params={"q": "getafe"}, timeout=10).json()["data"]
municipio = next(r for r in data["results"] if r["type"] == "municipality")
print(municipio["level"], municipio["code"])

Ejemplo ilustrativo: los valores no son reales

{
  "data": {
    "query": "getafe",
    "results": [
      {
        "type": "municipality",
        "name": "Getafe",
        "detail": "Madrid",
        "web_url": "https://preciosgasolina.es/precios-gasolineras/comunidad-de-madrid/madrid/getafe/",
        "level": "municipality",
        "code": "4300"
      },
      {
        "type": "station",
        "name": "Estación de ejemplo",
        "detail": "Madrid",
        "web_url": "https://preciosgasolina.es/gasolineras/estacion-de-ejemplo-12345/",
        "station_id": 12345,
        "address": "Calle de Ejemplo, 1",
        "brand_slug": "marca-ejemplo"
      }
    ]
  },
  "meta": { "…": "…" }
}

Cada resultado tiene un type: community, province, municipality, postal_code o station. Los territorios traen level y code (listos para usar en level + code) y las gasolineras, station_id.

Desde la lista: /v1/territories

Devuelve los territorios con sus identificadores:

Petición	Devuelve
GET /v1/territories	Comunidades autónomas (code, slug, name, códigos de sus provincias, low_tax_area)
GET /v1/territories?level=province	Provincias (code, slug, name, community_code). Con parent=<comunidad>, solo las de esa comunidad
GET /v1/territories?level=municipality&parent=28	Municipios de una provincia (code, slug, name, códigos postales, número de gasolineras y coordenadas). parent es obligatorio

En el servidor MCP, la herramienta search_places hace lo mismo que /v1/search y el recurso fuel://territories lista comunidades y provincias con sus códigos INE.

Coordenadas

Las coordenadas son WGS84 en grados decimales (lat, lng) y deben estar dentro de España, Canarias incluidas (latitud de 27,4 a 44, longitud de −18,4 a 4,6). La API las redondea a 3 decimales (unos 100 m) antes de usarlas: las respuestas son idénticas para puntos cercanos y no identifican a nadie.