Holidays API: Query Builder

All on one page

1. Authentication

Parameter

Description

Value

auth-method

Authentication Method

accesskey

Access Key (Required)

The access key for the request sender. This parameter identifies the account that will be charged for the request. Access keys can be created in the API control panel. Additionally, the API control panel allows to set certain preferences and restrictions per access key.

*

Example: NYczonwTxv

secretkey

Secret Key

The secret key associated with the access key.

Example: x4whvXnG7cCOBiNBoi1r

expires

Expiry Date (Required)

The date and time at which the signature for this request will expire. After this time, the request will be declined. This time stamp cannot be more than 24 hours ahead from the time the request is submitted. Default: 2 hours from now

*

now + 2hours

Example: 2025-03-26T20:34:26Z

signature

Signature (Required)

The signature for the request. The signature is created by applying the HMAC-SHA1 (RFC 2104) function to a concatenation of the access key, the called service name and the signature timestamp or expiry timestamp. The resulting data has to be encoded with the Base64 method.

*

Example: 4KvntdTApUC2MO6FJQqwYeVxQX0=

All on one page

2. Service Parameters

Parameter

Description

Value

country
Required

Country (Required)

Specify the country for which you would like to retrieve the list of holidays. A states ISO code can also be used when applicable (see a countrys state support on Holidays by Country
The additional code fun can be used to retrieve fun holidays.
The additional code _all_ can be used to retrieve holidays for all countries. When you use _all_ the cost of the request will be the number of countries returned, instead of 1.
Type: String/ISO3166-1-alpha-2 country code/ISO3166-2 country state code)

*

List of possible countries
Trial package: available data

year
Required

Year (Required)

The year for which the holidays should be retrieved.
Type: Integer

*

verbosetime

Verbose time

Adds verbose time specification to all ISO 8601 time stamps.
Type: Boolean
Default value: 1

tz

Time zone info

Add time zone information under the time object.
Type: Boolean
Default value: 1

lang

Language

The preferred language(s) for the texts. An error will be raised if the language code cannot be recognized. In case the text for a specific event cannot be retrieved in any of the requested languages it will be returned in English instead. To query for multiple languages, specify them as comma separated list or repeat the parameter multiple times. In case a requested translation is not available, it will be omitted from the output.
It is possible to query all available languages in a single request by specifying a primary text language, followed by the special value _all_. This value can not be specified as the first language.
In case you have specific needs for a certain language/translation, please contact us .
Type: String/ISO639 Language Code or _all_
Default value: en

types

Holiday types

Holiday types which should be returned. To combine multiple types, either separate them with commas or repeat the parameter with a different value. A negation can be expressed by prefixing the value with a tilde (~) character. Values are combined in the order they are supplied.
When the country parameter is a states ISO code then this parameter must include countrydefault to get valid result since the default value does not include local/state holidays.
Type: String/Holiday type
Default value: default (combination of federal, weekday, obs1 and federallocal)

Example: all,~un (return all holidays, but no UN events)
To select multiple items, press and hold CTRL key on windows and COMMAND key on mac then click on each item

readmore

3. Output Options

Parameter

Description

Value

out

Output Format

The services support data output in different formats. By default, the answer is returned in JSON format, but it is also possible to request the data in JSON-P, Javascript, XML, plain text or binary format. While XML and JSON/Javascript formats are supported by all services, plain text and binary is only supported by specific services. Please see the documentation for the individual services for more details. Note that the plain text and binary output method may also include a CSV representation.

callback

Callback Method

This parameter switches the output method to JSON-P and allows to specify the method name that should receive the result. You can choose this identifier freely to suit your needs.

Example: parseResponse

varname

Variable Name

This parameter switches the output method to Javascript and allows to specify the variable name the output data should be assigned to.

Example: o

prettyprint

Prettyprint

Set this parameter to 1 to receive the XML or JSON/Javascript output with line breaks and indentations. If set to zero, or unset, the output will be returned in compact form. This parameter is not applicable to the plain text output format. Default value: 1

All on one page

4. Result

Copy URL