# Dierum API

> The calendar-aware date API: business-day arithmetic, invoice due dates,
> payday schedules, and holiday calendars for 250+ countries, subdivisions,
> and financial markets (e.g. XNYS). Data coverage 2020-2035; out-of-range
> requests return errors, never guesses.

Base URL: https://dierum.io
Auth: X-Api-Key header (or ?api_key=). Free key: POST /v1/signup {"email": "..."}
  -> 100 requests/day free; paid tiers to 500k/day (/v1/plans).
Errors: {"error": {"code", "message"}} with matching HTTP status.
OpenAPI spec: https://dierum.io/openapi.json

## Endpoints

- GET /v1/check — Classify a date. Is the date a business day, weekend, or holiday in the region? Includes the next business day. Params: region*, date*.
- GET /v1/add — Add business days. Add or subtract (negative) business days to a date. Use market regions like XNYS for settlement math. Params: region*, start*, days*.
- GET /v1/count — Count business days. Business days between two dates, inclusive. Params: region*, from*, to*.
- GET /v1/due-date — Invoice due date. Invoice date plus payment terms (net30, net10b for business days, eom, eom+15), rolled forward off weekends/holidays. Params: region*, invoice_date*, terms*.
- GET /v1/paydays — Payday calendar. A year of pay dates from a rule; dates roll backward off non-working days. Params: region*, year*, rule*.
- GET /v1/nth — Nth business day of each month. The nth business day per month, from either end. 'Invoice on the 3rd business day' schedules. Params: region*, year*, n*, from_end.
- GET /v1/common-days — Common business days. Days that are business days in every listed region. Cross-border settlement windows. Params: regions*, from*, to*.
- GET /v1/window — Next N business days. The next N business days from a date, as a list. Date pickers and schedulers. Params: region*, start*, count.
- GET /v1/diff — Day-type census. How many business days, weekend days, and holidays a range contains. Params: region*, from*, to*.
- GET /v1/year — Year summary. Business-day totals per month plus the full holiday list for a year. Params: region*, year*.
- GET /v1/bridge-days — Bridge-day finder. Leave windows ranked by days-off per PTO day spent. Params: region*, year*, pto.
- GET /v1/next-holiday — Next holiday. Upcoming holidays with a day countdown. Params: region*, count.
- GET /v1/holidays — Holiday list. Raw holiday calendar for a range (max 3 years). Params: region*, from*, to*.
- GET /v1/regions — Region catalog. Every supported region with its weekend definition (day numbers, Sunday=0).
- GET /v1/pay-periods — Pay period generator. Pay periods with rolled paydays. Rules: weekly/biweekly (anchored on a known payday), semi-monthly, monthly. Params: region*, rule*, anchor, from*, count.
- GET /v1/add-hours — Business-hours arithmetic. Add business hours inside a working window; spills across holidays. Local wall-clock times. Params: region*, start*, time*, hours*, window.
- GET /v1/recurrence — Calendar-aware recurring schedules. weekly:<n>:<dow>, nth:<n>:<dow>, last:<dow> with roll policy forward|backward|skip|none. Params: region*, rule*, start*, count, roll.
- GET /v1/quarter — Fiscal quarter progress. Quarter containing a date with business days total/elapsed/remaining; custom fiscal-year start month. Params: region*, date, fiscal_start.
- POST /v1/batch — Batch operations. Up to 100 add/count/check/due-date operations per call (1,000 on Pro+); each metered as one request.

## Free, keyless

- GET /v1/holidays.ics?region=US&year=2027 — iCal feed (calendar apps).
- Interactive playground: https://dierum.io/playground

## Embeddable widgets

- One script (https://dierum.io/embed.js) provides <dierum-countdown>, <dierum-calendar>,
  <dierum-status>, <dierum-office-status>, clocks and more; publishable
  origin-locked keys via POST /v1/public-keys. Catalog: https://dierum.io/embeds

## Notes for agents

- Region codes at GET /v1/regions (includes each region's weekend days).
- Weekends differ by country (Fri-Sat in much of the Middle East; Sat-only Nepal).
- Market calendars (XNYS) differ from national ones: use them for settlement.
- Bare GB = holidays common to the whole UK only (no Easter Monday, no
  summer bank). Use GB-ENG / GB-WLS / GB-SCT / GB-NIR for real UK regions.
- Batch up to 100 operations per POST /v1/batch call.