Developers

Parse English into dates. Use the playground, the unpublished TypeScript package, or GET /api/parse.

TypeScript package

Parse one phrase or a batch. Reuse a parser with a fixed context. The package is not published yet.

import { parse } from "@tempus-date/core";

const result = parse("Call Sam tomorrow at noon", {
  timezone: "America/Chicago",
  reference: "2026-09-12T16:00:00Z",
});

// Branch on result.status before using a date.
// Resolved values include their kind and source text.

Package source

From the repository root, run pnpm build:sdk, then pnpm pack in packages/core. Install the tarball by absolute path. CommonJS is not provided.

Branch on result.status before using a date. When the status is needs-clarification, show the question and choices. Do not pick a date silently.

resolved: Use the value. kind is point, interval, collection or recurrence.
needs-clarification: Show the offered question and choices, if present. Otherwise show the error and let the user edit.
unsupported: Show the reason and let the user edit.
no-expression: Keep the text; there is no date to act on.

Clear previous choices when the phrase, timezone or reference changes. A recurrence includes a preview, not necessarily every occurrence.

Optional @tempus-date/core/calendar prepares complete schedules and files. Calendar-client imports and physical-device behavior remain unverified. Keep the result inspectable before your app acts on it.

HTTP API

GET /api/parse returns a calculated date as JSON. No API key. It does not clarify ambiguous input or expand recurrences. Check API result on the playground sends the highlighted date phrase, not a full reminder sentence.

curl --get 'https://tempus.funnydomainname.com/api/parse' \
  --data-urlencode 'expression=jan 31 2026 plus 1 month' \
  --data-urlencode 'timezone=America/Chicago' \
  --data-urlencode 'reference=2026-01-26T19:30:00.000Z'

That request returns 28 February 2026 at midnight in Chicago: 2026-02-28T06:00:00.000Z.

expression: Required. The phrase to calculate. Up to 200 characters.
timezone: Optional. An IANA timezone, such as America/Chicago. Defaults to UTC.
reference: Optional. A starting instant with an offset, such as 2026-01-26T19:30:00Z. Defaults to the request time; reuse it to reproduce a result.
format: Optional. A date-fns display format, such as yyyy-MM-dd. Does not change the calculation.

About 120 requests per minute per IP at each Cloudflare location. HTTP 429 means wait a minute; HTTP 503 means try again shortly. Invalid, unknown or repeated parameters return HTTP 400. URLs over 4,096 characters return HTTP 414. Responses are not cached.

Engine v2 removed preserveDayOfMonth. Omit it from requests. The API is stateless; your integration owns storage and external actions. Request URLs include the phrase. Privacy details