FA
API & MCPمستندات

پلتفرم عامل‌ها و API Road User Tools

محاسبه هزینه سوخت

سوخت مورد نیاز و هزینه سفر را از مسافت، صرفه جویی و قیمت سوخت محاسبه کنید.

رابط ها

POST
نقطه پایانی REST/api/v1/fuel-cost
MCP
نام ابزارcalculate_fuel_cost

درخواست کنید

درخواست را به عنوان JSON ارسال کنید. مشتریان MCP همان فیلدها را به عنوان آرگومان های ابزار ارسال می کنند.

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"
}'
درخواست بدنjson
{
  "distance": {
    "value": 500,
    "unit": "km"
  },
  "economy": {
    "value": 6.5,
    "unit": "l_per_100km"
  },
  "price": {
    "value": 1.65,
    "per": "l"
  },
  "currency": "GBP"
}

پاسخ

REST نتیجه محاسبات را در پاکت استاندارد موفقیت قرار می دهد. MCP همان داده های محاسباتی را به عنوان خروجی ابزار ساخت یافته برمی گرداند.

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"
  }
}

طرحواره ها

تعاریف زیر طرح کامل JSON را نشان می دهد که برای اعتبارسنجی ورودی ها و توصیف خروجی ها استفاده می شود.

شِمای ورودی

{
  "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"
  ]
}

شِمای خروجی

{
  "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"
  ]
}
مستندات API و MCP