REST API reference

Overview

Base URL https://fatcalendar.com. All endpoints are GET, return JSON, need no authentication and send Access-Control-Allow-Origin: *. The machine-readable contract is /openapi.json.

Endpoints

MCP tool	REST endpoint	What it returns
get_month	GET /api/v1/calendar/month	Get a month calendar
get_week	GET /api/v1/calendar/week	Get a week calendar
get_year	GET /api/v1/calendar/year	Get a year calendar
get_day	GET /api/v1/calendar/day	Get a full day (panchang) view
get_panchang	GET /api/v1/panchang	Get the raw normalised panchang
list_festivals	GET /api/v1/festivals	List festivals of a year
search_places	GET /api/v1/places	Search places (geocoder)
list_traditions	GET /api/v1/traditions	List calendar traditions
list_languages	GET /api/v1/languages	List display languages
-	GET /api/v1/health	Liveness check

Common parameters

Parameter	Type	Description
tradition	enum	gregorian, telugu, tamil, kannada, malayalam, marathi, gujarati, punjabi, bengali, hindi, muslim, christian (default gregorian)
lang	enum	en, te, ta, kn, ml, mr, gu, pa, bn, hi, ur (default en)
variant	string	Tradition sub-variant, see /api/v1/traditions. tamil: thirukanitha	vakya; kannada: smarta	madhva; malayalam: default	nazhika; punjabi: nanakshahi	desi	hindu; bengali: west-bengal-bisuddha	west-bengal-gupta	bangladesh; hindi: purnimanta	amanta	varanasi	braj	awadh; muslim: india	astronomical	tabular	hanafi	shia; christian: western	orthodox	catholic	protestant
lat, lon, tz	number, number, IANA zone	Explicit location
place	string	Free-text place; first geocoder hit is used
date	YYYY-MM-DD	Day or week anchor (default today)
year, month	integer	Gregorian year (1900-2200) and month (1-12)

If no location is given, it is inferred from the request IP (Cloudflare) and the response is private.

Examples

# Month grid in Tamil tradition, displayed in Tamil
curl 'https://fatcalendar.com/api/v1/calendar/month?tradition=tamil&lang=ta&year=2026&month=11&place=Chennai'

# Full panchang for a day
curl 'https://fatcalendar.com/api/v1/calendar/day?tradition=telugu&date=2026-11-08&lat=17.385&lon=78.4867&tz=Asia/Kolkata'

# Festivals of a year (Punjabi, Nanakshahi variant)
curl 'https://fatcalendar.com/api/v1/festivals?tradition=punjabi&variant=nanakshahi&year=2026&place=Amritsar'

# Geocode
curl 'https://fatcalendar.com/api/v1/places?q=Vijayawada'

const res = await fetch('https://fatcalendar.com/api/v1/calendar/day?tradition=muslim&place=Hyderabad');
const day = await res.json();
console.log(day.hijri, day.prayers);

Response shapes

month, week, year and day return MonthResponse, WeekResponse, YearResponse and DayResponse as defined in the OpenAPI document and in @fatcalendar/core. Each includes tradition, lang, the resolved location, a localized header (title, eras, months spanned) and notes (method and accuracy remarks). Time values are { iso, local } pairs: iso is UTC, local is wall time at the location with a trailing + after local midnight. /api/v1/panchang returns the language-independent normalised record.

Caching

Explicit-location responses: Cache-Control: public, max-age=300, s-maxage=86400, stale-while-revalidate=604800 plus a weak ETag (send If-None-Match for 304). Location-inferred responses: private, max-age=60.

Errors

Errors use application/problem+json (RFC 9457):

{ "type": "about:blank", "title": "Invalid parameters", "status": 400, "detail": "date: date must be YYYY-MM-DD", "instance": "/api/v1/calendar/day?date=tomorrow" }

Statuses: 400 invalid parameters, 404 unknown place or path, 429 rate limited, 502 upstream ephemeris failure, 500 internal error.

Rate limits

120 requests per 60 seconds per client IP across /api, /mcp, /a2a and /ask. Responses include RateLimit-Policy: "default";q=120;w=60 and RateLimit: "default";r=<remaining>;t=<seconds to reset>. A 429 response carries Retry-After. The limit is best effort per edge location; cached responses are the better route for bulk use.

Authentication

None. The API is public and anonymous.