# Date Math – Natural Language Date Parser

> Date Math – Natural Language Date Parser 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).

Resolves natural-language date/time expressions like 'next Friday at 3pm' or 'in 2 weeks' to exact UTC and local datetimes, relative to a reference time and timezone.

## Facts

- Endpoint: POST https://date-math.datemath.workers.dev/v1/parse?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-natural-language-date-parser-3fe047f0
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_O-9RJBIan1Fh28eiJvSbn

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-natural-language-date-parser-3fe047f0 -d '<json body>'
```

Example prompt: What exact date and time is 'next Friday at 3pm' if I'm in the America/New_York timezone and today is 2024-06-10T09:00:00?

## When to prefer this

Use this endpoint when you need to convert free-form, human-typed date/time expressions into precise machine-readable datetimes — especially when user input is ambiguous, relative, or uses natural language like 'next week', 'end of the month', or 'in 2 days'. Prefer this over manual date parsing logic or general LLM inference when accuracy, timezone correctness, and DST-awareness are critical.

## Known failure modes

- Ambiguous or unrecognizable date text returns zero results or low-certainty output
- Invalid or unsupported timezone string causes an error response
- Reference datetime in wrong format (not ISO 8601) may cause parsing failure
- Very long or malformed text input may exceed the 1000-character limit
- Network or payment errors (402) if USDC balance is insufficient

## How this service works

Date Math: Parse natural-language dates and relative times like "next Friday at 3pm", "in 2 weeks", "tomorrow morning" or "Dec 25 to Jan 2" into exact ISO datetimes, relative to a reference time and time zone. Use before acting on any date a user typed.

## Output

Returns a JSON object with the parsed date text, count of results, and an array of resolved date objects — each including UTC datetime, local datetime, date string, weekday, certainty indicators, and the matched portion of the input. Also echoes back the reference time and timezone used.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "text": {
   "type": "string",
   "example": "next friday at 3pm",
   "maxLength": 1000
  },
  "timezone": {
   "type": "string",
   "description": "Default UTC"
  },
  "reference": {
   "type": "string",
   "description": "ISO 8601 datetime the text is relative to; default now"
  },
  "forward_date": {
   "type": "boolean",
   "description": "Prefer future dates for ambiguous text (default true)"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "text": "next friday at 3pm",
  "count": 1,
  "results": [
   {
    "index": 0,
    "start": {
     "utc": "2026-11-13T07:00:00Z",
     "date": "2026-11-13",
     "local": "2026-11-13T15:00:00+08:00",
     "weekday": "Friday"
    },
    "certain": [
     "weekday"
    ],
    "matched": "next friday at 3pm"
   }
  ],
  "timezone": "Asia/Manila",
  "reference": "2026-11-07T14:00:00+08:00"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/date-math-natural-language-date-parser-3fe047f0/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)
