डेवलपर और AI टूल

समय, समय क्षेत्र, छुट्टियों और कार्यदिवसों की जानकारी पाएँ तथा डेटा स्रोत और कवरेज देखें।

छुट्टियाँ कैलेंडर के नियमों से तैयार की जाती हैं और पूर्ण आधिकारिक कार्य कैलेंडर नहीं दर्शातीं। कवरेज अपर्याप्त होने पर सख्त क्वेरी त्रुटि लौटाती हैं।

current_time

ClockZone developer reference

Anonymous, read-only time and calendar queries. No API key required.

Discovery

Queries

current_time

Read a timezone clock snapshot. at fixes the instant for reproducibility. Endpoint: /api/time/now (GET or POST)

Example JSON body:

{
  "tz": "Asia/Shanghai"
}

dst

Read timezone offset changes. Offset transitions do not always mean daylight saving. Endpoint: /api/time/dst (GET or POST)

Example JSON body:

{
  "tz": "America/New_York"
}

holidays

List rule-derived holidays, including provenance and coverage limitations. Endpoint: /api/holidays (GET or POST)

Example JSON body:

{
  "country": "US",
  "year": 2026
}

next_holidays

List upcoming holidays using an explicit local date and timezone. Endpoint: /api/holidays/next (GET or POST)

Example JSON body:

{
  "country": "US",
  "tz": "America/New_York",
  "limit": 2
}

catalog

Discover supported countries, regions, years and timezone candidates. Ambiguous names are not resolved automatically. Endpoint: /api/v1/catalog (GET or POST)

Example JSON body:

{
  "kind": "timezones",
  "q": "Beijing"
}

convert_time

Convert a local time or explicit instant between IANA timezones. Reject ambiguous or nonexistent local times by default. Endpoint: /api/v1/time/convert (GET or POST)

Example JSON body:

{
  "from": "America/New_York",
  "to": "Asia/Shanghai",
  "datetime": "2026-11-09T09:00:00"
}

business_days

Count a date interval or add signed working days under explicit rules. This is not an authoritative employment calendar. Endpoint: /api/v1/business-days (GET or POST)

Example JSON body:

{
  "start": "2026-11-05",
  "days": 10
}

meeting_slots

Find 15-minute-grid meeting starts inside all participants local working windows. Endpoint: /api/v1/meeting-slots (POST)

Example JSON body:

{
  "start": "2026-11-09",
  "end": "2026-11-09",
  "participants": [
    {
      "tz": "Asia/Shanghai"
    },
    {
      "tz": "Europe/London"
    }
  ]
}

Time semantics

Dates use YYYY-MM-DD. Instants include Z or an offset. IANA timezones or supported slugs are required. A timezone lookup returns candidates, never a guessed match. Current time uses no-store. Country/year holiday lists and catalog GET queries support private one-hour caching and content-derived ETags. at pins a time snapshot; upcoming holidays defaults to today in tz (UTC by default). DST flags are offset-based estimates, not an authoritative legal classification. nextTransition is the next offset change, precise to a second; timezone data comes from the runtime.

Local conversions reject ambiguous/nonexistent times by default. disambiguation=earlier or later explicitly selects Temporal's corresponding interpretation. An offset-bearing datetime denotes an absolute instant.

Calendar coverage

Results are derived from date-holidays and ClockZone overrides. They are not complete official work calendars. Sources, rule version, confirmation and limitations accompany calendar results. Unknown update dates are null. Do not treat response generation time as a source update. The catalog lists supported years; upcoming queries report searchThrough if next-year data is unavailable.

Working-day ranges include both endpoints by default; add/subtract excludes the start date. Weekdays use ISO numbering (Monday=1, Sunday=7). Extra working dates override extra holidays, public holidays and weekends. Only public holidays are excluded. Defaults: Saturday/Sunday weekends. strict=true with a country rejects incomplete official calendar coverage. A custom weekday query without country is a deterministic rules calculation, not a country calendar. Maximum range/scanning distance: 3660 days.

Meeting date ranges are UTC dates (maximum 31); working windows apply in each participant's own timezone. Default 09:00–17:00 Monday–Friday, no holiday exclusions, 60-minute duration, 15-minute candidate grid, at most 20 results and 10 participants. Same-day working windows only. Holiday exclusion requires country for every participant. Returned windows can overlap; each is a possible start, ordered earliest first.

Responses and errors

Every successful individual query includes normalized query and pageUrl to reproduce it. Follow pageUrl on the same origin. Calendar results include coverage; clocks include localDate, localDateTime, offsetMinutes and updatedAt. Conversion has from/to snapshots; working days have start/end/businessDays/rules; meeting queries have slots with UTC and local boundaries; catalog results have items,total,nextOffset.

Invalid input: HTTP 400, coverage/range failure: 422, quota: 429, body over 64 KiB: 413. JSON errors use error, message and optional details. Empty results mean a valid query found nothing, never a parse failure. A batch returns results with ok and data or an error. GET array parameters are JSON-encoded; POST accepts typed JSON.

Limits and privacy

60 computation units per source per minute; ordinary query=1, meeting query=5, batch=sum. Additional protocol/request limit: 120 limiter checks per minute (a computation request uses two checks). Quotas are shared by REST and MCP. Honor Retry-After and X-RateLimit-* headers. Maximum batch:20, body:64 KiB. Current quota storage is process-local, not a global distributed quota. Without a configured trustworthy proxy header, clients share one conservative quota.

AGENT_TRUSTED_IP_HEADER may only name a header stripped and rewritten by a trusted ingress proxy. Do not trust arbitrary X-Forwarded-For. AGENT_MCP_ORIGINS is a comma-separated browser-origin allowlist; absent Origin is accepted for native clients. No production configuration is changed by this feature.

Query URLs contain input parameters. Do not put names, secrets or personal information in them. Server logs contain operation, status, duration and request ID, not complete query inputs.

MCP client configuration

Configure a remote Streamable HTTP server URL https://clockzone.net/mcp in your MCP client. For local acceptance use http://localhost:3356/mcp. Tools use the same names and schemas as the queries above; tool results include structuredContent and a JSON text fallback. Business errors set isError. The server supports the protocol versions negotiated by its pinned official SDK. It does not send notifications or maintain persistent sessions.

Compatibility

Existing API paths and successful legacy fields remain available. Invalid type/limit values now return 400 instead of a misleading empty success. Additive fields must be ignored by older clients. This release does not claim an official working-day calendar or promise discovery by every AI search engine.

डेवलपर और AI टूल · ClockZone