---
title: "A small calendar API | Grid & Calendar"
description: "Read-only JSON dates and holiday snapshots."
url: https://gridandcalendar.com/api/
updated: 2026-10-03
site: "Grid & Calendar"
language: en
---

# A small calendar API

## Holiday endpoint

GET /api/v1/holidays/US/2027 returns national US holidays, including observed dates. Use a two-letter country code or a supported country slug. Data covers 2020–2030. Regional holidays are excluded.

## Calendar endpoint

GET /api/v1/calendar/2027/1?week\_start=monday returns the month’s day count, offset, rows, day cells, and ISO week labels. Month can be a number or an English month name.

## Requests & errors

Responses are JSON with no authentication required. The limit is 120 requests per network address per minute. An invalid date or country returns 400 or 404. A request over the limit returns 429 with Retry-After: 60.

## Public references and discovery

Eligible guides have .md references, with /index.md for home. Accept: text/markdown selects the same public document, respecting quality values and zero-quality exclusions. /sitemap/ lists every eligible guide. /llms.txt maps printable families; /llms-full.txt contains all eligible guides, date tables, meaningful preview text, source links and non-personal default form examples. /llms-manifest.json records scope and hashes. Submitted settings, personalized text, downloads/previews, search outputs, embeds and unindexed custom dates are excluded.

## Actual API behavior

/.well-known/api-catalog lists the two existing JSON endpoints and links /api/openapi.json. GET and HEAD share the 120-request sliding 60-second window; HEAD has no body. OPTIONS returns 405. Calendar query year/month override path values before effective bounds are checked; country supplies its default week start when week\_start is omitted. Shared printable options validate even when they do not affect returned geometry; unknown keys and variant are ignored. Holiday queries are ignored. Repeated PHP query names use the last value; arrays on recognized calendar options return 400. API results are no-store/noindex. Source or publication dependency failure returns a neutral 503 with Retry-After; no runtime build occurs.

## Use with attribution

Use the data with a link to Grid & Calendar and the original holiday source. The holiday dataset is supplied by the MIT-licensed Nager.Date project; see Sources for provenance.

[Try the calendar endpoint](https://gridandcalendar.com/api/v1/calendar/2027/1?week_start=monday) or [view US holidays](https://gridandcalendar.com/api/v1/holidays/US/2027).

Last updated 2026-10-03