API Reference

Comprehensive reference for all Festivo API endpoints.

Base URL

https://api.getfestivo.com/v3

All API requests must include your API key as a query parameter:

?api_key=your_api_key_here

Authentication

Include your API key in every request using the X-API-Key header (recommended):

X-API-Key: your_api_key_here

Alternative (deprecated): You can also use the api_key query parameter for legacy compatibility:

https://api.getfestivo.com/v3/public-holidays/list?api_key=YOUR_API_KEY&country=US&year=2026

Note: The X-API-Key header method is recommended for better security and cleaner URLs.

Endpoints

Get Public Holidays

Returns public holidays for a specific country and year.

Endpoint: GET /public-holidays/list

GEThttps://api.getfestivo.com/v3/public-holidays/list

Retrieve all public holidays for Great Britain in 2026

Request

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026"

Response:

1{
2  "holidays": [
3    {
4      "country": "GB",
5      "date": "2026-01-01",
6      "end": "2026-01-01T23:59:59Z",
7      "id": "20260101_1b5a163aa623c711ba95d37d129e2e7a",
8      "localLanguage": "gb",
9      "name": "New Year's Day",
10      "name_local": "New Year's Day",
11      "observed": "2026-01-01",
12      "public": true,
13      "start": "2026-01-01T00:00:00Z",
14      "subdivisions": [],
15      "regions": [],
16      "substitute": false,
17      "type": "public",
18      "weekday": {
19        "date": {
20          "name": "Thursday",
21          "numeric": 4
22        },
23        "observed": {
24          "name": "Thursday",
25          "numeric": 4
26        }
27      },
28      "dataVersion": "3.1.0",
29      "deprecated": false
30    }
31  ],
32  "query": "api_key=YOUR_API_KEY&country=GB&year=2026",
33  "requestId": "5bbf9184-07ab-4bb9-bf9b-dc14116d3bc6",
34  "status": 200
35}

Query Parameters

All query parameters and their availability by plan tier:

Plan Feature Overview

Feature Category	Explorer (Free)	Builder	Growth	Pro	Titan
Basic filters (country, year, month, day)	✓	✓	✓	✓	✓
Regions filter (ISO subdivisions)	—	✓	✓	✓	✓
Regions filter (city codes)	—	—	—	✓	✓
Date range filters (before/after)	—	✓	✓	✓	✓

Want to upgrade? Compare all plans and pricing →

Available in All Plans (Including Free Explorer)

Parameter	Type	Required	Description
api_key	string	Yes	Your API authentication key
country	string	Yes	ISO 3166-1 alpha-2 country code (e.g., GB)
year	number	Yes	Year (e.g., 2026)
month	number	No	Month (1-12) to filter by specific month
day	number	No	Day (1-31) to filter by specific day

Builder Plan and Above

These filters require at least a Builder plan subscription:

Parameter	Type	Description	Available From
regions	string	Filter by ISO 3166-2 subdivision codes (e.g., GB-SCT) OR city codes (e.g., IT-MILAN). Comma-separated for multiple. Learn more	Builder (regions) / Pro (cities)
after	string	Return only holidays after given date (YYYY-MM-DD)	Builder
before	string	Return only holidays before given date (YYYY-MM-DD)	Builder
type	string	Filter by holiday type (public, observance, regional, etc.)	Builder
public_only	boolean	Return only public holidays (default: false)	Builder
includeDeprecated	boolean	Include soft-removed holidays (default: false). See deprecated response field.	All plans

Growth Plan and Above

These advanced filters require at least a Growth plan subscription:

Parameter	Type	Description	Available From
language	string	ISO 639-1 language code for holiday names (e.g., 'de', 'fr', 'it'). Returns holiday names in the specified language.	Growth
timezone	string	Convert date and time according to timezone (e.g., 'America/New_York'). Defaults to UTC.	Growth
format	string	Response format: 'json' (default) or 'xml'	Growth

Important Notes:

City-level queries use the regions parameter with city code format (e.g., regions=IT-MILAN). This feature requires Pro plan or above.
Regional queries use the same regions parameter with ISO 3166-2 codes (e.g., regions=GB-SCT). This feature requires Builder plan or above.
Requests using unavailable parameters will return an error. View detailed plan comparison →

Example formats:

ISO subdivision (Builder+): regions=GB-SCT,GB-ENG
City code (Pro+): regions=IT-MILAN,IT-ROME
Mixed: regions=GB-SCT,IT-MILAN

