Road User Tools Agent & API Platform

Calculate fuel cost

Calculate fuel required and journey cost from distance, economy, and fuel price.

Interfaces

POST

REST endpoint/api/v1/fuel-cost

MCP

Tool namecalculate_fuel_cost

Request

Send the request as JSON. MCP clients pass the same fields as tool arguments.

cURLshell

curl -X POST https://roaduser.tools/api/v1/fuel-cost \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "distance": {
    "value": 500,
    "unit": "km"
  },
  "economy": {
    "value": 6.5,
    "unit": "l_per_100km"
  },
  "price": {
    "value": 1.65,
    "per": "l"
  },
  "currency": "GBP"
}'

Request bodyjson

{
  "distance": {
    "value": 500,
    "unit": "km"
  },
  "economy": {
    "value": 6.5,
    "unit": "l_per_100km"
  },
  "price": {
    "value": 1.65,
    "per": "l"
  },
  "currency": "GBP"
}

Response

REST wraps the calculation result in the standard success envelope. MCP returns the same calculation data as structured tool output.

JSON

{
  "ok": true,
  "data": {
    "fuel": {
      "litres": 32.5,
      "gallonsUk": 7.149000569720353,
      "gallonsUs": 8.585591701639824
    },
    "totalCost": 53.625,
    "costPerKm": 0.10725,
    "costPerMile": 0.172602144,
    "currency": "GBP"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request input."
  }
}

Schemas

The definitions below show the complete JSON Schema used to validate inputs and describe outputs.

Input schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "distance": {
      "type": "object",
      "additionalProperties": false,
      "description": "Journey distance. Must be finite and non-negative.",
      "properties": {
        "value": {
          "type": "number"
        },
        "unit": {
          "type": "string",
          "enum": [
            "km",
            "mi"
          ]
        }
      },
      "required": [
        "value",
        "unit"
      ]
    },
    "economy": {
      "type": "object",
      "additionalProperties": false,
      "description": "Vehicle fuel economy. Must be finite and greater than zero.",
      "properties": {
        "value": {
          "type": "number"
        },
        "unit": {
          "type": "string",
          "enum": [
            "mpg_uk",
            "mpg_us",
            "l_per_100km",
            "km_per_l"
          ]
        }
      },
      "required": [
        "value",
        "unit"
      ]
    },
    "price": {
      "type": "object",
      "additionalProperties": false,
      "description": "Fuel price per volume unit. Must be finite and non-negative.",
      "properties": {
        "value": {
          "type": "number"
        },
        "per": {
          "type": "string",
          "enum": [
            "l",
            "gal_uk",
            "gal_us"
          ]
        }
      },
      "required": [
        "value",
        "per"
      ]
    },
    "currency": {
      "type": "string",
      "description": "Optional display-only currency label echoed back in the result, e.g. \"GBP\" or \"£\". No conversion is performed."
    }
  },
  "required": [
    "distance",
    "economy",
    "price"
  ]
}

Output schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "fuel": {
      "type": "object",
      "additionalProperties": false,
      "description": "Fuel required for the journey.",
      "properties": {
        "litres": {
          "type": "number"
        },
        "gallonsUk": {
          "type": "number"
        },
        "gallonsUs": {
          "type": "number"
        }
      },
      "required": [
        "litres",
        "gallonsUk",
        "gallonsUs"
      ]
    },
    "totalCost": {
      "type": "number",
      "description": "Total journey fuel cost in the supplied price."
    },
    "costPerKm": {
      "type": "number"
    },
    "costPerMile": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "description": "Echo of the display-only currency label."
    }
  },
  "required": [
    "fuel",
    "totalCost",
    "costPerKm",
    "costPerMile"
  ]
}