# Date Math – Difference Between Two Dates

> Date Math – Difference Between Two Dates 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-19).

Calculates the difference between two dates or datetimes, returning calendar breakdown (years/months/days), total days/weeks/hours, ISO duration, and business days (excluding weekends, public holidays, and custom holidays).

## Facts

- Endpoint: POST https://date-math.datemath.workers.dev/v1/diff?utm_source=zero.xyz
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-19
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/date-math-difference-between-two-dates-9f21a2d8
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_29OB8uLnuNkVuF9EaA2F7

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-difference-between-two-dates-9f21a2d8 -d '<json body>'
```

Example prompt: How many calendar days and business days are there between January 31 2026 and March 15 2026, excluding US public holidays?

## When to prefer this

Choose this endpoint when you need a precise breakdown of the difference between two dates — especially when business-day calculation excluding country-specific public holidays is required. It is better than simple arithmetic when weekends, local holidays, or custom rest days must be excluded. Prefer it over generic date libraries when you need ISO duration strings, calendar decomposition (years + months + days), and configurable workweeks (e.g. Sun–Thu for Middle East calendars) in a single API call.

## Known failure modes

- Invalid date format returns a 400 error — dates must be YYYY-MM-DD or ISO 8601 with timezone offset
- Unsupported or malformed country code returns an error — must be valid ISO 3166-1 alpha-2
- 'from' date after 'to' date still returns a result but with 'direction' set to 'backward' — agents should handle negative/reverse ranges
- Custom holidays array exceeding 1000 items is rejected
- Workdays array with no items (minItems:1 violated) returns a validation error
- Payment not included or insufficient USDC balance returns HTTP 402

## How this service works

Date Math: How many days, weeks, months or business days between two dates or datetimes: calendar (Y/M/D), totals, and business days (weekdays in [from, to) minus holidays; pass country to exclude its public holidays). Use for age, tenure, countdowns, notice periods and working days until a deadline.

## Output

A JSON object containing: 'calendar' with years, months, and days breakdown; 'total_days' as an integer; 'total_weeks' as an integer; 'business_days' as an integer (weekdays minus weekends, public holidays for the given country, and any custom holidays); 'iso_duration' as a standard ISO 8601 duration string (e.g. P1M15D); and 'direction' indicating whether the range is forward or backward.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "to": {
   "type": "string",
   "example": "2026-11-07T14:30:00Z",
   "description": "YYYY-MM-DD, or ISO 8601 datetime with Z or offset"
  },
  "from": {
   "type": "string",
   "example": "2026-11-07T14:30:00Z",
   "description": "YYYY-MM-DD, or ISO 8601 datetime with Z or offset"
  },
  "country": {
   "type": "string",
   "example": "US",
   "pattern": "^[A-Za-z]{2}$",
   "description": "ISO 3166-1 alpha-2 country code (207 countries); its public holidays (2000–2050) are excluded from business days"
  },
  "holidays": {
   "type": "array",
   "items": {
    "type": "string",
    "example": "2026-11-07",
    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
   },
   "maxItems": 1000,
   "description": "Extra dates excluded from business-day counts (rest days from workdays are always excluded)"
  },
  "workdays": {
   "type": "array",
   "items": {
    "type": "integer",
    "maximum": 6,
    "minimum": 0
   },
   "example": [
    1,
    2,
    3,
    4,
    5
   ],
   "maxItems": 7,
   "minItems": 1,
   "description": "Working days of the week, 0 = Sunday. Default [1,2,3,4,5] (Mon–Fri); e.g. [0,1,2,3,4] for Sun–Thu or [1,2,3,4,5,6] for Mon–Sat"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "to": "2026-03-15",
  "from": "2026-01-31",
  "calendar": {
   "days": 15,
   "years": 0,
   "months": 1
  },
  "direction": "forward",
  "total_days": 43,
  "total_weeks": 6,
  "iso_duration": "P1M15D",
  "business_days": 29
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/date-math-difference-between-two-dates-9f21a2d8/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)