Example with filters:

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&subdivision=GB-SCT&type=public&public_only=true"

Response Fields

Each holiday object contains the following fields:

Field	Type	Description
country	string	ISO 3166-1 alpha-2 country code
date	string	Holiday date (YYYY-MM-DD)
end	string	Holiday end timestamp (ISO 8601)
id	string	Unique holiday identifier
localLanguage	string	Local language code
name	string	Holiday name in English
name_local	string	Holiday name in local language
observed	string	Date the holiday is observed (YYYY-MM-DD)
public	boolean	Whether it's a public holiday. Under the default contract version this means observed nationwide — regional/city-scoped holidays are`false` even when legally mandated in their own scope. Pass `dataVersion=3.1.1` to get `true` for any statutory holiday within its own scope instead — see the changelog.
start	string	Holiday start timestamp (ISO 8601)
subdivisions	string[]	List of subdivision codes (empty array = nationwide). Learn more
regions	object[]	Structured subdivision data with code and type (city/region). Learn more
substitute	boolean	Whether this is a substitute holiday
type	string	Holiday type (see Holiday Types section)
weekday	object	Contains date and observed weekday information
dataVersion	string	Contract version this record is shaped by (see Contract versions)
deprecated	boolean	true if this holiday was soft-removed from the active calendar (withdrawn / no longer returned by our sources). Hidden by default; pass includeDeprecated=true to see them.

New Response Fields

Contract versions

dataVersion is a contract version: it names the shape and meaning of the response (which fields exist, what they mean, their defaults). It is not a version of the holiday data. Within a contract version, the data keeps updating as governments and our sources change holidays, so the same request can return newer data tomorrow under the same dataVersion.

We publish a new contract version only when the contract changes, always opt-in: the default stays the same until we announce otherwise.

Patch versions (3.1.0 → 3.1.1) refine the same contract: an added field, a clarified meaning. All patch versions of the default's family (today, every 3.1.x) are available on every plan.
Minor and major versions (3.2.0, 4.0.0) are new contracts; access to a version other than the default's family depends on your plan.

Every record says which contract it follows:

1{
2  "dataVersion": "3.1.0",
3  "name": "New Year's Day",
4  "date": "2026-01-01"
5}

Contract version	Status	Data
`3.1.0`	Live, default	Updated continuously
`3.1.1`	Live, opt-in	Same live data as 3.1.0; only `public` differs (see the changelog)
`3.1.2`	Live, opt-in	As 3.1.1, plus `variant`, `revision` and `updatedAt` on each item (see Holiday history)
`3.0.0`	Frozen	Kept exactly as it was; no longer updated

Pass dataVersion to pin a contract (e.g. ?dataVersion=3.1.1); omit it to get the default. Live versions share one dataset, so pinning a contract never means missing a holiday update. Contract versions are separate from the platform release numbers in the changelog.

Every change to a holiday is recorded as a revision: see Holiday history & changelog for the change feed and the per-holiday history endpoints.

Soft-removed holidays (`deprecated`)

When a holiday is withdrawn or stops appearing in our upstream sources, we soft-remove it instead of deleting the row. The occurrence stays in storage with deprecated: true and is omitted from list/check/working-days responses unless you pass includeDeprecated=true.

1{
2  "name": "One-off Bank Holiday",
3  "date": "2026-06-15",
4  "deprecated": true,
5  "dataVersion": "3.1.0"
6}

deprecated: false (or omitted on older rows) — active holiday
deprecated: true — no longer part of the active calendar
This is not an API-version / endpoint deprecation notice

Example:

GET /v3/public-holidays/list?country=GB&year=2026&includeDeprecated=true

Structured Regions Field

The new regions field provides structured subdivision data as an array of objects, making it easier to filter and classify geographic locations:

1{
2  "name": "Feast of Saint Ambrose",
3  "date": "2026-12-07",
4  "subdivisions": [
5    "IT-MILAN"
6  ],
7  "regions": [
8    {
9      "code": "IT-MILAN",
10      "type": "city"
11    },
12    {
13      "code": "IT-88",
14      "type": "region"
15    }
16  ]
17}

Each region object includes:

code: The subdivision identifier (e.g., "IT-MILAN" for Milan)
type: Either "city" or "region" for precise classification

This structured format makes it easier to:

