Trip Cost API · v1
Build with what a drive costs.
The engine behind FuelWide's trip planner, as one JSON request: route, energy priced in every country and US state crossed, verified vignettes, the cheapest refuelling stops and route alternatives — each number with its source.
curl "https://fuelwide.com/api/v1/trip-cost?from=Paris&to=Barcelona&fuel=diesel&level=40"Country-by-country energy
Fuel priced where it's burned: 111 national markets and all 51 US states plus DC. Electricity at residential estimates, labelled as such.
Refuelling plans
The cheapest stops within range, using forecourt prices near the route where a national feed publishes them — and the saving against refuelling when low.
Honest road fees
Vignettes for 6 countries from each operator's tariff. Anything we don't hold comes back as "unavailable", never an estimate.
Request
GET with query parameters (cached for 30 minutes at the edge) or POST with JSON. Only from and to are required; everything you leave out is filled with a labelled assumption.
curl -X POST https://fuelwide.com/api/v1/trip-cost \
-H "Content-Type: application/json" \
-d '{
"origin": "Sofia",
"destination": { "label": "Munich", "lat": 48.137, "lon": 11.575 },
"vehicle": { "fuelType": "diesel", "consumption": 6.2, "tankCapacity": 55, "currentLevelPercent": 30 },
"currency": "EUR",
"roundTrip": true,
"stayDays": 4
}'| Field | Meaning |
|---|---|
| origin / destination | A place name, or { label, lat, lon } to skip geocoding |
| vehicle.fuelType | petrol · diesel · lpg · ev |
| vehicle.id | A model from FuelWide's car list (e.g. toyota/corolla) |
| vehicle.consumption | L/100 km, or kWh/100 km for ev — overrides the model |
| vehicle.tankCapacity | Litres, or usable kWh |
| vehicle.currentLevelPercent | 0–100; default 50 |
| currency | EUR · USD · GBP · CAD; default by origin |
| roundTrip, stayDays | Round trip, and days before the return (vignette validity) |
| optimization | fastest · cheapest — which route is primary |
Response
A real calculation from today's data, trimmed for length.
{
"apiVersion": "v1",
"engineVersion": "2",
"generatedAt": "2026-09-18T05:13:28.129Z",
"currency": "EUR",
"exchangeRate": {
"perEur": 1,
"asOf": "2026-09-16",
"source": null
},
"origin": {
"label": "Paris, France",
"lat": 48.8535,
"lon": 2.34839,
"countryCode": "FR"
},
"destination": {
"label": "Barcelona, Spain",
"lat": 41.38258,
"lon": 2.17707,
"countryCode": "ES"
},
"vehicle": {
"id": null,
"label": "Typical diesel car",
"fuelType": "diesel",
"consumptionPer100Km": 6,
"consumptionUnit": "L/100km",
"tankCapacity": 55,
"startLevelPercent": 40,
"provenance": {
"consumption": {
"source": "FuelWide assumption",
"sourceId": null,
"url": null,
"asOf": null,
"granularity": "assumption",
"confidence": "low",
"note": "Typical diesel car: 6 L/100 km",
"attribution": null
},
"tank": {
"source": "FuelWide assumption",
"sourceId": null,
"url": null,
"asOf": null,
"granularity": "assumption",
"confidence": "low",
"note": "Tank assumed at 55 L",
"attribution": null
},
"start": {
"source": "Entered by you",
"sourceId": null,
"url": null,
"asOf": null,
"granularity": "user",
"confidence": "high",
"note": null,
"attribution": null
}
}
},
"roundTrip": false,
"optimization": "fastest",
"primaryRouteId": "r0",
"routes": [
{
"id": "r0",
"tags": [
"fastest",
"shortest",
"cheapest"
],
"distanceKm": 1034,
"durationMinutes": 649,
"countries": [
{
"countryCode": "FR",
"name": "France",
"km": 875.5
},
{
"countryCode": "ES",
"name": "Spain",
"km": 158.5
}
],
"energy": {
"amount": 62,
"unit": "L",
"cost": 137.79,
"partial": false,
"unpricedKm": 0,
"method": "Fuel burned in each country or state, priced at that region's latest published average.",
"segments": [
{
"regionId": "FR",
"name": "France",
"countryCode": "FR",
"startKm": 0,
"endKm": 875.5,
"km": 875.5,
"units": 52.53,
"pricePerUnit": 2.29,
"cost": 120.35,
"priced": true,
"provenance": {
"source": "European Commission, DG Energy — Weekly Oil Bulletin",
"sourceId": "ec-weekly-oil-bulletin",
"url": "https://energy.ec.europa.eu/data-and-analysis/weekly-oil-bulletin_en",
"asOf": "2026-09-14",
"granularity": "national",
"confidence": "high",
"note": "Estimated using the France national average",
"attribution": "Source: European Commission, Weekly Oil Bulletin"
}
},
{
"regionId": "ES",
"name": "Spain",
"countryCode": "ES",
"startKm": 875.5,
"endKm": 1034,
"km": 158.5,
"units": 9.51,
"pricePerUnit": 1.83,
"cost": 17.44,
"priced": true,
"provenance": {
"source": "European Commission, DG Energy — Weekly Oil Bulletin",
"sourceId": "ec-weekly-oil-bulletin",
"url": "https://energy.ec.europa.eu/data-and-analysis/weekly-oil-bulletin_en",
"asOf": "2026-09-14",
"granularity": "national",
"confidence": "high",
"note": "Estimated using the Spain national average",
"attribution": "Source: European Commission, Weekly Oil Bulletin"
}
}
]
},
"refuelling": {
"recommended": {
"feasible": true,
"stops": [
{
"km": 4.3,
"regionId": "FR",
"kind": "station",
"label": "Paris",
"station": {
"brand": null,
"address": "27 Avenue de la Porte d'Italie",
"town": "Paris",
"lat": 48.817,
"lon": 2.36,
"offRouteKm": 0
},
"units": 33.3,
"pricePerUnit": 2.25,
"cost": 74.83,
"levelBeforePercent": 40,
"levelAfterPercent": 100,
"provenance": {
"source": "Ministère de l'Économie (France)",
"sourceId": "fr-prix-carburants",
"url": "https://www.prix-carburants.gouv.fr/rubrique/opendata/",
"asOf": "2026-09-17",
"granularity": "station",
"confidence": "high",
"note": "Reported by the forecourt; snapshot from 2026-09-17",
"attribution": "Station prices: prix-carburants.gouv.fr, Licence Ouverte"
}
},
{
"km": 774,
"regionId": "FR",
"kind": "station",
"label": "Salles-d'Aude",
"station": {
"brand": null,
"address": "Autoroute A9 - Aire de Narbonne Vinassan Sud",
"town": "Salles-d'Aude",
"lat": 43.2148856472,
"lon": 3.09236711734,
"offRouteKm": 0.1
},
"units": 8.3,
"pricePerUnit": 2.25,
"cost": 18.56,
"levelBeforePercent": 16,
"levelAfterPercent": 31,
"provenance": {
"source": "Ministère de l'Économie (France)",
"sourceId": "fr-prix-carburants",
"url": "https://www.prix-carburants.gouv.fr/rubrique/opendata/",
"asOf": "2026-09-17",
"granularity": "station",
"confidence": "high",
"note": "Reported by the forecourt; snapshot from 2026-09-17",
"attribution": "Station prices: prix-carburants.gouv.fr, Licence Ouverte"
}
}
],
"purchaseCost": 106.91,
"tripEnergyCost": 139.49,
"arrivalUnits": 9.7,
"arrivalPercent": 18,
"note": null
},
"baseline": "…",
"savings": {
"amount": 5.16,
"percent": 3.6,
"meaningful": true,
"message": "Refuel where we suggest instead of wherever the tank runs low."
}
},
"roadFees": {
"total": 0,
"partial": true,
"items": [
{
"countryCode": "FR",
"countryName": "France",
"status": "unavailable",
"kind": "unknown",
"label": "Toll information unavailable",
"amount": null,
"amountLocal": null,
"currencyLocal": null,
"note": "Distance-based motorway tolls apply on many roads here. We don't price them yet.",
"provenance": null
},
{
"countryCode": "ES",
"countryName": "Spain",
"status": "unavailable",
"kind": "unknown",
"label": "Toll information unavailable",
"amount": null,
"amountLocal": null,
"currencyLocal": null,
"note": "Distance-based motorway tolls apply on many roads here. We don't price them yet.",
"provenance": null
}
]
},
"totalKnownCost": 137.79,
"totalPartial": true,
"geometry": {
"type": "LineString",
"coordinates": [
[
2.34788,
48.8539
],
"…"
]
}
},
"… 1 alternative route(s)"
],
"warnings": [],
"assumptions": [
"Prices are each region's latest published average, not live pump prices.",
"Refuelling plans keep at least 10% in the tank.",
"Road-fee validity assumes about 9 hours of driving a day.",
"Typical diesel car: 6 L/100 km",
"Tank assumed at 55 L"
],
"capabilities": {
"avoidTolls": false,
"alternatives": true
},
"licensing": {
"withheld": [],
"commercialUseCleared": true,
"note": null
}
}Supported data
- Fuel and energy
- Petrol and diesel for 111 markets and every US state; LPG where the source publishes it; electricity estimates for European markets and the US. Forecourt-level prices near the route in Spain, France, Italy, Portugal, Slovenia and Bulgaria.
- Vignettes (priced)
- ATHUCZSICHBG
- No general car toll (recorded)
- DENLBELU
- Not yet
- Distance-based tolls, ferries, congestion charges and public charging tariffs. The response says so wherever they apply, and totals are marked partial.
AT
HU
CZ
SI
CH
BG
DE
NL
BE
LURules of the road
- Licensing. Values whose publisher hasn't cleared redistribution are withheld and listed in
licensing.withheld.licensing.commercialUseClearedis false whenever any source used has not cleared commercial use. Credit each source'sattribution. See sources. - Limits. Without a key: 20 requests a minute per IP. Keys (sent as
X-API-Key) get higher limits. - Errors. Always JSON:
{ "error": { "code", "message" } }with codes such asinvalid_request,geocode_failed,route_failed,provider_timeoutandrate_limited. - Versioning. Breaking changes get a new path (
/api/v2/…); v1 fields are only ever added to. - Pricing. Free during the beta. Paid plans with higher limits and an SLA are planned — tell us what you need.
What it's for
Travel and booking apps
Show the driving cost next to the train and flight fare.
Fleet and expenses
Estimate a trip before it's driven; reconcile after.
Logistics quotes
Price the energy and vignettes on a cross-border run.
EV and car platforms
Compare what the same trip costs in different vehicles.
Building something with trip costs?
Tell us the routes, volumes and markets you need — we'll set up a key.
Looking for raw prices instead? The fuel prices API serves national and forecourt prices with their licences.