---
title: "Get countries available for holiday calendars"
method: GET
path: "/api/v2/holiday_calendars/countries"
tags: ["Holiday calendars"]
---

# Get countries available for holiday calendars

`GET /api/v2/holiday_calendars/countries`

## Request

- Base URL: `https://developer.productive.io` (the document declares no server; this is the origin it was published from)
- URL: `https://developer.productive.io/api/v2/holiday_calendars/countries`
- Auth: none declared

Returns the countries and their subdivisions that can be used for automatic holiday generation. Use the returned `code` values as the holiday calendar `country` and `state` attributes. Requires permission to manage holidays.

This is a plain JSON response (not JSON:API). The list is proxied from holidayapi.com and cached for 24 hours; if the provider is unavailable, `countries` is an empty array.

## Response `200`

List of supported countries with their subdivisions.

- object: Wrapper object holding the `countries` array.
  - `countries` object[]: Supported countries, each with ISO codes, languages, currencies and subdivisions.
    - `code` string: ISO 3166-1 alpha-2 country code (e.g. `US`). Use it as the holiday calendar `country` attribute.
    - `codes` object: Alternative ISO 3166-1 representations of the country code.
      - `alpha-2` string: ISO 3166-1 alpha-2 code.
      - `alpha-3` string: ISO 3166-1 alpha-3 code.
      - `numeric` string: ISO 3166-1 numeric code.
    - `currencies` object[]: Currencies used in the country.
      - `alpha` string: ISO 4217 currency code.
    - `flag` string, uri: URL of the country flag image.
    - `languages` string[]: ISO 639-1 codes of the languages in which holiday names are available for this country.
    - `name` string: English name of the country.
    - `subdivisions` object[]: States or regions with their own regional holidays. Use the subdivision `code` as the holiday calendar `state` attribute.
      - `code` string: ISO 3166-2 subdivision code (e.g. `US-CA`).
      - `languages` string[]: ISO 639-1 codes of the languages used in the subdivision.
      - `name` string: Name of the state or region.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `408`: Request Timeout
- `423`: Locked
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-11-02** `fa3060fd0144`: 6 info
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - added the non-success response with the status `408`
  - added the non-success response with the status `423`
  - …2 more
- **2026-10-27** `f11a8740641a`: 1 info
  - endpoint added
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/productive/apis/api-documentation/changes/api/v2/holiday_calendars/countries/get.md)

---

[API](https://skmtc.dev/productive/apis/api-documentation.md) - [All operations](https://skmtc.dev/productive/apis/api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/productive/apis/api-documentation/revisions/e7bdfdf6cba3?raw)