Filter holidays by geographic level (city vs region)
Build location-based UI components
Implement city-specific business logic
Distinguish between city holidays and regional holidays

The legacy subdivisions field remains available for backward compatibility. For detailed information about city-level holidays and subdivision codes, see the Subdivisions documentation.

Holiday Types

Holidays are classified into the following types:

Public Holidays

Type: public

Official public holidays recognized by the government. Most businesses and government offices are closed.

Examples:

New Year's Day
Christmas Day
Independence Day

Observance

Type: observance

Widely observed but not official public holidays. Most businesses remain open.

Examples:

Valentine's Day
Mother's Day
Halloween

Regional Holidays

Type: regional

Holidays observed in specific regions, states, or provinces. The subdivisions field indicates where the holiday is observed. These are legally-mandated, statutory holidays within their scope — not merely observances — even though the default public field reads false for them (see Contract versions below).

Examples:

Saint Andrew's Day (Scotland only)
Carnival (specific states in Brazil)

Religious Holidays

Type: religious

Holidays of religious significance. May or may not be public holidays depending on the country.

Examples:

Good Friday
Eid al-Fitr
Diwali

Governmental

Type: governmental

Holidays when government offices are closed, but private businesses may remain open.

Examples:

Presidential Inauguration Day
Election Day

Bank Holidays

Type: bank

Days when banks are closed. Common in the UK and some Commonwealth countries.

Examples:

Spring Bank Holiday
Summer Bank Holiday

Subdivisions

Holidays can be specific to subdivisions (states, provinces, territories) within a country. The subdivisions field indicates which regions observe the holiday:

Empty array []: Holiday is observed nationwide
Array with codes: Holiday is only observed in specified subdivisions (e.g., ["GB-SCT"] for Scotland)

Subdivision Code Format:

Subdivision codes follow the ISO 3166-2 format: {COUNTRY}-{SUBDIVISION}

Examples:

GB-SCT - Scotland
GB-ENG - England
GB-WLS - Wales
GB-NIR - Northern Ireland
US-CA - California
US-NY - New York

To get a list of subdivisions for a country, use the premium filters with subdivision parameter.

Substitute Holidays

When a public holiday falls on a weekend, some countries observe a substitute holiday on the next working day. This is indicated by the substitute field:

substitute: false: Holiday is observed on its actual date
substitute: true: Holiday is a substitute / in-lieu day (weekend shift, or source names it as such)

When sources provide both the nominal calendar date and the day off, date and observed differ. Some sources only publish the weekday already; those rows may still have substitute: true with matching dates when the name indicates “(in lieu)” / substitute.

1{
2  "date": "2026-12-26",
3  "name": "Boxing Day",
4  "observed": "2026-12-28",
5  "substitute": true,
6  "weekday": {
7    "date": {
8      "name": "Saturday",
9      "numeric": 6
10    },
11    "observed": {
12      "name": "Monday",
13      "numeric": 1
14    }
15  }
16}

In this example, Boxing Day falls on Saturday (December 26), but is observed on Monday (December 28) as a substitute.

Timezones

All timestamps in the API are provided in UTC (Coordinated Universal Time) using ISO 8601 format:

start: Beginning of the holiday (00:00:00 UTC)
end: End of the holiday (23:59:59 UTC)

Example:

1{
2  "date": "2026-01-01",
3  "start": "2026-01-01T00:00:00Z",
4  "end": "2026-01-01T23:59:59Z"
5}

The Z suffix indicates UTC timezone. You should convert these timestamps to your local timezone in your application.

Converting to local timezone:

1// JavaScript example
2const holiday = {
3start: "2026-01-01T00:00:00Z",
4end: "2026-01-01T23:59:59Z"
5};
6const localStart = new Date(holiday.start).toLocaleString();
7const localEnd = new Date(holiday.end).toLocaleString();

Weekday Information

Each holiday includes detailed weekday information:

1{
2  "weekday": {
3    "date": {
4      "name": "Saturday",
5      "numeric": 6
6    },
7    "observed": {
8      "name": "Monday",
9      "numeric": 1
10    }
11  }
12}

weekday.date: The actual day of the week the holiday falls on
weekday.observed: The day of the week the holiday is observed (may differ if substitute)
numeric: Day number (0=Sunday, 1=Monday, ..., 6=Saturday)

Response Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key doesn't have access to this endpoint
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

Rate limits vary by plan:

