offchaindata/holiday-oracle-php

Client library to interact with the Holiday Oracle global holidays API

Maintainers

Details

github.com/OffChainData/holiday-oracle-php

Source

Issues

Installs: 4

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

0.1 2020-04-15 04:59 UTC

Requires

Requires (Dev)

MIT 3565867bbc7fc926932118925fc1ae466cbb7960

  • Julian Broudou <julian.woop@offchaindata.com>

This package is auto-updated.

Last update: 2025-06-16 15:11:15 UTC

README

Build Status License

The Holiday Oracle PHP library provides convenient access to the global holidays API provided by Off Chain Data from your PHP applications.

Installation

Install with composer:

composer require offchaindata/holiday-oracle-php

Calling the API

Note that all methods accept an optional array as the last parameter that can be used to pass optional parameters to the API. e.g.

public function holidays($country, $year, array $options = [])

First create an instance of the Holiday Oracle client object

<?php

require_once __DIR__ . '/vendor/autoload.php'; // Autoload files using Composer autoload
use OffChainData\HolidayOracle\Client;
$client = new Client('INSERT API TOKEN');

To obtain a list of supported locations (countries and subdivisions) call the locations() method.

try {
    $response = $client->locations();
    ...
} catch (\Exception $e) {
    echo $e->getMessage();
}

The date end point can be used to determine if a date is a working day or holiday. It can also be used to calculate the next N working day.

try {
    $response = $client->date('2020-01-01', 'AU', ['subdivision' => 'NSW']);
    ...
} catch (\Exception $e) {
    echo $e->getMessage();
}

Obtaining a list of holidays for a location is done via the holidays() method.

try {
    $response = $client->holidays('AU', '2020');
    ...
} catch (\Exception $e) {
    echo $e->getMessage();
}

Lastly, to calculate business/working days between two dates, call the businessDays() method.

try {
    $response = $client->businessDays('2020-01-01', '2020-02-01', 'AU');
    ...
} catch (\Exception $e) {
    echo $e->getMessage();
}

Errors

The client library will throw exceptions upon validation errors and when errors are returned by the API. The exact API error code can be returned as per the following

try {
    $response = $client->businessDays('2020-01-01', '2020-02-01', 'AU');
    ...
} catch (\Exception $e) {
    var_dump($client->getLastResponseStatus());
}

Supported Locations

The following is a list of locations supported by the API. Where a country has no subdivisions, holidays are returned for the entire country. Where subdivisions are defined, you can query for holidays a both the country and subdivisions level.

You can also query the API https://holidayoracle.io/docs/index.html#locations for a list of currently supported locations.

