# World Clock Calculator

> Takes a reference date and time in one IANA time zone and lists the corresponding local date, time, weekday and UTC offset in each zone of a list, using the tz database rules built into ICU (daylight saving included).

- Calculator id: `world-clock` · Category: Time & Geography (`time`) · Tool name: `calculate_world_clock`
- Canonical page: https://tttkmbb.com/time/world-clock · This document: https://tttkmbb.com/time/world-clock.md · JSON definition: https://tttkmbb.com/time/world-clock.json

## Purpose

Takes a reference date and time in one IANA time zone and lists the corresponding local date, time, weekday and UTC offset in each zone of a list, using the tz database rules built into ICU (daylight saving included).

**Use when:** You are scheduling across several cities and need the local time in each of them for one instant, or want to see the spread of UTC offsets.

**Do not use when:** You only convert between two zones (use time-zone-converter) or need an epoch value (use unix-timestamp).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `date` | date |  | optional, default "today" | Calendar date of the reference time in the reference zone; defaults to the current UTC date. |
| `time` | string |  | optional, default "12:00" | Wall-clock time in the reference zone, 24-hour HH:MM. |
| `zone` | string |  | optional, default "UTC" | IANA time zone in which date and time are given. |
| `zones` | string_list |  | required | List of IANA time zones to display (comma-separated or JSON array), e.g. America/New_York, Europe/London, Asia/Tokyo. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `utc_datetime` | string |  | The reference instant in UTC (ISO 8601). |
| `reference_datetime` | string |  | The reference time with its UTC offset (ISO 8601). |
| `clocks` | list |  | One entry per zone: zone, local_date, local_time, weekday, utc_offset, abbreviation and day_offset (local date minus reference date, in days). |
| `offset_span_hours` | number | h | Largest minus smallest UTC offset among the reference zone and all listed zones. |

## Formula

`utc = reference wall time − offset_reference; for each zone: local = utc + offset_zone(utc); day_offset = local_date − reference_date`

Offsets come from the IANA tz database via Intl.DateTimeFormat. Non-existent reference times (clocks jumped forward) are moved forward by the gap; ambiguous ones take their first occurrence.

## Data Sources

- IANA Time Zone Database (tz) — https://www.iana.org/time-zones (standard, retrieved 2026-09-24)
- List of tz database time zones (Wikipedia) — https://en.wikipedia.org/wiki/List_of_tz_database_time_zones (reference, retrieved 2026-09-24)

Data freshness: `daily` (max_age_seconds 86400). Depends on the current date unless the date is supplied.

## API

- `GET https://tttkmbb.com/api/v1/calculate/world-clock?zones=…`
- `POST https://tttkmbb.com/api/v1/calculate/world-clock` 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/world-clock · OpenAPI operationId `calculate_world_clock` 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": "world-clock", "inputs": {…}}`

## Example

- 09:00 Adelaide on 2026-09-23 in New York, London, Tokyo: inputs `{"date":"2026-09-23","time":"09:00","zone":"Australia/Adelaide","zones":["America/New_York","Europe/London","Asia/Tokyo"]}` → `{"utc_datetime":"2026-09-22T23:30:00Z","clocks":[{"zone":"America/New_York","local_date":"2026-09-22","local_time":"19:30","utc_offset":"-04:00","day_offset":-1},{"zone":"Europe/London","local_date":"2026-09-23","local_time":"00:30","utc_offset":"+01:00","day_offset":0},{"zone":"Asia/Tokyo","local_date":"2026-09-23","local_time":"08:30","utc_offset":"+09:00","day_offset":0}],"offset_span_hours":13.5}`
- New Year 2026 00:00 UTC in Auckland, Kolkata, Los Angeles: inputs `{"date":"2026-01-01","time":"00:00","zone":"UTC","zones":["Pacific/Auckland","Asia/Kolkata","America/Los_Angeles"]}` → `{"clocks":[{"zone":"Pacific/Auckland","local_date":"2026-01-01","local_time":"13:00","utc_offset":"+13:00"},{"zone":"Asia/Kolkata","local_time":"05:30","utc_offset":"+05:30"},{"zone":"America/Los_Angeles","local_date":"2025-12-31","local_time":"16:00","utc_offset":"-08:00","day_offset":-1}],"offset_span_hours":21}`

```
GET https://tttkmbb.com/api/v1/calculate/world-clock?date=2026-09-23&time=09%3A00&zone=Australia%2FAdelaide&zones=America%2FNew_York%2CEurope%2FLondon%2CAsia%2FTokyo
```

## Limitations

You only convert between two zones (use time-zone-converter) or need an epoch value (use unix-timestamp). Offsets come from the IANA tz database via Intl.DateTimeFormat. Non-existent reference times (clocks jumped forward) are moved forward by the gap; ambiguous ones take their first occurrence. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why does a city show a different date?**

day_offset is the local calendar date minus the reference date: −1 means the instant falls on the previous day there, +1 on the next day (e.g. Auckland is ahead of Los Angeles by up to 21 hours).

**Can I use city names instead of zone names?**

No; use the IANA zone of the city (Paris → Europe/Paris, Mumbai → Asia/Kolkata, Sydney → Australia/Sydney). Invalid names return an INVALID_PARAMETER error.

## Related

- [Time Zone Converter](https://tttkmbb.com/time/time-zone-converter.md) — Two-zone conversion with day difference and abbreviations.
- [Unix Timestamp Converter](https://tttkmbb.com/time/unix-timestamp.md) — Epoch seconds for the same instant.