Explorer (Free): 100 requests/day
Builder: 10,000 requests/day
Growth: 50,000 requests/day
Pro: 200,000 requests/day
Titan (Enterprise): Unlimited with custom limits

Rate limit information is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9543
X-RateLimit-Reset: 1640995200

Error Handling

All errors return a JSON response with an error message:

1{
2  "error": {
3    "code": "invalid_parameter",
4    "message": "Invalid country code",
5    "details": "Country code must be ISO 3166-1 alpha-2 format"
6  },
7  "status": 400
8}

Common Use Cases

Get All Public Holidays for a Country

Available in: All plans (including Free Explorer)

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=US&year=2026

Get Holidays for a Specific Month

Available in: All plans (including Free Explorer)

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=US&year=2026&month=12

Get Regional Holidays

Available in: Builder plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&regions=GB-SCT

Get Only Public Holidays

Available in: Builder plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&public_only=true

Get Holidays by Type

Available in: Builder plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&type=public

Get Holidays in Different Language

Available in: Growth plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=DE&year=2026&language=de

Get Holidays in XML Format

Available in: Growth plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=FR&year=2026&format=xml

Get City-Specific Holidays

Available in: Pro plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=IT&regions=IT-MILAN&year=2026

SDKs & Libraries

Official SDKs available:

JavaScript/TypeScript: npm install @festivo-io/festivo-sdk
Python: pip install festivo-python
PHP: composer require festivo-io/festivo-php
Go: go get github.com/festivo-io/festivo-sdk-go
Ruby: gem install festivo

Java:

Maven:

<dependency>
  <groupId>io.github.festivo-io</groupId>
  <artifactId>festivo-sdk</artifactId>
  <version>0.2.1</version>
</dependency>

Gradle:

implementation 'io.github.festivo-io:festivo-sdk:0.2.1'

Support

Need help?

API Reference

Comprehensive reference for all Festivo API endpoints.

Base URL

https://api.getfestivo.com/v3

All API requests must include your API key as a query parameter:

?api_key=your_api_key_here

Authentication

Include your API key in every request using the X-API-Key header (recommended):

X-API-Key: your_api_key_here

Alternative (deprecated): You can also use the api_key query parameter for legacy compatibility:

https://api.getfestivo.com/v3/public-holidays/list?api_key=YOUR_API_KEY&country=US&year=2026

Note: The X-API-Key header method is recommended for better security and cleaner URLs.

Endpoints

Get Public Holidays

Returns public holidays for a specific country and year.

Endpoint: GET /public-holidays/list

GEThttps://api.getfestivo.com/v3/public-holidays/list

Retrieve all public holidays for Great Britain in 2026

Request

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026"

Response:

1{
2  "holidays": [
3    {
4      "country": "GB",
5      "date": "2026-01-01",
6      "end": "2026-01-01T23:59:59Z",
7      "id": "20260101_1b5a163aa623c711ba95d37d129e2e7a",
8      "localLanguage": "gb",
9      "name": "New Year's Day",
10      "name_local": "New Year's Day",
11      "observed": "2026-01-01",
12      "public": true,
13      "start": "2026-01-01T00:00:00Z",
14      "subdivisions": [],
15      "regions": [],
16      "substitute": false,
17      "type": "public",
18      "weekday": {
19        "date": {
20          "name": "Thursday",
21          "numeric": 4
22        },
23        "observed": {
24          "name": "Thursday",
25          "numeric": 4
26        }
27      },
28      "dataVersion": "3.1.0",
29      "deprecated": false
30    }
31  ],
32  "query": "api_key=YOUR_API_KEY&country=GB&year=2026",
33  "requestId": "5bbf9184-07ab-4bb9-bf9b-dc14116d3bc6",
34  "status": 200
35}

Query Parameters

All query parameters and their availability by plan tier:

Plan Feature Overview

Feature Category	Explorer (Free)	Builder	Growth	Pro	Titan
Basic filters (country, year, month, day)	✓	✓	✓	✓	✓
Regions filter (ISO subdivisions)	—	✓	✓	✓	✓
Regions filter (city codes)	—	—	—	✓	✓
Date range filters (before/after)	—	✓	✓	✓	✓

Want to upgrade? Compare all plans and pricing →

Available in All Plans (Including Free Explorer)

