Data you
can trace.

The Utsavs API reconciles public calendars with institutional closures and regional rules. Built for technical systems that require high-stakes date precision.

response_example.json

GET/api/v1/intelligence?jurisdiction=IN&date=2026-11-08

{
  "status": "success",
  "query": {
    "jurisdiction": "IN",
    "date": "2026-11-08",
    "purpose": "travel"
  },
  "metadata": {
    "timestamp": "2026-10-01T00:00:00.000Z",
    "source_connected": true,
    "version": "4.2.0-static-first",
    "now_resolved": "2026-10-01"
  },
  "records": [
    {
      "id": "RULE_IN_Diwali_dated_2026__2026-11-08",
      "rule_id": "RULE_IN_Diwali_dated_2026",
      "name": "Diwali",
      "category": "public",
      "jurisdiction": {
        "country_code": "IN",
        "country_name": "India",
        "scope": "national"
      },
      "temporal_kind": "recurring",
      "state": "confirmed",
      "confidence": "high",
      "evidence": {
        "source_name": "DoPT OM F.No.12/2/2023-JCA",
        "source_url": "https://example.com/holidays.pdf",
        "last_checked": "2026-09-05"
      },
      "consequences": {
        "implication": "National Holiday. Mandatory commercial shutdown in most states.",
        "severity": "high"
      }
    }
  ]
}

Documentation

Developer Quickstart

01. Authentication

Every request must include an X-API-KEY header. Access is restricted to authorized partners.

02. Parameters

jurisdiction

Required. ISO 3166-1 alpha-2 country code (e.g., IN, JP, US).

date

Required. ISO-8601 date string (YYYY-MM-DD).

purpose

Optional. Context filter: travel, business, study, workforce, or logistics. Default: travel.

03. Response Schema

Our engine returns a materialized_record. This is a computed result based on the intersection of the date, jurisdiction-specific rules, and the chosen user purpose.

cURL Example

curl -X GET "https://utsavs.com/api/v1/intelligence" \
  -H "X-API-KEY: YOUR_KEY" \
  -G \
  --data-urlencode "jurisdiction=IN" \
  --data-urlencode "date=2026-11-08"

Status Codes

200 — Successful query

400 — Invalid request parameters (Date/Jurisdiction/Purpose)

401 — Missing or invalid API key

500 — Server configuration failure

Integration Roadmap

Four steps to production-grade intelligence.

Partner Request

Initiate contact via the support chat. Our team evaluates jurisdiction requirements and volume tiers.

Sandbox Token

Receive a restricted key for local development and schema validation in your testing environment.

Schema Alignment

Map your application purpose (travel/study/biz) to our deterministic record logic.

Production Key

Rotate to a production-grade X-API-KEY with SLA-backed uptime and verified data refreshes.

Data you can trace.