# IANA Local Time Resolver

> Resolves a local wall-clock time with pinned IANA tzdb 2026d. Returns every valid UTC candidate for a repeated fall-back time, or the exact gap and shift-forward suggestion for a nonexistent spring-forward time.

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

## Purpose

Resolves a local wall-clock time with pinned IANA tzdb 2026d. Returns every valid UTC candidate for a repeated fall-back time, or the exact gap and shift-forward suggestion for a nonexistent spring-forward time.

**Use when:** You must safely turn a named-zone local time into an instant, validate a scheduled time around a daylight-saving transition, or preserve every possible interpretation instead of silently choosing one.

**Do not use when:** The input already includes a numeric UTC offset or Z, the task only needs the current clock time, or latitude/longitude must first be mapped to a zone.

## Example user requests

- Resolve 2026-11-01 01:30 in America/New_York and return both UTC candidates.
- Does 2026-03-08 02:30 exist in New York? Show the DST gap.
- 判断 Australia/Adelaide 的 2026-10-04 02:30 是否存在，并给出时区数据版本。


## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `local_datetime` | string |  | required | Wall-clock date and time without Z or a numeric offset; it will be interpreted only in time_zone. |
| `time_zone` | string |  | required | IANA zone identifier present in tzdb 2026d. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `local_datetime` | string |  | Normalized input wall-clock time. |
| `time_zone` | string |  | Zone identifier supplied by the caller. |
| `resolved_zone_id` | string |  | Zone record used by the pinned data build. |
| `status` | string |  | unique, ambiguous (two valid instants) or nonexistent (inside a clock-forward gap). |
| `candidate_count` | integer |  | Number of valid UTC instants for the wall-clock input. |
| `candidates` | list |  | Every valid instant with UTC time, local time, offset and abbreviation, ordered earliest first. |
| `gap` | object |  | Clock-forward gap and shift-forward suggestion; null/omitted when the time exists. |
| `related_transition` | object |  | Transition whose overlap or gap contains the input, when applicable. |
| `previous_transition` | object |  | Previous offset change in this zone. |
| `next_transition` | object |  | Next offset change in this zone. |
| `tzdb_version` | string |  | Pinned IANA release used for every offset and transition. |
| `dataset_version` | string |  | Immutable Calcgrid evidence-package version. |
| `source_url` | string |  | Version-specific official IANA release URL. |
| `source_sha256` | string |  | SHA-256 of the downloaded official IANA tzdata release artifact. |
| `coverage_note` | string |  | Coverage and rule-change limitations for this fixed version. |

## Formula

`for each zone offset o: candidate_utc = local_wall_time + o; keep candidates whose active offset at candidate_utc equals o`

Calcgrid enumerates the offsets in the pinned zone record, verifies each candidate against the transition table, and returns zero, one or multiple candidates without asking the Worker runtime's mutable Intl/ICU database.

## Data Sources

- IANA Time Zone Database 2026d — https://data.iana.org/time-zones/releases/tzdata2026d.tar.gz (standard, retrieved 2026-09-26)
- IANA tz database LICENSE — https://data.iana.org/time-zones/tzdb/LICENSE (license, retrieved 2026-09-26)
- Moment Timezone 0.6.4 data build — https://www.npmjs.com/package/moment-timezone/v/0.6.4 (implementation, retrieved 2026-09-26)

Data freshness: `static`. Immutable IANA tzdb 2026d evidence package. Check the data-package index for newer published versions.

## API

- `GET https://tttkmbb.com/api/v1/calculate/local-time-resolver?local_datetime=…&time_zone=…`
- `POST https://tttkmbb.com/api/v1/calculate/local-time-resolver` 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/local-time-resolver · OpenAPI operationId `resolve_local_time` 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: `resolve_local_time` (dedicated) or `run_calculator` with `{"calculator_id": "local-time-resolver", "inputs": {…}}`

## Example

- New York fall-back overlap: inputs `{"local_datetime":"2026-11-01T01:30:00","time_zone":"America/New_York"}` → `{"status":"ambiguous","candidate_count":2,"candidates":[{"utc_datetime":"2026-11-01T05:30:00Z","utc_offset":"-04:00"},{"utc_datetime":"2026-11-01T06:30:00Z","utc_offset":"-05:00"}],"tzdb_version":"2026d"}`
- New York spring-forward gap: inputs `{"local_datetime":"2026-03-08T02:30:00","time_zone":"America/New_York"}` → `{"status":"nonexistent","candidate_count":0,"gap":{"duration_seconds":3600,"suggested_shift_forward_local":"2026-03-08T03:30:00"}}`

```
GET https://tttkmbb.com/api/v1/calculate/local-time-resolver?local_datetime=2026-11-01T01%3A30%3A00&time_zone=America%2FNew_York
```

## Limitations

The input already includes a numeric UTC offset or Z, the task only needs the current clock time, or latitude/longitude must first be mapped to a zone. Calcgrid enumerates the offsets in the pinned zone record, verifies each candidate against the transition table, and returns zero, one or multiple candidates without asking the Worker runtime's mutable Intl/ICU database. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why can one local time have two answers?**

When clocks move backward, a range of wall-clock labels repeats under two offsets. The resolver returns both instants instead of guessing.

**Is this based on the server's current time-zone database?**

No. Results are fixed to IANA tzdb 2026d and include the release URL and SHA-256 so they can be reproduced.

## Related

- [Time Zone Converter](https://tttkmbb.com/time/time-zone-converter.md) — Convert one resolved wall time to a target zone.
- [IANA Time Zone Transition List](https://tttkmbb.com/time/time-zone-transitions.md) — List every offset transition in a date range.
- [Unix Timestamp Converter](https://tttkmbb.com/time/unix-timestamp.md) — Convert a known instant to epoch seconds.