Parameter	Type	Required	Description
api_key	string	Yes	Your API authentication key
country	string	Yes	ISO 3166-1 alpha-2 country code (e.g., GB)
year	number	Yes	Year (e.g., 2026)
month	number	No	Month (1-12) to filter by specific month
day	number	No	Day (1-31) to filter by specific day

Builder Plan and Above

These filters require at least a Builder plan subscription:

Parameter	Type	Description	Available From
regions	string	Filter by ISO 3166-2 subdivision codes (e.g., GB-SCT) OR city codes (e.g., IT-MILAN). Comma-separated for multiple. Learn more	Builder (regions) / Pro (cities)
after	string	Return only holidays after given date (YYYY-MM-DD)	Builder
before	string	Return only holidays before given date (YYYY-MM-DD)	Builder
type	string	Filter by holiday type (public, observance, regional, etc.)	Builder
public_only	boolean	Return only public holidays (default: false)	Builder
includeDeprecated	boolean	Include soft-removed holidays (default: false). See deprecated response field.	All plans

Growth Plan and Above

These advanced filters require at least a Growth plan subscription:

Parameter	Type	Description	Available From
language	string	ISO 639-1 language code for holiday names (e.g., 'de', 'fr', 'it'). Returns holiday names in the specified language.	Growth
timezone	string	Convert date and time according to timezone (e.g., 'America/New_York'). Defaults to UTC.	Growth
format	string	Response format: 'json' (default) or 'xml'	Growth

Important Notes:

City-level queries use the regions parameter with city code format (e.g., regions=IT-MILAN). This feature requires Pro plan or above.
Regional queries use the same regions parameter with ISO 3166-2 codes (e.g., regions=GB-SCT). This feature requires Builder plan or above.
Requests using unavailable parameters will return an error. View detailed plan comparison →

Example formats:

ISO subdivision (Builder+): regions=GB-SCT,GB-ENG
City code (Pro+): regions=IT-MILAN,IT-ROME
Mixed: regions=GB-SCT,IT-MILAN

Example with filters:

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&subdivision=GB-SCT&type=public&public_only=true"

Response Fields

Each holiday object contains the following fields:

Field	Type	Description
country	string	ISO 3166-1 alpha-2 country code
date	string	Holiday date (YYYY-MM-DD)
end	string	Holiday end timestamp (ISO 8601)
id	string	Unique holiday identifier
localLanguage	string	Local language code
name	string	Holiday name in English
name_local	string	Holiday name in local language
observed	string	Date the holiday is observed (YYYY-MM-DD)
public	boolean	Whether it's a public holiday. Under the default contract version this means observed nationwide — regional/city-scoped holidays are`false` even when legally mandated in their own scope. Pass `dataVersion=3.1.1` to get `true` for any statutory holiday within its own scope instead — see the changelog.
start	string	Holiday start timestamp (ISO 8601)
subdivisions	string[]	List of subdivision codes (empty array = nationwide). Learn more
regions	object[]	Structured subdivision data with code and type (city/region). Learn more
substitute	boolean	Whether this is a substitute holiday
type	string	Holiday type (see Holiday Types section)
weekday	object	Contains date and observed weekday information
dataVersion	string	Contract version this record is shaped by (see Contract versions)
deprecated	boolean	true if this holiday was soft-removed from the active calendar (withdrawn / no longer returned by our sources). Hidden by default; pass includeDeprecated=true to see them.

New Response Fields

Contract versions

We publish a new contract version only when the contract changes, always opt-in: the default stays the same until we announce otherwise.

Patch versions (3.1.0 → 3.1.1) refine the same contract: an added field, a clarified meaning. All patch versions of the default's family (today, every 3.1.x) are available on every plan.
Minor and major versions (3.2.0, 4.0.0) are new contracts; access to a version other than the default's family depends on your plan.

Every record says which contract it follows:

1{
2  "dataVersion": "3.1.0",
3  "name": "New Year's Day",
4  "date": "2026-01-01"
5}

Contract version	Status	Data
`3.1.0`	Live, default	Updated continuously
`3.1.1`	Live, opt-in	Same live data as 3.1.0; only `public` differs (see the changelog)
`3.1.2`	Live, opt-in	As 3.1.1, plus `variant`, `revision` and `updatedAt` on each item (see Holiday history)
`3.0.0`	Frozen	Kept exactly as it was; no longer updated

Every change to a holiday is recorded as a revision: see Holiday history & changelog for the change feed and the per-holiday history endpoints.

Soft-removed holidays (`deprecated`)