Country                       Subdivision
Andorra (AD) Andorra la Vella (07)
United Arab Emirates (AE) Entire Country
Antigua and Barbuda (AG) Barbuda (10)
Anguilla (AI) Entire Country
Albania (AL) Entire Country
Armenia (AM) Entire Country
Angola (AO) Entire Country
Argentina (AR) Entire Country
American Samoa (AS) Entire Country
Austria (AT) Burgenland (1), Kärnten (2), Niederösterreich (3), Oberösterreich (4), Salzburg (5), Steiermark (6), Tirol (7), Vorarlberg (8), Wien (9)
Australia (AU) Australian Capital Territory (ACT), New South Wales (NSW), Northern Territory (NT), Queensland (QLD), South Australia (SA), Tasmania (TAS), Victoria (VIC), Western Australia (WA)
Aruba (AW) Entire Country
Åland Islands (AX) Entire Country
Azerbaijan (AZ) Entire Country
Bosnia and Herzegovina (BA) Federacija Bosne i Hercegovine (BIH), Brčko distrikt (BRC), Republika Srpska (SRP)
Barbados (BB) Entire Country
Bangladesh (BD) Entire Country
Belgium (BE) Brussels Hoofdstedelijk Gewest (BRU), Vlaams Gewest (VLG), wallonne, Région (WAL)
Burkina Faso (BF) Entire Country
Bulgaria (BG) Entire Country
Bahrain (BH) Entire Country
Burundi (BI) Entire Country
Benin (BJ) Entire Country
Saint Barthélemy (BL) Entire Country
Bermuda (BM) Entire Country
Brunei Darussalam (BN) Entire Country
Bolivia (Plurinational State of) (BO) Entire Country
Bonaire, Sint Eustatius and Saba (BQ) Boneiru (BO), Saba (SA), Sint Eustatius (SE)
Brazil (BR) Acre (AC), Alagoas (AL), Amazonas (AM), Amapá (AP), Bahia (BA), Ceará (CE), Distrito Federal (DF), Espírito Santo (ES), Goiás (GO), Maranhão (MA), Minas Gerais (MG), Mato Grosso do Sul (MS), Mato Grosso (MT), Pará (PA), Paraíba (PB), Pernambuco (PE), Piauí (PI), Paraná (PR), Rio de Janeiro (RJ), Rio Grande do Norte (RN), Rondônia (RO), Roraima (RR), Rio Grande do Sul (RS), Santa Catarina (SC), Sergipe (SE), São Paulo (SP), Tocantins (TO)
Bahamas (BS) Entire Country
Botswana (BW) Entire Country
Belarus (BY) Entire Country
Belize (BZ) Entire Country
Canada (CA) Alberta (AB), Colombie-Britannique (BC), Manitoba (MB), Nouveau-Brunswick (NB), Terre-Neuve-et-Labrador (NL), Nouvelle-Écosse (NS), Territoires du Nord-Ouest (NT), Nunavut (NU), Ontario (ON), Île-du-Prince-Édouard (PE), Québec (QC), Saskatchewan (SK), Yukon (YT)
Cocos (Keeling) Islands (CC) Entire Country
Congo, Democratic Republic of the (CD) Entire Country
Central African Republic (CF) Entire Country
Congo (CG) Entire Country
Switzerland (CH) Aargau (AG), Appenzell Innerrhoden (AI), Appenzell Ausserrhoden (AR), Berne (BE), Basel-Landschaft (BL), Basel-Stadt (BS), Fribourg (FR), Genève (GE), Glarus (GL), Grischun (GR), Jura (JU), Luzern (LU), Neuchâtel (NE), Nidwalden (NW), Obwalden (OW), Sankt Gallen (SG), Schaffhausen (SH), Solothurn (SO), Schwyz (SZ), Thurgau (TG), Ticino (TI), Uri (UR), Vaud (VD), Valais (VS), Zug (ZG), Zürich (ZH)
Côte d'Ivoire (CI) Entire Country
Chile (CL) Arica y Parinacota (AP), Atacama (AT), Biobío (BI), Coquimbo (CO), Los Ríos (LR), Magallanes (MA), Tarapacá (TA)
Cameroon (CM) Entire Country
China (CN) Entire Country
Colombia (CO) Entire Country
Costa Rica (CR) Entire Country
Cuba (CU) Entire Country
Cabo Verde (CV) Ilhas de Sotavento (S)
Curaçao (CW) Entire Country
Christmas Island (CX) Entire Country
Cyprus (CY) Entire Country
Czechia (CZ) Entire Country
Germany (DE) Brandenburg (BB), Berlin (BE), Baden-Württemberg (BW), Bayern (BY), Bremen (HB), Hessen (HE), Hamburg (HH), Mecklenburg-Vorpommern (MV), Niedersachsen (NI), Nordrhein-Westfalen (NW), Rheinland-Pfalz (RP), Schleswig-Holstein (SH), Saarland (SL), Sachsen (SN), Sachsen-Anhalt (ST), Thüringen (TH)
Denmark (DK) Entire Country
Dominica (DM) Entire Country
Dominican Republic (DO) Entire Country
Algeria (DZ) Entire Country
Ecuador (EC) Pichincha (P)
Estonia (EE) Entire Country
Egypt (EG) Entire Country
Spain (ES) Andalucía (AN), Aragón (AR), Asturias, Principado de (AS), Cantabria (CB), Ceuta (CE), Castilla y León (CL), Castilla-La Mancha (CM), Canarias (CN), Catalunya (CT), Extremadura (EX), Galicia (GA), Illes Balears (IB), La Rioja (LO), Madrid (M), Murcia, Región de (MC), Madrid, Comunidad de (MD), Melilla (ML), Murcia (MU), Navarra (NA), Navarra, Comunidad Foral de (NC), Asturias (O), País Vasco (PV), La Rioja (RI), Valenciana, Comunidad (VC)
Ethiopia (ET) Entire Country
Finland (FI) Entire Country
Micronesia (Federated States of) (FM) Entire Country
Faroe Islands (FO) Entire Country
France (FR) Moselle (57), Bas-Rhin (67), Haut-Rhin (68), Saint-Barthélemy (BL), Guyane (GF), Guadeloupe (GP), Guadeloupe (GUA), La Réunion (LRE), Mayotte (MAY), Saint-Martin (MF), Martinique (MQ), Nouvelle-Calédonie (NC), Polynésie française (PF), La Réunion (RE), Wallis-et-Futuna (WF), Mayotte (YT)
Gabon (GA) Entire Country
United Kingdom of Great Britain and Northern Ireland (GB) England (ENG), Northern Ireland (NIR), Scotland (SCT), Wales (WLS)
Grenada (GD) Entire Country
French Guiana (GF) Entire Country
Guernsey (GG) Entire Country
Gibraltar (GI) Entire Country
Greenland (GL) Entire Country
Gambia (GM) Entire Country
Guadeloupe (GP) Entire Country
Equatorial Guinea (GQ) Entire Country
Greece (GR) Entire Country
Guatemala (GT) Entire Country
Guam (GU) Entire Country
Guyana (GY) Entire Country
Hong Kong (HK) Entire Country
Honduras (HN) Entire Country
Croatia (HR) Splitsko-dalmatinska županija (17), Dubrovačko-neretvanska županija (19)
Haiti (HT) Entire Country
Hungary (HU) Entire Country
Indonesia (ID) Entire Country
Ireland (IE) Entire Country
Israel (IL) Entire Country
Isle of Man (IM) Entire Country
India (IN) Andhra Pradesh (AP), Assam (AS), Bihar (BR), Gujarat (GJ), Haryana (HR), Karnataka (KA), Kerala (KL), Maharashtra (MH), Madhya Pradesh (MP), Rajasthan (RJ), Sikkim (SK), Tamil Nadu (TN), Uttar Pradesh (UP), West Bengal (WB)
Iceland (IS) Entire Country
Italy (IT) Valle d'Aosta (23), Trentino-Alto Adige (32), Ancona (AN), Bari (BA), Belluno (BL), Bologna (BO), Brescia (BS), Bolzano (BZ), Campobasso (CB), Chieti (CH), Cosenza (CS), Catania (CT), Enna (EN), Forlì-Cesena (FC), Ferrara (FE), Firenze (FI), Frosinone (FR), Genova (GE), Isernia (IS), Crotone (KR), Latina (LT), Monza e Brianza (MB), Milano (MI), Mantova (MN), Modena (MO), Massa-Carrara (MS), Napoli (NA), Palermo (PA), Piacenza (PC), Padova (PD), Pescara (PE), Perugia (PG), Pisa (PI), Parma (PR), Pistoia (PT), Pesaro e Urbino (PU), Ravenna (RA), Reggio Emilia (RE), Rieti (RI), Roma (RM), Rimini (RN), Rovigo (RO), Salerno (SA), La Spezia (SP), Siracusa (SR), Teramo (TE), Torino (TO), Vercelli (VC), Venezia (VE), Vicenza (VI)
Jersey (JE) Entire Country
Jamaica (JM) Entire Country
Japan (JP) Entire Country
Kenya (KE) Entire Country
Korea, Republic of (KR) Entire Country
Cayman Islands (KY) Entire Country
Liechtenstein (LI) Entire Country
Lesotho (LS) Entire Country
Lithuania (LT) Entire Country
Luxembourg (LU) Entire Country
Latvia (LV) Entire Country
Morocco (MA) Entire Country
Monaco (MC) Entire Country
Moldova, Republic of (MD) Cahul (CA), Chișinău (CU)
Montenegro (ME) Entire Country
Madagascar (MG) Entire Country
Marshall Islands (MH) Entire Country
North Macedonia (MK) Entire Country
Mongolia (MN) Entire Country
Northern Mariana Islands (MP) Entire Country
Martinique (MQ) Entire Country
Malta (MT) Entire Country
Malawi (MW) Entire Country
Mexico (MX) Entire Country
Malaysia (MY) Entire Country
Mozambique (MZ) Entire Country
Namibia (NA) Entire Country
Niger (NE) Entire Country
Nicaragua (NI) Entire Country
Netherlands (NL) Entire Country
Norway (NO) Entire Country
New Zealand (NZ) Tāmaki-makau-rau (AUK), Te Moana a Toi Te Huatahi (BOP), Waitaha (CAN), Wharekauri (CIT), Tūranga nui a Kiwa (GIS), Te Matau a Māui (HKB), Marlborough (MBH), Manawatu Whanganui (MWT), Whakatū (NSN), Te Tai tokerau (NTL), Ō Tākou (OTA), Murihiku (STL), Tasman (TAS), Taranaki (TKI), Te Whanga-nui-a-Tara (WGN), Waikato (WKO), Te Taihau ā uru (WTC)
Panama (PA) Entire Country
Peru (PE) Cusco (CUS)
Philippines (PH) Entire Country
Poland (PL) Entire Country
Puerto Rico (PR) Entire Country
Portugal (PT) Região Autónoma dos Açores (20), Região Autónoma da Madeira (30)
Palau (PW) Entire Country
Paraguay (PY) Entire Country
Qatar (QA) Entire Country
Réunion (RE) Entire Country
Romania (RO) Entire Country
Serbia (RS) Entire Country
Russian Federation (RU) Entire Country
Rwanda (RW) Entire Country
Sweden (SE) Entire Country
Singapore (SG) Entire Country
Saint Helena, Ascension and Tristan da Cunha (SH) Ascension (AC), Saint Helena (HL), Tristan da Cunha (TA)
Slovenia (SI) Entire Country
Svalbard and Jan Mayen (SJ) Entire Country
Slovakia (SK) Banskobystrický kraj (BC), Bratislavský kraj (BL), Košický kraj (KI), Nitriansky kraj (NI), Prešovský kraj (PV), Trnavský kraj (TA), Trenčiansky kraj (TC), Žilinský kraj (ZI)
San Marino (SM) Entire Country
Somalia (SO) Awdal (AW), Sanaag (SA), Sool (SO), Togdheer (TO), Woqooyi Galbeed (WO)
Suriname (SR) Entire Country
South Sudan (SS) Entire Country
Sao Tome and Principe (ST) Entire Country
El Salvador (SV) San Salvador (SS)
Togo (TG) Entire Country
Tunisia (TN) Entire Country
Tonga (TO) Entire Country
Turkey (TR) Entire Country
Taiwan, Province of China (TW) Entire Country
Tanzania, United Republic of (TZ) Entire Country
Ukraine (UA) Entire Country
Uganda (UG) Entire Country
United States of America (US) Alaska (AK), Alabama (AL), Arkansas (AR), American Samoa (AS), Arizona (AZ), California (CA), Colorado (CO), Connecticut (CT), District of Columbia (DC), Delaware (DE), Florida (FL), Georgia (GA), Guam (GU), Hawaii (HI), Iowa (IA), Idaho (ID), Illinois (IL), Indiana (IN), Kansas (KS), Kentucky (KY), Louisiana (LA), Massachusetts (MA), Maryland (MD), Maine (ME), Michigan (MI), Minnesota (MN), Missouri (MO), Northern Mariana Islands (MP), Mississippi (MS), Montana (MT), North Carolina (NC), North Dakota (ND), Nebraska (NE), New Hampshire (NH), New Jersey (NJ), New Mexico (NM), Nevada (NV), New York (NY), Ohio (OH), Oklahoma (OK), Oregon (OR), Pennsylvania (PA), Puerto Rico (PR), Rhode Island (RI), South Carolina (SC), South Dakota (SD), Tennessee (TN), Texas (TX), Utah (UT), Virginia (VA), Virgin Islands, U.S. (VI), Vermont (VT), Washington (WA), Wisconsin (WI), West Virginia (WV), Wyoming (WY)
Uruguay (UY) Entire Country
Holy See (VA) Entire Country
Venezuela (Bolivarian Republic of) (VE) Anzoátegui (B), Carabobo (G), Lara (K), Miranda (M), Monagas (N), Táchira (S), Zulia (V)
Virgin Islands (U.S.) (VI) Entire Country
Viet Nam (VN) Entire Country
Mayotte (YT) Entire Country
South Africa (ZA) Entire Country
Zambia (ZM) Entire Country
Zimbabwe (ZW) Entire Country