The OfficeHolidays API has one endpoint for both trial and full access users. All requests must be sent to the following endpoint:

The current version of the holidays service is v1 so all requests should begin with /holidays/v1, e.g.

OfficeHolidays API requires you to sign each of your requests with an HMAC signature. Each request to the API requires the addition of the following three HTTP headers:

Header            Value
X-Request-Time Unix timestamp at time of request. In order to prevent replay attacks
X-Auth This is your public API key which we use to identify you.
X-Sign The base64 encoded HMAC signature. To create the string to sign you concatenate the HTTP method, resource URI, query string, and Unix timestamp of the request. Then the string is hashed with your secret API key using the SHA256 hash function and finally base64 encoded.

PHP: example code

// Your public ID used to identify you
$accessKeyId = 'yRNgDLImYpft4I0FqzwHjCWWu5Cl9NW2';

// Your secret key that you use to hash your requests
$secretAccessKey = '7UT0NCz49uzIa9d/V0+oxy0v9okbI0/I';

$httpMethod = 'GET';
$endpoint = '';
$method = '/holidays/v1/next/30/days?limit=200&countries=fr,it,ch&return_type=json';
$signatureTime = time(); // Current UNIX timestamp

// Assemble the string to be hashed
$stringToSign = $httpMethod . $method . $signatureTime;

// Hash the string with your secretAccessCode using SHA256
$signature = base64_encode(hash_hmac('sha256', $stringToSign, $secretAccessKey));

$ch = curl_init();

// Set up a cURL to get send the request 
curl_setopt_array($ch, array(
	CURLOPT_URL => $endpoint . $method,
		'X-AUTH: '. $accessKeyId,
		'X-REQUEST-TIME: ' . $signatureTime,
		'X-SIGN: ' . $signature)

$response = curl_exec($ch);

// The response now contains the holidays you requested
echo $response;

C#: example code

using System;
using System.Collections.Generic;
using System.Web;
using System.Security.Cryptography;

// Your public ID used to identify you
String accessKeyId = "yRNgDLImYpft4I0FqzwHjCWWu5Cl9NW2";

// Your secret key that you use to hash your requests
String secretAccessKey = "7UT0NCz49uzIa9d/V0+oxy0v9okbI0/I";

// The request components
String httpMethod = "GET";
String endpoint = "";
String method = "/holidays/v1/next/30/days?limit=10&countries=fr,it,ch&return_type=json";

// Construct Unix timestamp
String signatureTime = ((Int32)(DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1))).TotalSeconds).ToString();

// Assemble URL
String url = endpoint + method;

// Assemble the string to be hashed
String stringToSign = httpMethod + method + signatureTime;

// Get bytes
var encoding = new System.Text.UTF8Encoding();
byte[] secretAccessKeyBytes = encoding.GetBytes(secretAccessKey);
byte[] stringToSignBytes = encoding.GetBytes(stringToSign);

// Hash the string with your secretAccessCode using SHA256
var hash = new HMACSHA256(secretAccessKeyBytes);
String signaturehex = BitConverter.ToString(hash.ComputeHash(stringToSignBytes)).Replace("-", "").ToLower();
String signaturebase64 = Convert.ToBase64String(encoding.GetBytes(signaturehex));

// Construct the request and get response in the variable 'response'
using (var request = new System.Net.WebClient())
	request.Headers.Add("X-Auth", accessKeyId);
	request.Headers.Add("X-Request-Time", signatureTime);
	request.Headers.Add("X-Sign", signaturebase64);
	var response = request.DownloadString(url);
GET /between/:start_date/:end_date

Returns holidays between the specified dates. The dates must be provided in the format yyyy-mm-dd. Holidays that fall on the start and end date are included. Returned holidays can be limited to specified countries, limited in number, sorted by date, and returned in xml or json using the query string.

Query string options

Field Value
countries A comma-separated case insensitive list of country codes for the desired countries. If the package being used is limited to certain countries, only holidays for the allowed countries will be returned. All other country codes will fail silently. If this parameter is not provided the service will default to all allowed countries. E.g. countries=de,at,ch
limit Maximum number of holidays to be returned. Accepted values are 1 to 999. If this parameter is not provided the service will default to 20.
sort The date order by which to sort result set. Accepted values are asc and desc. If this parameter is not provided the service will default to asc.
return_type Desired return data type. Accepted values are json and xml. If this parameter is not provided the service will default to json.

Example URL,at,ch&limit=10&sort=asc&return_type=json
GET /next/:number_of_days/days GET /year/:year GET /month/:month GET /date/:date GET /:id GET /search/:q

There are different maximum request rates depending on the package that you have purchased. Upon exceeding the allowed maximum rate your requests will be answered with a 429 - Too Many Requests response, along with information telling you how long to wait before sending your next request.

Package Limit
Free Trial 10 requests per minute
One-country package 60 requests per minute
Full access No rate limit


The total number of allowed requests depends on the package that you have purchased. Upon exceeding the allowed total number of requests, your requests will be answered with a 429 - Too Many Requests response, along with information telling you how to purchase more.

Package Limit
Free Trial 1,000 total requests
One-country package 100,000 total requests
Full access 1,000,000 total requests


The following examples are the JSON and XML versions of a holidays service response containing only 1 holiday, Bastille day 2015. If multiple holidays are returned, the count will increase accordingly, and the holidays array/holidays element will contain multiple holiday objects/elements.