1{
2  "name": "One-off Bank Holiday",
3  "date": "2026-06-15",
4  "deprecated": true,
5  "dataVersion": "3.1.0"
6}

deprecated: false (or omitted on older rows) — active holiday
deprecated: true — no longer part of the active calendar
This is not an API-version / endpoint deprecation notice

Example:

GET /v3/public-holidays/list?country=GB&year=2026&includeDeprecated=true

Structured Regions Field

The new regions field provides structured subdivision data as an array of objects, making it easier to filter and classify geographic locations:

1{
2  "name": "Feast of Saint Ambrose",
3  "date": "2026-12-07",
4  "subdivisions": [
5    "IT-MILAN"
6  ],
7  "regions": [
8    {
9      "code": "IT-MILAN",
10      "type": "city"
11    },
12    {
13      "code": "IT-88",
14      "type": "region"
15    }
16  ]
17}

Each region object includes:

code: The subdivision identifier (e.g., "IT-MILAN" for Milan)
type: Either "city" or "region" for precise classification

This structured format makes it easier to:

Filter holidays by geographic level (city vs region)
Build location-based UI components
Implement city-specific business logic
Distinguish between city holidays and regional holidays

The legacy subdivisions field remains available for backward compatibility. For detailed information about city-level holidays and subdivision codes, see the Subdivisions documentation.

Holiday Types

Holidays are classified into the following types:

Public Holidays

Type: public

Official public holidays recognized by the government. Most businesses and government offices are closed.

Examples:

New Year's Day
Christmas Day
Independence Day

Observance

Type: observance

Widely observed but not official public holidays. Most businesses remain open.

Examples:

Valentine's Day
Mother's Day
Halloween

Regional Holidays

Type: regional

Examples:

Saint Andrew's Day (Scotland only)
Carnival (specific states in Brazil)

Religious Holidays

Type: religious

Holidays of religious significance. May or may not be public holidays depending on the country.

Examples:

Good Friday
Eid al-Fitr
Diwali

Governmental

Type: governmental

Holidays when government offices are closed, but private businesses may remain open.

Examples:

Presidential Inauguration Day
Election Day

Bank Holidays

Type: bank

Days when banks are closed. Common in the UK and some Commonwealth countries.

Examples:

Spring Bank Holiday
Summer Bank Holiday

Subdivisions

Holidays can be specific to subdivisions (states, provinces, territories) within a country. The subdivisions field indicates which regions observe the holiday:

Empty array []: Holiday is observed nationwide
Array with codes: Holiday is only observed in specified subdivisions (e.g., ["GB-SCT"] for Scotland)

Subdivision Code Format:

Subdivision codes follow the ISO 3166-2 format: {COUNTRY}-{SUBDIVISION}

Examples:

GB-SCT - Scotland
GB-ENG - England
GB-WLS - Wales
GB-NIR - Northern Ireland
US-CA - California
US-NY - New York

To get a list of subdivisions for a country, use the premium filters with subdivision parameter.

Substitute Holidays

When a public holiday falls on a weekend, some countries observe a substitute holiday on the next working day. This is indicated by the substitute field:

substitute: false: Holiday is observed on its actual date
substitute: true: Holiday is a substitute / in-lieu day (weekend shift, or source names it as such)

1{
2  "date": "2026-12-26",
3  "name": "Boxing Day",
4  "observed": "2026-12-28",
5  "substitute": true,
6  "weekday": {
7    "date": {
8      "name": "Saturday",
9      "numeric": 6
10    },
11    "observed": {
12      "name": "Monday",
13      "numeric": 1
14    }
15  }
16}

In this example, Boxing Day falls on Saturday (December 26), but is observed on Monday (December 28) as a substitute.

Timezones

All timestamps in the API are provided in UTC (Coordinated Universal Time) using ISO 8601 format:

start: Beginning of the holiday (00:00:00 UTC)
end: End of the holiday (23:59:59 UTC)

Example:

1{
2  "date": "2026-01-01",
3  "start": "2026-01-01T00:00:00Z",
4  "end": "2026-01-01T23:59:59Z"
5}

The Z suffix indicates UTC timezone. You should convert these timestamps to your local timezone in your application.

Converting to local timezone:

1// JavaScript example
2const holiday = {
3start: "2026-01-01T00:00:00Z",
4end: "2026-01-01T23:59:59Z"
5};
6const localStart = new Date(holiday.start).toLocaleString();
7const localEnd = new Date(holiday.end).toLocaleString();

