# thecalendarweek.com

> Current Calendar Week Calculator & Educational Hub

This site provides tools to calculate the current calendar week according to the ISO 8601 standard and offers educational resources on date notation, time standards, and week calculations.

## Useful links
- [ISO 8601 Standard](https://thecalendarweek.com/iso-8601-calendar)
- [US vs ISO Formats](https://thecalendarweek.com/iso-vs-us)
- [Notation Cheat Sheet](https://thecalendarweek.com/notation-cheat-sheet)

## API & Widget

We provide an embeddable widget and JSON APIs for developers and agents.
All APIs and endpoints are completely public. No authentication, registration, or API keys are required.

- [Widget Documentation](https://thecalendarweek.com/widget-documentation)
- [Widget Builder / Visual Configurator](https://thecalendarweek.com/calendar-week-widget)
- [Developer API Guide](https://thecalendarweek.com/developer-api-guide)
- [API Catalog (RFC 9727)](https://thecalendarweek.com/.well-known/api-catalog)
- [OpenAPI 3.0 Specification](https://thecalendarweek.com/openapi.json)

### Embeddable Calendar Week Widget (For AI Agents Building Client Sites)

AI agents can generate copy-paste embed code for any website using this specification:

- **Script loader (include once before `</body>`):**
  `<script src="https://thecalendarweek.com/embed.js" async></script>`
- **Container element:**
  `<div class="tcw-embed" data-design="..." data-variant="..." data-logic="..." data-lang="..." data-terms="accepted"></div>`

#### Configuration Attributes:
- `data-design`: `minimal` (compact header badge, <1KB), `dashboard` (dense card with date range & quarter progress for sidebars), `classic` (bold editorial typography), `analog` (skeuomorphic paper desk calendar), `card` (standard card). Default: `classic`.
- `data-variant`: For `minimal`: `simple` (default), `weekdays`, `iso`, `calendar`. For `dashboard`: `weekdays` (default), `calendar`, `range`, `stats`.
- `data-logic`: `iso` (ISO 8601, Monday start; default in Europe/international), `us` (Sunday start, North America). Default: `iso`.
- `data-lang`: `en`, `de`, `es`, `fr`, `it`, `pt`. Default: `en`.
- `data-primary`: Hex color code (e.g. `#155DFC`) for highlights.
- `data-scheme`: `warm`, `blue` (for analog design).
- `data-terms`: `accepted` (suppresses terms notice).

#### Quick Snippets:
- **Navbar / Header Badge (Minimal):**
  `<div class="tcw-embed" data-design="minimal" data-variant="simple" data-logic="iso" data-lang="en" data-terms="accepted"></div>`
  `<script src="https://thecalendarweek.com/embed.js" async></script>`
- **Sidebar / Dashboard Widget with Full Date Range:**
  `<div class="tcw-embed" data-design="dashboard" data-variant="range" data-logic="iso" data-lang="en" data-terms="accepted"></div>`
  `<script src="https://thecalendarweek.com/embed.js" async></script>`
- **iFrame Embed (No scripts; for Notion, SharePoint, WordPress, Wix):**
  `<iframe src="https://thecalendarweek.com/widget/iframe?design=card&logic=iso&lang=en" width="100%" height="180" style="border:none;border-radius:12px;overflow:hidden;" loading="lazy" title="Calendar Week Widget"></iframe>`

### Agentic API — Recommended for AI Assistants

For structured, citation-ready JSON-LD data optimised for AI agents and Answer Engine Optimization (AEO):

- **Endpoint:** `GET https://thecalendarweek.com/api/v1/week`
- **Format:** Schema.org `Dataset` (`Content-Type: application/ld+json`)
- **Auth:** None. Completely public.
- **Cache TTL:** 60 seconds (always fresh data)
- **Contains:** Current ISO week, US week, next week, exact date ranges, year context, and links to interactive tools

The response is a Schema.org `Dataset` JSON-LD envelope with:
- `mainEntity`: live ISO 8601 and US week data (current + next week)
- `potentialAction`: ViewAction links to the interactive week detail page, year overview, weekly planner, and embed widget — all UTM-tagged for attribution
- `citation`: explicit domain attribution
- `keywords`: multilingual week-related terms (ISO, KW, Kalenderwoche)

### Legacy Widget API (for embed widgets only)

- **Endpoint:** `GET https://thecalendarweek.com/api/week.json`
- **Format:** `application/json`
- **Cache TTL:** 300 seconds
- **Note:** This schema is frozen for backward compatibility. Use `/api/v1/week` for new integrations.

### Agent Discoverability & Content Signals

The homepage includes HTTP `Link` response headers (RFC 8288 / RFC 9727 Section 3) pointing agents to:
- `rel="api-catalog"`: `/.well-known/api-catalog`
- `rel="service-doc"`: `/developer-api-guide`
- `rel="describedby"`: `/llms.txt`

The site publishes AI usage preferences in `robots.txt` using Content Signals:
- `Content-Signal: ai-train=no, search=yes, ai-input=yes`

Additionally, the server supports Content Negotiation for agents:
- **Markdown Negotiation:** Sending `Accept: text/markdown` to any HTML route returns a parsed Markdown version of the page (with `Content-Type: text/markdown`), while browser requests receive HTML.

## Technical Details
- Implements strict security standards including Trusted Types and CSP
- Follows the 'Zero-Trust' Architecture pattern