holiday-oracle 0.1.2

Provides access to global holidays via the Holiday Oracle API.

Holiday Oracle Python bindings

The Holiday Oracle Python library provides convenient access to the global holiday API provided by Off Chain Data from applications written in the Python language.

Requirements

• An API token from Holiday Oracle
• Python 3.4+

Installation

Install with pip:

pip install --upgrade holiday-oracle

Install from source with:

pip install --editable .

Calling the API

Calling the API is straight-forward:

from offchain.api import HolidayOracleApi

api = HolidayOracleApi( token )
resp = api.me()
print( resp.json )

If no token is provided, the library will look for a OCD_TOKEN environment variable.

The HTTP response code, headers and raw response data are also provided in the response object.

Some API endpoints have mandatory parameters e.g.

resp = api.date( country="AU", date="2020-01-01" )

Optional parameters can also be provided in the same way e.g.

resp = api.date( country="AU", date="2020-01-01", subdivision="NSW" )

Handling errors

If an error occurs, an ApiError exception will be thrown e.g.

try:
    resp = api.me()
except ApiError as ex:
    print( "ERROR:", ex.message )

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://offchaindata.com/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