Road User Tools Agent & API Platform

Calculate journey time

Calculate journey duration from distance and average speed.

Interfaces

POST

REST endpoint/api/v1/journey-time

MCP

Tool namecalculate_journey_time

Request

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

cURLshell

curl -X POST https://roaduser.tools/api/v1/journey-time \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "distance": {
    "value": 250,
    "unit": "km"
  },
  "speed": {
    "value": 100,
    "unit": "kmh"
  }
}'

Request bodyjson

{
  "distance": {
    "value": 250,
    "unit": "km"
  },
  "speed": {
    "value": 100,
    "unit": "kmh"
  }
}

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": {
    "totalSeconds": 9000,
    "totalHours": 2.5,
    "duration": {
      "hours": 2,
      "minutes": 30,
      "seconds": 0
    },
    "formatted": "2:30:00"
  }
}

{
  "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",
            "m"
          ]
        }
      },
      "required": [
        "value",
        "unit"
      ]
    },
    "speed": {
      "type": "object",
      "additionalProperties": false,
      "description": "Average speed. Must be finite and greater than zero.",
      "properties": {
        "value": {
          "type": "number"
        },
        "unit": {
          "type": "string",
          "enum": [
            "kmh",
            "mph",
            "ms",
            "kn"
          ]
        }
      },
      "required": [
        "value",
        "unit"
      ]
    }
  },
  "required": [
    "distance",
    "speed"
  ]
}

Output schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "totalSeconds": {
      "type": "number",
      "description": "Total duration in seconds, full precision."
    },
    "totalHours": {
      "type": "number",
      "description": "Total duration in decimal hours."
    },
    "duration": {
      "type": "object",
      "additionalProperties": false,
      "description": "Duration split into whole hours, minutes, and seconds.",
      "properties": {
        "hours": {
          "type": "number"
        },
        "minutes": {
          "type": "number"
        },
        "seconds": {
          "type": "number"
        }
      },
      "required": [
        "hours",
        "minutes",
        "seconds"
      ]
    },
    "formatted": {
      "type": "string",
      "description": "H:MM:SS presentation of the duration."
    }
  },
  "required": [
    "totalSeconds",
    "totalHours",
    "duration",
    "formatted"
  ]
}