---
title: "Parse a natural-language date query and answer it"
method: GET
path: "/api/v1/parse"
---

# Parse a natural-language date query and answer it

`GET /api/v1/parse`

## Request

- Base URL: `https://tilwhen.com`
- URL: `https://tilwhen.com/api/v1/parse`
- Auth: none declared

## Query parameters

- `q` string, required
- `tz` string: IANA timezone name; defaults to UTC.
- `locale` 'mdy' | 'dmy'

## Response `200`

Parse outcome; parsed may be null with warnings or needsClarification

- ParseResult
  - `parsed` object, nullable
  - `confidence` number
  - `warnings` string[]
  - `needsClarification` object
  - `canonicalPath` string, nullable
  - `answer` object
  - `receipt` Receipt: Auditable calculation record; field order in serialized responses is stable.
    - `id` string
    - `query` object
    - `resolved` object
    - `answer` object
    - `timezone` string
    - `convention` 'exclusive-today-is-day-0'
    - `workweek` 'mon-fri' | 'sun-thu' | 'mon-sat'
    - `jurisdiction` string, nullable
    - `customHolidays` string[]
    - `holidaysExcluded` object[]: Itemised excluded holidays, capped at 500; see holidaysExcludedCount for the true total.
      - `name` string
      - `dateISO` string
    - `holidaysExcludedCount` integer: Total holidays excluded by the calculation. Exceeds holidaysExcluded.length on very wide spans, where a holiday_list_truncated warning also appears.
    - `computedAt` string, date-time
    - `validFor` string, date
    - `engineVersion` string
    - `holidayDatasetVersion` string
    - `warnings` object[]
      - `code` string
      - `message` string
    - `sources` object[]
      - `title` string
      - `url` string
      - `publisher` string
      - `retrievedAt` string

## Other responses

- `400`: Machine-readable error
- `429`: Rate limited. The API is free and unauthenticated, so requests are metered per IP at 300 per 60 seconds. Counters are per Cloudflare location and eventually consistent, so this is an abuse brake rather than an exact quota. Retry-After gives the window.

---

[API](https://skmtc.dev/tilwhen/apis/tilwhen-date-api.md) · [All operations](https://skmtc.dev/tilwhen/apis/tilwhen-date-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tilwhen/apis/tilwhen-date-api/revisions/73e321edeaaa?raw)