Retrieve public holidays, bank holidays, and observances for any country or region. Holidays are calculated dynamically, supporting queries for any year, past or future.
Standards Used
- ISO 8601
- ISO 3166-1
- ISO 3166-2
Regional Holidays#
When querying a region (e.g., US-CA), both national and regional holidays are returned. For example, César Chávez Day appears for California, but not Texas.
The Holiday object#
| Field | Type | Required | Description |
|---|---|---|---|
| date | string | Yes | Date (ISO 8601, YYYY-MM-DD). Example: 2024-12-25 |
| name | string | Yes | Holiday name. Example: Christmas Day |
| types | string[] | Yes | Holiday types. Example: ["public","bank"] |
The different Holiday types#
Schema 'HolidayKind' not found in OpenAPI specification.
Endpoints#
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locationpath | string | Yes | Country (alpha-2) or region (ISO 3166-2) code |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| yearquery | integer (int32) | No | Full year to query (mutually exclusive with start/end). Example: 2024 |
| startquery | string | No | Start date (ISO 8601, requires end). Example: 2024-01-01 |
| endquery | string | No | End date (ISO 8601, requires start). Example: 2024-12-31 |
| typequery | string | No | Filter by type (public, bank, school, authorities, optional, observance, international). Example: public |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| holidays | object[] | Yes | Holidays sorted by date. |
| location | string | Yes | Resolved location code. Example: US |
| period | object | object | Yes | Holiday period in response. |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/holidays/40.7128,-74.0060?year=2024&start=2024-01-01',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/holidays/40.7128,-74.0060',
params={
'year': '2024',
'start': 'example'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/holidays/40.7128,-74.0060?year=2024&start=2024-01-01"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters |
| 404 | Location not found |
| 429 | Rate limit exceeded |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locationpath | string | Yes | Country (alpha-2) or region (ISO 3166-2) code |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| fromquery | string | No | Start date for search (defaults to today). Example: 2024-01-15 |
| typequery | string | No | Filter by type. Example: public |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| days_until | integer (int64) | Yes | Days until the holiday. Example: 5 |
| from | string | Yes | Search start date. Example: 2024-01-15 |
| holiday | object | Yes | Holiday response object. |
| date | string | Yes | Date (ISO 8601, YYYY-MM-DD). Example: 2024-12-25 |
| name | string | Yes | Holiday name. Example: Christmas Day |
| types | string[] | Yes | Holiday types. Example: ["public","bank"] |
| location | string | Yes | Resolved location code. Example: US |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/holidays/40.7128,-74.0060/next?from=2024-01-15&type=public',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/holidays/40.7128,-74.0060/next',
params={
'from': 'example',
'type': 'example'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/holidays/40.7128,-74.0060/next?from=2024-01-15&type=public"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters |
| 404 | Location not found or no upcoming holidays |
| 429 | Rate limit exceeded |