Countries & Holidays
API Reference

Browse ISO-3166 country metadata, subdivisions, and public holiday data for 130+ countries.

249 Countries
5,046 Provinces
130+ Holiday Calendars

Country Browser

countries/

Metadata

Provinces / Subdivisions (0)

Holiday Browser

holidays/
Select a country and click Load to view holidays.

Countries API

countries/
GET countries/list.json All countries index

Returns an alphabetically sorted array of all 249 ISO 3166-1 countries.

// Response
[
  { "code": "AD", "name": "Andorra" },
  { "code": "AE", "name": "United Arab Emirates" },
  { "code": "IN", "name": "India" },
  // …249 total
]
GET countries/{CC}.json Country detail + subdivisions

Returns full ISO metadata and a sorted list of all provinces/subdivisions. Replace {CC} with the uppercase alpha-2 country code (e.g. IN, US).

// countries/IN.json
{
  "name":                "India",
  "alpha_2":             "IN",
  "alpha_3":             "IND",
  "numeric":             "356",
  "official_name":       "Republic of India",
  "flag":                "🇮🇳",
  "region":              "Asia",
  "sub_region":          "Southern Asia",
  "region_code":         "142",
  "sub_region_code":     "034",
  "iso_3166_2":          "ISO 3166-2:IN",
  "provinces": [
    { "code": "IN-AN", "name": "Andaman and Nicobar Islands", "type": "Union territory" },
    // …36 total
  ]
}

Holidays API

holidays/
GET holidays/{year}/IN/IN.json India national holidays

Returns all general/national calendar holidays for India for the given year.

// holidays/2026/IN/IN.json
[
  {
    "date":         "2026-01-26",
    "day":          "Monday",
    "title":        "Republic Day",
    "holiday_type": "Gazetted"
  },
  // …50 total
]
GET holidays/{year}/IN/IN-{STATE}.json India per-state holidays

Returns state-level public holidays. Replace {STATE} with an Indian state code (e.g. MH, DL, KA). Use list.json to get all state codes.

// holidays/2026/IN/IN-MH.json
[
  {
    "date":         "2026-04-14",
    "day":          "Tuesday",
    "title":        "Dr. Ambedkar Jayanti",
    "holiday_type": "Gazetted"
  }
]
GET holidays/{year}/IN/list.json India state index

Returns all 36 Indian states/UTs with their IN-{STATE} codes and full names.

// holidays/2026/IN/list.json
[
  { "code": "IN-AN", "name": "Andaman and Nicobar Islands" },
  { "code": "IN-AP", "name": "Andhra Pradesh" },
  // …36 total
]
GET holidays/{year}/{CC}/{CC}.json Other countries

Returns public holidays for any of the 130+ supported countries. When counties is non-null, the holiday applies only to those sub-regions.

// holidays/2026/US/US.json
[
  {
    "date":         "2026-07-04",
    "day":          "Saturday",
    "title":        "Independence Day",
    "local_name":   "Independence Day",
    "holiday_type": "Public, Bank",
    "global":       true,
    "counties":     null
  }
]