{"uid":"cap_O-9RJBIan1Fh28eiJvSbn","slug":"date-math-natural-language-date-parser-3fe047f0","name":"Date Math – Natural Language Date Parser","description":"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.","url":"https://date-math.datemath.workers.dev/v1/parse?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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)"}}},"responseSchema":{"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"}},"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_d1gHAg7G2Hagwg8zOOoXi","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":"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.","exampleAgentPrompt":"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?","exampleUseCases":[{"title":"Scheduling assistant date resolution","prompt":"My user said they want a meeting 'next Thursday at 2pm' — I'm in London (Europe/London) and today is 2024-06-10T10:00:00. What's the exact UTC datetime for that?"},{"title":"Event deadline parsing from user input","prompt":"A user typed 'in 3 weeks' as their project deadline. Can you resolve that to an exact date, treating today as 2024-06-05T00:00:00 in the America/Chicago timezone?"},{"title":"Date range extraction for travel booking","prompt":"Someone said they want to travel 'Dec 25 to Jan 2' — resolve both of those to exact ISO datetimes in the Asia/Manila timezone so I can search for flights."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-11-21T12:35:53.625Z","isFirstParty":false,"canonicalSlug":"date-math-natural-language-date-parser-3fe047f0"}