Dónde repostar en una ruta

Para saber dónde repostar más barato en un viaje, envía los puntos de tu ruta a POST /v1/route/fuel: la API devuelve las gasolineras más baratas a menos de corridor_km del recorrido, su posición en la ruta y el coste estimado del viaje. Si quieres rutas ya preparadas (en coche o en moto), usa el catálogo: GET /v1/routes y GET /v1/routes/{slug}.

Tu propia ruta: POST /v1/route/fuel

Es el único endpoint de la API que usa POST, porque la ruta no cabe en una URL. El cuerpo es JSON (Content-Type: application/json, 32 KB como mucho):

Campo	Tipo	Obligatorio	Descripción
points	[[lat, lng], …]	sí	De 2 a 200 puntos en orden de recorrido (origen, localidades intermedias, destino).
fuel	texto	no	Carburante (por defecto gasoline_95).
corridor_km	número	no	Distancia máxima a la ruta, de más de 0 a 10 km (por defecto 3).
limit	entero	no	De 1 a 50 gasolineras (por defecto 10).
open_24h	booleano	no	Solo las abiertas 24 horas.
consumption	número	no	Consumo en L/100 km (kg/100 km con GNC), hasta 40, para estimar el coste.

La ruta puede medir hasta 1.500 km; si es más larga, la API responde 400. Las distancias se calculan en línea recta entre los puntos que envías: cuantos más puntos, más preciso (por ejemplo, uno cada 10–20 km de tu polilínea).

1. Consigue la polilínea. De tu servicio de rutas o de tu mapa, como lista de pares [lat, lng]. Si tienes muchos puntos, quédate con 200 como mucho repartidos por el recorrido.

2. Envíala.

   curl

   curl -X POST "https://api.preciosgasolina.es/v1/route/fuel" \
     -H "Content-Type: application/json" \
     -d '{
       "points": [[40.4168, -3.7038], [40.0704, -2.1374], [39.4699, -0.3763]],
       "fuel": "diesel",
       "corridor_km": 3,
       "limit": 5,
       "consumption": 6
     }'

   JavaScript

   // Reduce una polilínea larga a 200 puntos como mucho, conservando el primero y el último.
   function simplificar(puntos, max = 200) {
     if (puntos.length <= max) return puntos;
     const paso = (puntos.length - 1) / (max - 1);
     return Array.from({ length: max }, (_, i) => puntos[Math.round(i * paso)]);
   }
   
   const res = await fetch("https://api.preciosgasolina.es/v1/route/fuel", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       points: simplificar(miPolilinea), // [[lat, lng], …]
       fuel: "diesel",
       corridor_km: 3,
       limit: 5,
       consumption: 6,
     }),
   });
   const body = await res.json();
   if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
   const { route_length_km, trip_estimate, stations } = body.data;
   console.log(`${route_length_km} km · ${trip_estimate?.cost_eur} € con la media de hoy`);
   for (const s of stations) console.log(`km ${s.position_km}: ${s.price} €/L · ${s.name} (a ${s.distance_to_route_km} km)`);

   Python

   import requests
   
   ruta = [[40.4168, -3.7038], [40.0704, -2.1374], [39.4699, -0.3763]]
   r = requests.post(
       "https://api.preciosgasolina.es/v1/route/fuel",
       json={"points": ruta, "fuel": "diesel", "corridor_km": 3, "limit": 5, "consumption": 6},
       timeout=15,
   )
   body = r.json()
   if not r.ok:
       raise RuntimeError(f'{body["code"]}: {body["detail"]}')
   d = body["data"]
   print(d["route_length_km"], "km ·", (d["trip_estimate"] or {}).get("cost_eur"), "€")
   for s in d["stations"]:
       print("km", s["position_km"], s["price"], s["name"], "a", s["distance_to_route_km"], "km")

3. Muestra las paradas ordenadas por position_km (kilómetros desde el origen) o por precio, con la fecha de los datos y la atribución.

Ejemplo ilustrativo: los valores no son precios reales

{
  "data": {
    "fuel": "diesel",
    "currency": "EUR",
    "route_length_km": 302.6,
    "corridor_km": 3,
    "trip_estimate": {
      "consumption_per_100km": 6,
      "price_used": 1.481,
      "price_basis": "media de España de hoy",
      "fuel_quantity": 18.2,
      "cost_eur": 26.95,
      "cost_at_cheapest_on_route_eur": 25.28
    },
    "note": "Distancias en línea recta entre los puntos enviados: cuantos más puntos, más preciso.",
    "stations": [
      {
        "id": 12345,
        "name": "Estación de ejemplo",
        "brand": { "slug": "marca-ejemplo", "name": "Marca Ejemplo" },
        "address": "Calle de Ejemplo, 1",
        "postal_code": "16001",
        "municipality": { "id": 1234, "name": "Municipio de ejemplo" },
        "province": { "code": "16", "name": "Cuenca" },
        "community": { "code": "08", "name": "Castilla-La Mancha" },
        "lat": 40.07,
        "lng": -2.14,
        "is_24h": true,
        "hours": "L-D: 24H",
        "low_tax_area": false,
        "web_url": "https://preciosgasolina.es/gasolineras/estacion-de-ejemplo-12345/",
        "price": 1.389,
        "price_updated_at": "2026-10-07T06:12:00.000+00:00",
        "distance_to_route_km": 0.8,
        "position_km": 141.2
      }
    ]
  },
  "meta": { "web_url": "https://preciosgasolina.es/herramientas/calculadora-ruta/", "…": "…" }
}

trip_estimate usa la media de España de hoy del carburante (y, si no indicas consumption, un consumo típico); cost_at_cheapest_on_route_eur es el coste si repostas todo en la gasolinera más barata del recorrido. Puede ser null si no hay precio medio.

Límites

POST /v1/route/fuel cuenta como consulta pesada (30 por minuto por IP) y no se cachea. Las coordenadas se redondean a 3 decimales. Los campos desconocidos en el cuerpo devuelven 400 (INVALID_PARAMETER), un JSON mal formado 400 (INVALID_JSON), un cuerpo de más de 32 KB 413 y otro tipo de contenido 415. Ver Errores.

Rutas del catálogo

preciosgasolina.es tiene un catálogo de rutas por carretera en coche y en moto. GET /v1/routes las busca:

Parámetro	Valores
type	moto, rurales, costa, montana o clasicas
region	nombre de una comunidad (p. ej. Andalucía)
q	texto libre (2–100 caracteres)
limit	1–50 (por defecto 20)

curl "https://api.preciosgasolina.es/v1/routes?type=costa&region=Andalucía&limit=5"

Cada ruta trae slug, title, description, answer (resumen), tags y web_url. Con el slug, GET /v1/routes/{slug} devuelve el recorrido completo (localidades con coordenadas, distancia, duración, dificultad, mejor temporada, puntos destacados y fotos con su autor y licencia), el coste estimado del viaje (trip_estimate) y las gasolineras más baratas a 3 km o menos del trazado (stations_along):

curl "https://api.preciosgasolina.es/v1/routes/albufera-cullera-gandia-denia-en-coche?fuel=diesel&limit=5&consumption=6.5"

GET /v1/routes/{slug} también es una consulta pesada. El trazado de las rutas del catálogo es aproximado (une sus localidades).

Con el servidor MCP

find_fuel_along_route hace lo mismo que POST /v1/route/fuel («Voy de Madrid a Valencia por la A-3, ¿dónde reposto?»); find_routes y get_route, lo mismo que el catálogo. El prompt planificar_viaje combina el coste, las paradas y una ruta del catálogo.