# Date Math: DST & Timezone Clock Change Lookup

> Date Math: DST & Timezone Clock Change Lookup is a paid API for AI agents from date-math.datemath.workers.dev, paid per call via x402, $0.001/call, status unknown (last checked 2026-11-21).

Returns DST observance, annual clock-change transitions, and validity status of a local time (valid, skipped, or repeated) for a given IANA timezone.

## Facts

- Endpoint: POST https://date-math.datemath.workers.dev/v1/dst?utm_source=zero.xyz
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-21
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/date-math-dst-timezone-clock-change-lookup-22dcc93f
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_pqA_AUW0XEabj-XyaBeoC

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability date-math-dst-timezone-clock-change-lookup-22dcc93f -d '<json body>'
```

Example prompt: Is 2:30 AM on March 8, 2026 a valid local time in America/New_York, or does it fall in the spring-forward gap? Also tell me exactly when the clocks change that day.

## When to prefer this

Use this endpoint when you need to reason about daylight saving time transitions for a specific timezone — especially before scheduling jobs, alarms, meetings, or cron expressions near clock-change boundaries. It is specifically designed to surface skipped (spring-forward) and repeated (fall-back) local times, which most general datetime libraries handle inconsistently. Prefer this over a general date arithmetic endpoint when the DST validity of a specific local wall time is the core question.

## Known failure modes

- Invalid or unrecognized IANA timezone string returns an error
- Malformed datetime string (wrong format or out-of-range values) returns a validation error
- Year outside 1900–2100 range is rejected
- Missing required timezone field causes a 400-level error
- Network timeout on the Workers.dev edge function

## How this service works

Date Math: Daylight saving time for a time zone: does it observe DST, the year's exact clock changes (UTC instant, local before/after), and whether a local time is valid, skipped (spring-forward gap, e.g. 02:30) or repeated (fall-back, happens twice). Use before scheduling jobs, alarms or meetings near clock changes.

## Output

A JSON object containing: whether the timezone observes DST, its standard and DST UTC offsets, an array of clock-change transition events for the year (each with UTC instant, local time before/after, offsets before/after, and direction), and if a datetime was supplied, a check object showing whether that local time is valid, skipped (spring-forward gap), or repeated (fall-back ambiguity), along with possible UTC instants and the resolved canonical time.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "year": {
   "type": "integer",
   "maximum": 2100,
   "minimum": 1900,
   "description": "Year to list (default: the datetime's year, else the current year)"
  },
  "datetime": {
   "type": "string",
   "example": "2026-03-08T02:30",
   "description": "Local wall time to check, without offset: YYYY-MM-DDTHH:MM[:SS]"
  },
  "timezone": {
   "type": "string",
   "example": "Asia/Manila",
   "description": "IANA time zone, e.g. Asia/Manila"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "year": 2026,
  "check": {
   "note": "This local time does not exist: clocks jump forward 60 minutes. Most systems shift it forward to 03:30.",
   "local": "2026-03-08T02:30:00",
   "status": "skipped",
   "instants": [],
   "resolved": "2026-03-08T03:30:00-04:00"
  },
  "timezone": "America/New_York",
  "dst_offset": "-04:00",
  "transitions": [
   {
    "type": "clocks_forward",
    "at_utc": "2026-03-08T07:00:00Z",
    "local_after": "2026-03-08T03:00:00-04:00",
    "local_before": "2026-03-08T02:00:00-05:00",
    "offset_after": "-04:00",
    "offset_before": "-05:00",
    "change_minutes": 60
   }
  ],
  "observes_dst": true,
  "standard_offset": "-05:00"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/date-math-dst-timezone-clock-change-lookup-22dcc93f/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from date-math.datemath.workers.dev](https://www.zero.xyz/host/date-math.datemath.workers.dev/llms.txt)
