See also:

• publicholiday.region.get
• telecoms.dayparting functions

Returns a list of supported public holiday regions (ie regions for which we have public holiday information). Can be given filter args if you're trying to match on search strings.

Public holidays are used by some features, such as telecoms.dayparting.

When reading the below documentation, it helps to understand that public holiday regions are usally heirarchical, eg "Canada/Northwest Territories". Think of this as a master region and a sub-region, where "Canada" is the master region and "Northwest Territories" is the sub-region.

Arguments:

Example 1

Requesting a list of regions where the full region name starts "uk" by using the match_start filter argument.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "publicholiday.region.list",
   "args" : {
      "match_start" : "uk"
   }
}

JSON example response:

{
   "results" : {
      "data" : [
         "UK",
         "UK/England and Wales",
         "UK/Northern Ireland",
         "UK/Scotland"
      ],
      "more_rows" : 0
   },
   "success" : 1
}

Note that UK is returned as a separate region of its own. Public holidays assumed to be in this region are holidays that are relevant to all sub-regions of the UK (as per this example) eg Christmas day, as that is celebrated all across the UK. But holidays such as St Andrew's day are celebtrated in Scotland but nowhere else in the UK, so this public holiday is only specifically in the UK/Scotland region.

Sub-regions automatically include any holidays in their parent region, eg UK/Scotland includes ALL public holidays celebrated in Scotland, not just the ones unique to Scotland.

Example 2

Whereas suppling match_start with a value of just "u" includes other regions starting with "u":

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "publicholiday.region.list",
   "args" : {
      "match_start" : "u"
   }
}

JSON example response:

{
   "results" : {
      "data" : [
         "UK",
         "UK/England and Wales",
         "UK/Northern Ireland",
         "UK/Scotland",
         "USA",
         "USA/Alabama",
         "USA/Alaska",
         "USA/Arizona",
         "USA/Arkansas",
         "USA/California",
         "USA/Colorado",
         "USA/Connecticut",
         "USA/Delaware",
         "USA/District of Columbia",
         "USA/Florida",
         "USA/Georgia",
         "USA/Hawaii",
         "USA/Idaho",
         "USA/Illinois",
         "USA/Indiana",
         "USA/Iowa",
         "USA/Kansas",
         "USA/Kentucky",
         "USA/Louisiana",
         "USA/Maine",
         "USA/Maryland",
         "USA/Massachusetts",
         "USA/Michigan",
         "USA/Minnesota",
         "USA/Mississippi",
         "USA/Missouri",
         "USA/Montana",
         "USA/Nebraska",
         "USA/Nevada",
         "USA/New Hampshire",
         "USA/New Jersey",
         "USA/New Mexico",
         "USA/New York",
         "USA/North Carolina",
         "USA/North Dakota",
         "USA/Ohio",
         "USA/Oklahoma",
         "USA/Oregon",
         "USA/Pennsylvania",
         "USA/Rhode Island",
         "USA/South Carolina",
         "USA/South Dakota",
         "USA/Tennessee",
         "USA/Texas",
         "USA/Utah",
         "USA/Vermont",
         "USA/Virginia",
         "USA/Washington",
         "USA/West Virginia",
         "USA/Wisconsin",
         "USA/Wyoming"
      ],
      "more_rows" : 0
   },
   "success" : 1
}

Example 3

Using the browse argument makes the function behave a bit like listing the contents of a folder/directory, as if you are browsing through a file system:

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "publicholiday.region.list",
   "args" : {
      "browse" : 1
   }
}

JSON example response:

{
   "results" : {
      "data" : [
         "Canada",
         "Canada/",
         "UK",
         "UK/",
         "USA",
         "USA/"
      ],
      "more_rows" : 0
   },
   "success" : 1
}

Though note that each result in this example appears to have been duplicated (eg UK and UK/). This is deliberate behaviour. The entry without the trailing slash is a holiday region in its own right, whereas the entry with a trailing slash indicates that there are sub-regions of this region. See the next example.

Example 4

Using browse whilst specifying a prefix. In this example, we know that UK has sub-regions from the above example, so let's look inside that:

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "publicholiday.region.list",
   "args" : {
      "browse" : 1,
      "prefix" : "uk"
   }
}

JSON example response:

{
   "results" : {
      "data" : [
         "UK/England and Wales",
         "UK/Northern Ireland",
         "UK/Scotland"
      ],
      "more_rows" : 0
   },
   "success" : 1
}

Example 5

A fuzzy search on "scot":

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "publicholiday.region.list",
   "args" : {
      "match_fuzzy" : "scot"
   }
}

JSON example response:

{
   "results" : {
      "data" : [
         "UK/Scotland",
         "Canada/Nova Scotia"
      ],
      "more_rows" : 0
   },
   "success" : 1
}