List holidays by country

GET

/holidays/{country}/{year}

Last modified:2026-09-28 00:01:50

OperationId:ReadHolidayInformationCountry

Returns the holidays of a country in one year, to fill the holidays of a holiday or custom time frame. Any authenticated token can call it: holiday data is not scoped to a domain, and no scope privilege is checked.

Each holiday gives the values a holiday time frame entry needs: uuid becomes timeframe-holiday-uuid, name timeframe-holiday-name, date timeframe-holiday-begin-date, country country-abbreviation, and locations holiday-api-location-hint. date is an integer YYYYMMDD. states is All, or a list of the region codes the holiday applies in.

Holidays come from the platform's holiday lookup service, a hosted Calendarific proxy the API calls over HTTPS with a 3-second connect and 8-second total limit. Answers are cached for 24 hours per country, region, year, and language; failures are not cached. If the service fails, times out, or answers anything but a holiday list, the call returns 503; retry later.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Query Params

Body Params application/json

Examples

Responses

🟢200OK

application/json

The holidays, in the order the lookup sends them.

Bodyapplication/json

🟠401Authentication Required

🔴503Service Unavailable

🟠400Bad Request

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://awqacore01.crexendocloud.com/ns-api/v2/holidays/US/2026?language=en' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'

Response Example

200 - Holidays

Two United States holidays.

[
    {
        "uuid": "3f1b2c4d5e6f708192a3b4c5d6e7f809",
        "name": "Thanksgiving Day",
        "description": "Thanksgiving Day is a federal holiday in the United States.",
        "country": "us",
        "date": 20261126,
        "type": [
            "National holiday"
        ],
        "primary_type": "Federal Holiday",
        "locations": "All",
        "states": "All"
    },
    {
        "uuid": "5e6f708192a3b4c5d6e7f8091a2b3c4d",
        "name": "Lincoln's Birthday",
        "description": "Lincoln's Birthday is observed in some states.",
        "country": "us",
        "date": 20260212,
        "type": [
            "Local observance"
        ],
        "primary_type": "Local observance",
        "locations": "NY",
        "states": [
            "US-NY"
        ]
    }
]

Modified at 2026-09-28 00:01:50

List holiday regions

List holidays by country and region