# Time Duration Calculator

> Computes the elapsed time between a start and an end clock time (24-hour HH:MM), optionally minus a break, handling intervals that cross midnight, and reports it as hours and minutes and as decimal hours.

- Calculator id: `time-duration` · Category: Everyday Life (`everyday`) · Tool name: `calculate_time_duration`
- Canonical page: https://tttkmbb.com/everyday/time-duration · This document: https://tttkmbb.com/everyday/time-duration.md · JSON definition: https://tttkmbb.com/everyday/time-duration.json

## Purpose

Computes the elapsed time between a start and an end clock time (24-hour HH:MM), optionally minus a break, handling intervals that cross midnight, and reports it as hours and minutes and as decimal hours.

**Use when:** You need the length of a shift, meeting, trip or any interval given two clock times on the same or consecutive days.

**Do not use when:** The interval spans more than 24 hours or several days (use date-difference), or you need weekly hours and pay (use work-hours).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `start_time` | string |  | required | Start clock time in 24-hour HH:MM format. |
| `end_time` | string |  | required | End clock time in 24-hour HH:MM format. An end time earlier than the start time is taken as the next day. |
| `break_minutes` | integer | min | optional, default 0 | Unpaid or excluded minutes to subtract from the interval. (min 0, max 1440) |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `total_minutes` | integer | min | Elapsed minutes after subtracting the break. |
| `hours` | integer | h | Whole hours of the duration. |
| `minutes` | integer | min | Minutes beyond the whole hours. |
| `decimal_hours` | number | h | total_minutes / 60, e.g. for timesheets. |
| `duration_text` | string |  | Duration as 'h h m min'. |
| `gross_minutes` | integer | min | Minutes from start_time to end_time before subtracting the break. |
| `crosses_midnight` | boolean |  | true when end_time is earlier than start_time and was taken as the next day. |

## Formula

`gross_minutes = end − start (+ 1440 if end < start); total_minutes = gross_minutes − break_minutes; decimal_hours = total_minutes / 60`

Identical start and end times give 0 minutes, not 24 hours. Daylight-saving transitions are ignored.

## Data Sources

- ISO 8601 – Date and time format (Wikipedia) — https://en.wikipedia.org/wiki/ISO_8601 (reference, retrieved 2026-09-23)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/time-duration?start_time=…&end_time=…`
- `POST https://tttkmbb.com/api/v1/calculate/time-duration` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/time-duration · OpenAPI operationId `calculate_time_duration` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "time-duration", "inputs": {…}}`

## Example

- 09:30 to 17:45 with a 30-minute break: inputs `{"start_time":"09:30","end_time":"17:45","break_minutes":30}` → `{"total_minutes":465,"hours":7,"minutes":45,"decimal_hours":7.75,"duration_text":"7 h 45 min","gross_minutes":495,"crosses_midnight":false}`
- Night shift 22:00 to 06:30: inputs `{"start_time":"22:00","end_time":"06:30"}` → `{"total_minutes":510,"hours":8,"minutes":30,"decimal_hours":8.5,"duration_text":"8 h 30 min","crosses_midnight":true}`

```
GET https://tttkmbb.com/api/v1/calculate/time-duration?start_time=09%3A30&end_time=17%3A45&break_minutes=30
```

## Limitations

The interval spans more than 24 hours or several days (use date-difference), or you need weekly hours and pay (use work-hours). Identical start and end times give 0 minutes, not 24 hours. Daylight-saving transitions are ignored. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**How do I enter 12-hour times?**

Convert to 24-hour clock first: 5:45 PM is 17:45, 12:30 AM is 00:30.

**What if the break is longer than the interval?**

The calculator returns a CALCULATION_ERROR; check the times or the break length.

## Related

- [Work Hours Calculator](https://tttkmbb.com/everyday/work-hours.md) — Weekly and monthly hours and pay from the same shift times.
- [Date Difference Calculator](https://tttkmbb.com/everyday/date-difference.md) — Intervals spanning several days.