# Calculadoras

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

Coste de un viaje y del depósito, ahorro, gasolina o diésel, AdBlue y desglose de impuestos con las calculadoras de la API de Gasolina hoy.

Los endpoints de **`/v1/calc/…`** usan las mismas fórmulas que las [calculadoras de preciosgasolina.es](https://preciosgasolina.es/herramientas/) y, si no indicas un precio, el precio medio de hoy (de España o de la provincia que pidas con `province`). Así tu app y la web dan el mismo resultado.

| Endpoint                       | Calcula                                                   | Parámetros obligatorios                               |
| ------------------------------ | --------------------------------------------------------- | ----------------------------------------------------- |
| `GET /v1/calc/trip-cost`       | Coste en combustible de un viaje                          | `km` **o** `from_lat`, `from_lng`, `to_lat`, `to_lng` |
| `GET /v1/calc/tank-cost`       | Cuánto cuesta llenar el depósito                          | `capacity`                                            |
| `GET /v1/calc/savings`         | Ahorro al repostar más barato y si compensa el desvío     | `usual_price`, `cheap_price`                          |
| `GET /v1/calc/vehicle-costs`   | Gasolina frente a diésel, o eléctrico frente a combustión | `compare`, `km_per_year`                              |
| `GET /v1/calc/adblue`          | Gasto en AdBlue al mes y al año                           | `km_per_year`                                         |
| `GET /v1/calc/price-breakdown` | Cuánto de cada litro son impuestos                        | ninguno                                               |

Los precios van en €/L (€/kg con GNC), los consumos en L/100 km y las distancias en km. Todas las respuestas incluyen en `inputs` los valores usados (también los que la API ha puesto por defecto) y `price_basis`, que dice de dónde sale el precio («media de España hoy», «precio indicado»…).

## Coste de un viaje

Parámetros: `fuel` (por defecto `gasoline_95`), `km` (de ida, hasta 20.000) o las coordenadas de origen y destino (la distancia se estima en línea recta × 1,25), `round_trip`, `consumption` (hasta 40), `price` (hasta 5 €), `province` (código o slug, para usar su media) y `people` (1–9, para repartir el coste).

**curl**

```sh
curl "https://api.preciosgasolina.es/v1/calc/trip-cost?fuel=diesel&km=350&consumption=6.5&round_trip=true&people=2"
```

**JavaScript**

```js
const params = new URLSearchParams({ fuel: "diesel", km: "350", consumption: "6.5", round_trip: "true", people: "2" });
const { data } = await (await fetch("https://api.preciosgasolina.es/v1/calc/trip-cost?" + params)).json();
console.log(`${data.distance.total_km} km: ${data.cost_eur} € (${data.cost_per_person_eur} € por persona)`);
```

**Python**

```python
import requests

d = requests.get(
    "https://api.preciosgasolina.es/v1/calc/trip-cost",
    params={"fuel": "diesel", "km": 350, "consumption": 6.5, "round_trip": "true", "people": 2},
    timeout=10,
).json()["data"]
print(d["distance"]["total_km"], "km:", d["cost_eur"], "€,", d["cost_per_person_eur"], "€ por persona")
```

Ejemplo ilustrativo: los valores no son precios reales

```json
{
  "data": {
    "fuel": "diesel",
    "unit": "L",
    "currency": "EUR",
    "inputs": { "consumption_per_100km": 6.5, "price": 1.481, "price_basis": "media de España hoy", "round_trip": true, "people": 2 },
    "distance": { "one_way_km": 350, "total_km": 700, "straight_line_km": null, "note": null },
    "fuel_quantity": 45.5,
    "cost_eur": 67.39,
    "cost_per_person_eur": 33.69,
    "cost_per_100km_eur": 9.63
  },
  "meta": { "web_url": "https://preciosgasolina.es/herramientas/calculadora-ruta/", "…": "…" }
}
```

## Llenar el depósito

`capacity` (litros, hasta 200), `level` del depósito al empezar (`vacio`, `reserva` —por defecto—, `1-4`, `1-2` o `3-4`), `fuel`, `price` y `province`. Devuelve el coste con el precio medio y con el más barato de hoy, y la diferencia (`possible_saving_eur`).

```sh
curl "https://api.preciosgasolina.es/v1/calc/tank-cost?capacity=50&level=reserva&fuel=gasoline_95"
```

## Ahorro al repostar más barato

`usual_price` y `cheap_price` (€/L), y opcionalmente `quantity_per_refuel`, `refuels_per_month`, `detour_km` (ida y vuelta) y `consumption`. Devuelve el ahorro por repostaje, al mes y al año, el coste del desvío, el ahorro neto, los kilómetros de desvío a partir de los que deja de compensar (`break_even_detour_km`) y un veredicto (`verdict`: `worth`, `not-worth`, `even` o `no-saving`).

```sh
curl "https://api.preciosgasolina.es/v1/calc/savings?usual_price=1.55&cheap_price=1.47&detour_km=6"
```

## Gasolina o diésel, eléctrico o combustión

`compare=petrol_vs_diesel` compara un coche de gasolina con uno diésel; `compare=ev_vs_fuel`, un eléctrico con uno de combustión. Siempre con `km_per_year`. Opcionales: consumos (`petrol_consumption`, `diesel_consumption`, `ev_consumption` en kWh/100 km), precios (`petrol_price`, `diesel_price`, `electricity_price` en €/kWh) y sobrecostes (`diesel_extra_price`, `diesel_extra_yearly_cost`, `ev_extra_price`). Devuelve el coste por 100 km, el ahorro al año, los años para amortizar y los kilómetros al año a partir de los que compensa.

```sh
curl "https://api.preciosgasolina.es/v1/calc/vehicle-costs?compare=petrol_vs_diesel&km_per_year=20000&diesel_extra_price=1500"
```

## AdBlue

`km_per_year` (obligatorio), `litres_per_1000km`, `price` (por defecto, la media de hoy en surtidor) y `tank_litres`. Devuelve litros y euros al mes, al año y cada 1.000 km.

```sh
curl "https://api.preciosgasolina.es/v1/calc/adblue?km_per_year=20000"
```

## Desglose del precio: impuestos

`fuel` (`gasoline_95`, `gasoline_98`, `diesel` o `diesel_premium`), `price` (por defecto, la media de hoy), `province` (cambia el régimen fiscal en Canarias, Ceuta y Melilla) y `tank_litres`. Devuelve por litro el IVA, el Impuesto sobre Hidrocarburos (con la rebaja vigente, si la hay), el total de impuestos y lo que queda para producto, logística y margen, con las fuentes legales.

```sh
curl "https://api.preciosgasolina.es/v1/calc/price-breakdown?fuel=diesel"
```

Los tipos de impuestos y los tramos de la rebaja están también en `GET /v1/taxes`.

> **Nota**
>
> Las calculadoras son estimaciones con las fórmulas y supuestos de las herramientas de la web. Si no indicas consumo o precio, la API usa valores típicos y te los devuelve en `inputs`.

## Con el servidor MCP

`calculate_trip_cost` (viaje y, con `tank_capacity`, también el depósito), `calculate_savings`, `compare_vehicle_costs`, `calculate_adblue` y `explain_fuel_price` (desglose más impuestos y rebaja). Ejemplo: «¿Cuánto me cuesta ir de Madrid a Valencia con 6,5 L/100 km?».