# Primeros pasos

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

Haz tu primera petición a la API de Gasolina hoy con curl, lee el sobre de respuesta y conecta el servidor MCP a tu asistente en 5 minutos.

En este tutorial harás tu primera petición a la API REST, entenderás qué devuelve y conectarás el servidor MCP a un asistente de IA. No necesitas registrarte ni pedir una clave: la API y el MCP son gratuitos y de solo lectura.

**Necesitas:** una terminal con `curl` (o Node.js 18+ o Python 3) y, para la segunda parte, un cliente MCP como Claude, ChatGPT, Cursor, VS Code o Claude Code.

## 1. Tu primera petición

La API está en `https://api.preciosgasolina.es/v1`. Pide las 5 gasolineras con el diésel más barato de la provincia de Madrid (código INE `28`):

**curl**

```sh
curl "https://api.preciosgasolina.es/v1/stations/cheapest?fuel=diesel&level=province&code=28&limit=5"
```

**JavaScript**

```js
const url = new URL("https://api.preciosgasolina.es/v1/stations/cheapest");
url.search = new URLSearchParams({ fuel: "diesel", level: "province", code: "28", limit: "5" });

const res = await fetch(url);
const { data, meta } = await res.json();
console.log(data.stations.map((s) => `${s.price} €/L · ${s.name} (${s.municipality.name})`));
console.log("Datos de", meta.last_updated, "·", meta.attribution);
```

**Python**

```python
import requests  # pip install requests

r = requests.get(
    "https://api.preciosgasolina.es/v1/stations/cheapest",
    params={"fuel": "diesel", "level": "province", "code": "28", "limit": 5},
    timeout=10,
)
r.raise_for_status()
body = r.json()
for s in body["data"]["stations"]:
    print(s["price"], "€/L ·", s["name"], f'({s["municipality"]["name"]})')
print("Datos de", body["meta"]["last_updated"], "·", body["meta"]["attribution"])
```

## 2. Lee la respuesta

Todas las respuestas correctas tienen la misma forma: un objeto con `data` (el resultado) y `meta` (fecha, fuente, licencia y enlace a la web). Así es una respuesta recortada a una gasolinera:

Ejemplo ilustrativo: los valores no son precios reales

```json
{
  "data": {
    "fuel": "diesel",
    "unit": "L",
    "currency": "EUR",
    "area": {
      "level": "province",
      "code": "28",
      "name": "Madrid",
      "web_url": "https://preciosgasolina.es/precios-gasolineras/comunidad-de-madrid/madrid/"
    },
    "note": null,
    "stations": [
      {
        "id": 12345,
        "name": "Estación de ejemplo",
        "brand": { "slug": "marca-ejemplo", "name": "Marca Ejemplo" },
        "address": "Calle de Ejemplo, 1",
        "postal_code": "28001",
        "municipality": { "id": 4354, "name": "Madrid" },
        "province": { "code": "28", "name": "Madrid" },
        "community": { "code": "13", "name": "Comunidad de Madrid" },
        "lat": 40.39,
        "lng": -3.65,
        "is_24h": true,
        "hours": "L-D: 24H",
        "low_tax_area": false,
        "web_url": "https://preciosgasolina.es/gasolineras/estacion-de-ejemplo-12345/",
        "price": 1.459,
        "price_updated_at": "2026-10-07T06:12:00.000+00:00"
      }
    ]
  },
  "meta": {
    "api_version": "v1",
    "request_id": "8c1f2a9b3d4e5f60",
    "last_updated": "2026-10-07T06:12:00.000Z",
    "next_update": "2026-10-07T18:10:00.000Z",
    "data_age_seconds": 7430,
    "stale": false,
    "source": "Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras)",
    "attribution": "Fuente: Gasolina hoy (preciosgasolina.es), con datos del Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras).",
    "license": "https://creativecommons.org/licenses/by/4.0/",
    "web_url": "https://preciosgasolina.es/precios-gasolineras/comunidad-de-madrid/madrid/"
  }
}
```

Fíjate en tres campos de `meta`:

- **`last_updated`**: fecha y hora (UTC) de los datos. Los precios se actualizan dos veces al día, hacia las 8:00 y las 20:00 (hora peninsular): **no son en tiempo real**. Más en [Frescura de los datos](https://docs.preciosgasolina.es/conceptos/frescura/).
- **`attribution`**: el texto que debes mostrar junto a los datos (licencia CC BY 4.0). Más en [Atribución y licencia](https://docs.preciosgasolina.es/empezar/atribucion-y-licencia/).
- **`web_url`**: la página equivalente de preciosgasolina.es, para enlazarla como fuente.

Los precios van en euros por litro (por kilo con el GNC) y con tres decimales, como los publica el Ministerio. Cada campo está explicado en la [referencia](https://docs.preciosgasolina.es/referencia/).

## 3. Prueba un error

Pide un carburante que no existe:

```sh
curl -i "https://api.preciosgasolina.es/v1/prices?fuel=petrol"
```

La API responde `400` con un error en formato RFC 9457 (`application/problem+json`) y un `code` estable que tu código puede comprobar:

Ejemplo ilustrativo

```json
{
  "type": "https://docs.preciosgasolina.es/conceptos/errores/#invalid-parameter",
  "title": "Parámetros no válidos",
  "status": 400,
  "detail": "fuel: Invalid option: expected one of \"gasoline_95\"|\"gasoline_98\"|\"diesel\"|\"diesel_premium\"|\"lpg\"|\"cng\"",
  "code": "INVALID_PARAMETER",
  "request_id": "c51fe0c34cbb42eb",
  "instance": "/v1/prices"
}
```

La lista de códigos está en [Errores](https://docs.preciosgasolina.es/conceptos/errores/).

## 4. Conecta el servidor MCP

El servidor MCP ofrece los mismos datos a los asistentes de IA. Su dirección es:

```text
https://mcp.preciosgasolina.es/mcp
```

No hace falta iniciar sesión. Por ejemplo, en Claude Code:

```sh
claude mcp add --transport http preciosgasolina https://mcp.preciosgasolina.es/mcp
```

1. Añade el servidor en tu cliente (pasos para Claude, ChatGPT, Cursor y VS Code en [Conectar el servidor MCP](https://docs.preciosgasolina.es/mcp/conectar/)).
2. Abre un chat nuevo y activa el conector si tu cliente lo pide.
3. Pregunta, por ejemplo: «¿Qué provincia tiene el diésel más barato hoy?». El asistente usará la herramienta `compare_regions` y te dará la fecha de los datos y el enlace a preciosgasolina.es.

> **Antes de ir a producción**
>
> Lee los [límites de uso](https://docs.preciosgasolina.es/conceptos/limites/) (120 peticiones por minuto por IP en la API REST) y cómo [cachear hasta la próxima actualización](https://docs.preciosgasolina.es/guias/integrar-en-tu-web/) con `meta.next_update`: los datos solo cambian dos veces al día.

## Siguientes pasos

[Conceptos básicos](https://docs.preciosgasolina.es/empezar/conceptos-basicos/)Identificadores de carburantes, territorios y gasolineras.

[Guías](https://docs.preciosgasolina.es/guias/gasolinera-mas-barata-cerca/)Casos de uso completos, paso a paso.

[Herramientas del MCP](https://docs.preciosgasolina.es/mcp/herramientas/)Las 21 herramientas con sus argumentos.

[Referencia de la API](https://docs.preciosgasolina.es/referencia/)Endpoints, parámetros y cabeceras.