JSON: Holiday Object

	version: "1.0",
	count: 1,
	holidays: [
			id: "5170",
			name: "Bastille Day",
			country: "France",
			country_code: "FR",
			regional_info: false,
			regions: null,
			date: "2015-07-14",
			date_detail: {
				mday: 14,
				wday: 2,
				mon: 7,
				year: 2015,
				yday: 194,
				weekday: "Tuesday",
				month: "July"
			religion: null,
			is_public_holiday: true,
			is_government_holiday: false,
			is_bank_holiday: false,
			url: "",
			image_url: "",
			info: "Bastille Day celebrates the birth of the French Republic and marks the storming of the Bastille in 1789",
			remarks: "French National Day"

XML: Holiday Object

			<name>Bastille Day</name>
			<info>Bastille Day celebrates the birth of the French Republic and marks the storming of the Bastille in 1789</info>
			<remarks>French National Day</remarks>

In general all errors will contain a response body containing information on what went wrong. The exception to this are authentication errors which will only send a 401 Unauthorized.

Authentication Errors

If there was a problem authenticating the request the API will respond with a 401 Unauthorized response. Please review the authentication section and ensure that you have signed your request properly. Each request MUST contain all three headers and the string that is hashed MUST be constructed properly.

Rate and Request Limit Errors

If too many requests are sent in a given time period the API will respond with a 429 Too Many Requests response. It will contain information on how long to wait before sending another request.

Method Errors

If a request constructed for a method that does not exist the API will respond with a 404 Not Found response.

Input Errors

If any part of the request URI is constructed incorrectly the API will respond with a 400 Bad Request response. The body will contain information on which part of the URL was improperly constructed.

Package Expiration Errors

If the package associated with an account has expired the API will respond with a 403 Forbidden response. Please contact our support to renew your package.

If you encounter any problems using the OfficeHolidays API, please refer to this page and ensure that the requests are formatted properly, and signed correctly. If your request returns and error the response body will usually contain information on what went wrong. If your problem persists please use the contact form to get in touch with our support.

Albania AlbaniaAL
Algeria AlgeriaDZ
Angola AngolaAO
Argentina ArgentinaAR
Armenia ArmeniaAM
Australia AustraliaAU
Austria AustriaAT
Azerbaijan AzerbaijanAZ
Bahamas BahamasBS
Bahrain BahrainBH
Bangladesh BangladeshBD
Barbados BarbadosBB
Belarus BelarusBY
Belgium BelgiumBE
Bolivia BoliviaBO
Bosnia and Herzegovina Bosnia and HerzegovinaBA
Botswana BotswanaBW
Brazil BrazilBR
Brunei BruneiBN
Bulgaria BulgariaBG
Burundi BurundiBI
Cambodia CambodiaKH
Canada CanadaCA
Cayman Islands Cayman IslandsKY
Chile ChileCL
China ChinaCN
Colombia ColombiaCO
Costa Rica Costa RicaCR
Croatia CroatiaHR
Cyprus CyprusCY
Czech Republic Czech RepublicCZ
Denmark DenmarkDK
Dominican Republic Dominican RepublicDO
Ecuador EcuadorEC
Egypt EgyptEG
El Salvador El SalvadorSV
Estonia EstoniaEE
Ethiopia EthiopiaET
Fiji FijiFJ
Finland FinlandFI
France FranceFR
Georgia GeorgiaGE
Germany GermanyDE
Ghana GhanaGH
Gibraltar GibraltarGI
Greece GreeceGR
Grenada GrenadaGD
Honduras HondurasHN
Hong Kong Hong KongHK
Hungary HungaryHU
Iceland IcelandIS
India IndiaIN
Indonesia IndonesiaID
Iraq IraqIQ
Ireland IrelandIE
Isle of Man Isle of ManIM
Israel IsraelIL
Italy ItalyIT
Jamaica JamaicaJM
Japan JapanJP
Jordan JordanJO
Kazakhstan KazakhstanKZ
Kenya KenyaKE
Kuwait KuwaitKW
Lao LaoLA
Latvia LatviaLV
Lebanon LebanonLB
Libya LibyaLY
Lithuania LithuaniaLT
Luxembourg LuxembourgLU
Macau MacauMO
Macedonia MacedoniaMK
Malaysia MalaysiaMY
Maldives MaldivesMV
Malta MaltaMT
Mauritius MauritiusMU
Mexico MexicoMX
Moldova MoldovaMD
Montenegro MontenegroME
Morocco MoroccoMA
Mozambique MozambiqueMZ
Myanmar MyanmarMM
Netherlands NetherlandsNL
New Zealand New ZealandNZ
Nigeria NigeriaNG
Norway NorwayNO
Oman OmanOM
Pakistan PakistanPK
Panama PanamaPA
Paraguay ParaguayPY
Peru PeruPE
Philippines PhilippinesPH
Poland PolandPL
Portugal PortugalPT
Qatar QatarQA
Romania RomaniaRO
Russia RussiaRU
Rwanda RwandaRW
Saint Lucia Saint LuciaLC
Saudi Arabia Saudi ArabiaSA
Serbia SerbiaRS
Singapore SingaporeSG
Slovakia SlovakiaSK
Slovenia SloveniaSI
South Africa South AfricaZA
South Korea South KoreaKR
Spain SpainES
Sri Lanka Sri LankaLK
Sweden SwedenSE
Switzerland SwitzerlandCH
Taiwan TaiwanTW
Tanzania TanzaniaTZ
Thailand ThailandTH
Tonga TongaTO
Trinidad and Tobago Trinidad and TobagoTT
Tunisia TunisiaTN
Turkey TurkeyTR
Turks and Caicos Islands Turks and Caicos IslandsTC
Uganda UgandaUG
Ukraine UkraineUA
United Arab Emirates United Arab EmiratesAE
United Kingdom United KingdomGB
Uruguay UruguayUY
Venezuela VenezuelaVE
Vietnam VietnamVN
Yemen YemenYE
Zambia ZambiaZM
Zimbabwe ZimbabweZW