# Conceptos básicos

> Versión Markdown de https://docs.preciosgasolina.es/empezar/conceptos-basicos/ · Actualizado: 2026-10-07 · Índice para LLM: https://docs.preciosgasolina.es/llms.txt

Identificadores de la API de Gasolina hoy: carburantes, productos, niveles territoriales, códigos INE, municipios, gasolineras y slugs, y cómo obtenerlos.

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**

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

**JavaScript**

```js
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**

```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

```json
{
  "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.