Weekday Information

Each holiday includes detailed weekday information:

1{
2  "weekday": {
3    "date": {
4      "name": "Saturday",
5      "numeric": 6
6    },
7    "observed": {
8      "name": "Monday",
9      "numeric": 1
10    }
11  }
12}

weekday.date: The actual day of the week the holiday falls on
weekday.observed: The day of the week the holiday is observed (may differ if substitute)
numeric: Day number (0=Sunday, 1=Monday, ..., 6=Saturday)

Response Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key doesn't have access to this endpoint
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

Rate limits vary by plan:

Explorer (Free): 100 requests/day
Builder: 10,000 requests/day
Growth: 50,000 requests/day
Pro: 200,000 requests/day
Titan (Enterprise): Unlimited with custom limits

Rate limit information is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9543
X-RateLimit-Reset: 1640995200

Error Handling

All errors return a JSON response with an error message:

1{
2  "error": {
3    "code": "invalid_parameter",
4    "message": "Invalid country code",
5    "details": "Country code must be ISO 3166-1 alpha-2 format"
6  },
7  "status": 400
8}

Common Use Cases

Get All Public Holidays for a Country

Available in: All plans (including Free Explorer)

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=US&year=2026

Get Holidays for a Specific Month

Available in: All plans (including Free Explorer)

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=US&year=2026&month=12

Get Regional Holidays

Available in: Builder plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&regions=GB-SCT

Get Only Public Holidays

Available in: Builder plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&public_only=true

Get Holidays by Type

Available in: Builder plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&type=public

Get Holidays in Different Language

Available in: Growth plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=DE&year=2026&language=de

Get Holidays in XML Format

Available in: Growth plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=FR&year=2026&format=xml

Get City-Specific Holidays

Available in: Pro plan and above

1GET /v3/public-holidays/list?api_key=YOUR_API_KEY&country=IT&regions=IT-MILAN&year=2026

SDKs & Libraries

Official SDKs available:

JavaScript/TypeScript: npm install @festivo-io/festivo-sdk
Python: pip install festivo-python
PHP: composer require festivo-io/festivo-php
Go: go get github.com/festivo-io/festivo-sdk-go
Ruby: gem install festivo

Java:

Maven:

<dependency>
  <groupId>io.github.festivo-io</groupId>
  <artifactId>festivo-sdk</artifactId>
  <version>0.2.1</version>
</dependency>

Gradle:

implementation 'io.github.festivo-io:festivo-sdk:0.2.1'

Support

Need help?

API Reference

Base URL

Authentication

Endpoints

Get Public Holidays

Request

Query Parameters

Plan Feature Overview

Available in All Plans (Including Free Explorer)

Builder Plan and Above

Growth Plan and Above

Response Fields

New Response Fields

Contract versions

Soft-removed holidays (deprecated)

Structured Regions Field

Holiday Types

Public Holidays

Observance

Regional Holidays

Religious Holidays

Governmental

Bank Holidays

Subdivisions

Substitute Holidays

Timezones

Weekday Information

Response Codes

Rate Limits

Error Handling

Common Use Cases

Get All Public Holidays for a Country

Get Holidays for a Specific Month

Get Regional Holidays

Get Only Public Holidays

Get Holidays by Type

Get Holidays in Different Language

Get Holidays in XML Format

Get City-Specific Holidays

SDKs & Libraries

Support

API Reference

Base URL

Authentication

Endpoints

Get Public Holidays

Request

Query Parameters

Plan Feature Overview

Available in All Plans (Including Free Explorer)

Builder Plan and Above

Growth Plan and Above

Response Fields

New Response Fields

Contract versions

Soft-removed holidays (deprecated)

Structured Regions Field

Holiday Types

Public Holidays

Observance

Regional Holidays

Religious Holidays

Governmental

Bank Holidays

Subdivisions

Substitute Holidays

Timezones

Weekday Information

Response Codes

Rate Limits

Error Handling

Common Use Cases

Get All Public Holidays for a Country

Get Holidays for a Specific Month

Get Regional Holidays

Get Only Public Holidays

Get Holidays by Type

Get Holidays in Different Language

Get Holidays in XML Format

Get City-Specific Holidays

Soft-removed holidays (`deprecated`)

Soft-removed holidays (`deprecated`)