{"uid":"cap_29OB8uLnuNkVuF9EaA2F7","slug":"date-math-difference-between-two-dates-9f21a2d8","name":"Date Math – Difference Between Two Dates","description":"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.","url":"https://date-math.datemath.workers.dev/v1/diff?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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"}}},"responseSchema":{"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}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.001","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.001/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.001","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.001","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_HJ3v0DHExB8XWDG3yhxdG","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.001","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"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).","exampleAgentPrompt":"How many calendar days and business days are there between January 31 2026 and March 15 2026, excluding US public holidays?","exampleUseCases":[{"title":"Project deadline business-day countdown","prompt":"How many business days are left between today, June 2 2025, and our project deadline on August 29 2025, excluding UK public holidays?"},{"title":"Invoice payment terms calculation","prompt":"A client invoice is dated March 1 2026 and payment terms are net-30 business days — what's the exact number of working days to April 30 2026, skipping US holidays?"},{"title":"HR probation period elapsed time","prompt":"An employee started on September 15 2025 and their 90-day probation ends December 31 2025 — can you tell me the calendar breakdown in years, months, and days, plus total business days?"}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-11-19T23:42:57.031Z","isFirstParty":false,"canonicalSlug":"date-math-difference-between-two-dates-9f21a2d8"}