Discover the easiest way to enhance your website or application with public holidays and observances.
Retrieves a list countries with states and provinces. Full list of supported countries and states / provinces. Try it in your browser.
key
string
Your API key.
country
string
Return only the country with the specified code.
search
string
Search countries by code and name. Minimum 2 characters.
public
boolean
Return only countries that have public holidays.
format
string
Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.
pretty
boolean
Prettifies results to be more human-readable.
status
number
Status code for the response.
requests
dictionary
Rate limit information for the current month.
requests.available
integer
The remaining number of API calls you can make for the current month.
requests.used
integer
Total number of API requests you have made during the current month.
requests.resets
datetime string
The date and time that the current rate limits will be reset.
countries
array of dictionaries
List of countries based on your request parameters.
countries.code
string
ISO 3166-1 alpha-2 code for the country.
countries.name
string
Name of the country.
countries.codes
dictionary of country codes
Not every system uses ISO 3166-1 alpha-2 codes. These codes provide an easy way to map ISO 3166-1 alpha 2 codes back to the codes your system uses.
countries.codes.alpha-2
string
ISO 3166-1 alpha-2 code for the country.
countries.codes.alpha-3
string
ISO 3166-1 alpha-3 code for the country.
countries.codes.numeric
integer
ISO 3166-1 numeric code for the country.
countries.languages
array of strings
Spoken languages for the country.
Use with /v1/holidays
to request holidays in a language other than English.
countries.currencies
array of dictionaries
Currencies accepted as legal tender in the country.
countries.currencies.alpha
string
ISO 4217 alpha code for the currency.
countries.flag
URL string
URL to a 64x64 image of the country's flag, courtesy of Country Flags API.
countries.subdivisions
array of dictionaries
Many countries are broken down into of smaller subdivisions. These subdivisions go by different names, like states or provinces and in some scenarios may represent countries or nations. For simplicity, we refer to these subdivisions collectively as States & Provinces.
countries.subdivisions.code
string
ISO 3166-2 code for the state / province.
Use with /v1/holidays
to request holidays for a specific state / province.
countries.subdivisions.name
string
Name of the state / province.
countries.subdivisions.languages
array of strings
Spoken languages for the state / province.
Use with /v1/holidays
to request holidays in a language other than English.
countries.weekend
array of dictionaries
Days of the week that are considered weekends (non-working days) in the country.
countries.weekend.name
string
Name of the day of the week that the weekend day occurs.
countries.weekend.numeric
string
ISO-8601 numeric representation of the day of the week that the weekend day occurs.
error
string
Textual explanation of the error that ocurred.
warning
string
Additional information about the data that was returned.
{
"status": 200,
+ "requests": { ... }, - "requests": {
"used": 311,
"available": 689,
"resets": "2025-01-01 00:00:00"
}, + "countries": [ ... ] - "countries": [
{
"code": "ST",
"name": "Sao Tome and Principe",
"codes": {
"alpha-2": "ST",
"alpha-3": "STP",
"numeric": 678
},
"languages": [
"pt"
],
"currencies": [
{
"alpha": "STN"
}
]
"flag": "https:\/\/flagsapi.com\/ST\/flat\/64.png",
"subdivisions": [
{
"code": "ST-P",
"name": "Principe",
"languages": [
"pt"
]
},
{
"code": "ST-S",
"name": "São Tomé",
"languages": [
"pt"
]
}
]
}
]}
Retrieves a list languages. Full list of supported languages. Try it in your browser.
key
string
Your API key.
language
string
Return only the language with the specified code.
search
string
Search languages by code and name. Minimum 2 characters.
format
string
Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.
pretty
boolean
Prettifies results to be more human-readable.
status
number
Status code for the response.
requests
dictionary
Rate limit information for the current month.
requests.available
integer
The remaining number of API calls you can make for the current month.
requests.used
integer
Total number of API requests you have made during the current month.
requests.resets
datetime string
The date and time that the current rate limits will be reset.
languages
array of dictionaries
List of languages based on your request parameters.
languages.code
string
ISO-639-1, ISO-639-2 (for Cebuano, Hawaiian and Hmong), or BCP-47 (for Chinese) code for the language.
languages.name
string
Name of the language.
error
string
Textual explanation of the error that ocurred.
warning
string
Additional information about the data that was returned.
{
"status": 200,
+ "requests": { ... }, - "requests": {
"used": 311,
"available": 689,
"resets": "2025-01-01 00:00:00"
}, + "languages": [ ... ] - "languages": [
{
"code": "ar",
"name": "Arabic"
},
{
"code": "en",
"name": "English"
},
{
"code": "es",
"name": "Spanish, Castilian"
},
{
"code": "hi",
"name": "Hindi"
},
{
"code": "zh",
"name": "Chinese (Simplified)"
}
]}
Calculates the workday (based on country's workweek) that occurs a given number of days after a date. Try it in your browser.
key
string
Your API key.
country
string
For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For states / provinces (with our States & Provinces plan), ISO 3166-2 format.
Full list of supported countries and states / provinces.
start
date
The date (in YYYY-MM-DD format) from which to begin counting.
days
non-zero integer
Number of working / business days to advance (positive integer) or retrogress (negative integer) from start
.
format
string
Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.
pretty
boolean
Prettifies results to be more human-readable.
status
number
Status code for the response.
requests
dictionary
Rate limit information for the current month.
requests.available
integer
The remaining number of API calls you can make for the current month.
requests.used
integer
Total number of API requests you have made during the current month.
requests.resets
datetime string
The date and time that the current rate limits will be reset.
date
date
The date of the calculated workday.
weekday
dictionary
Day of the week that the workday occurs.
weekday.name
string
Name of the day of the week that the workday occurs. Corresponds with the date
property.
weekday.numeric
string
ISO-8601 numeric representation of the day of the week that the workday occurs. Corresponds with the date
property.
error
string
Textual explanation of the error that ocurred.
warning
string
Additional information about the data that was returned.
{
"status": 200,
+ "requests": { ... }, - "requests": {
"used": 311,
"available": 689,
"resets": "2025-01-01 00:00:00"
}, + "workday": { ... } - "workday": {
"date": "2019-07-16",
"date": "weekday": {
"name": "Tuesday",
"numeric": "1"
}
}}
Calculates the number of workdays (based on country's workweek) that occur between a given date range. Try it in your browser.
key
string
Your API key.
country
string
For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For states / provinces (with our States & Provinces plan), ISO 3166-2 format.
Full list of supported countries and states / provinces.
start
date
The date (in YYYY-MM-DD format) from which to begin counting.
end
date
The date (in YYYY-MM-DD format) to count until.
format
string
Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.
pretty
boolean
Prettifies results to be more human-readable.
status
number
Status code for the response.
requests
dictionary
Rate limit information for the current month.
requests.available
integer
The remaining number of API calls you can make for the current month.
requests.used
integer
Total number of API requests you have made during the current month.
requests.resets
datetime string
The date and time that the current rate limits will be reset.
workdays
integer
Number of working / business days between the specified start
and end
dates.
error
string
Textual explanation of the error that ocurred.
warning
string
Additional information about the data that was returned.
{
"status": 200,
+ "requests": { ... }, - "requests": {
"used": 311,
"available": 689,
"resets": "2025-01-01 00:00:00"
}, "workdays": 13
}
Response status codes are returned as both the HTTP status code and as part of the response body.
200
400
401
402
403
429
500
Monthly rate limits vary by plan. Once exceeded, the API will return the 429
status code.
You can easily track your usage for the current month via the requests
property in the response body.
Kick-start your next project with our official and community contributed libraries
or generate your own from our OpenAPI definition.