Working days API documentation for Developers (v1.2)

Introduction

Our HTTP JSON API (v1.2) exposes 3 kind of services you can plug to:

Analyse a period. You provide a start date and an end date, we respond with the number of days, working days, work hours, weekend days, the list of the public holidays over the period for a given country.

Add any number of working days / working hours / public holidays / weekend days to a given date. You provide a start date, we return the end date. We also return the days ventilation over that period.

List all the non working dates between 2 dates (they can be weekend days, public holidays or custom dates)

We cover more than 45 countries and 230 regional calendars. We also cover main stock exchanges calendars. The quality of our data is our top priority. We work hard to keep our database up to date by following government announcements regarding public holidays changes.

All the calendars can be fully customized from our friendly working days websites’ user interfaces (public holidays, weekend days, work hours, custom dates & more).

Without a key, you can immediately evaluate the service as long as your dates are inside the year 2013. In order to access the API without dates limitations, you will be needing a personal API key. Get your key right now, it comes with a SLA and a Data Quality Insurance .

Note that the period you want to analyze must not exceed 1600 days (4.4 years) in order not to overload our servers. We no longer have any other restrictions on dates.

Give also a try to our API test tool, it will let you understand the API behavior very quickly.

Now let's look at the API, some sample HTTP requests and JSON replies, and some PHP code examples (JSON libraries are available in all languages).

They trust us:

Analyse a period

Endpoint /analyse

Analyse a given calendar over a time period.

Arguments

Name	Description
key Required	Your personal API key
country_code Required	The ISO country code (2 letters). See the list of countries For instance, if you want to take into account the french calendar, send country_code=FR
start_date Required	The start date (YYYY-MM-DD)
end_date Required	The end date (YYYY-MM-DD)
start_time Optional	The start date's time (24 hours format, like 09:00 or 15:00, but not 3pm). If omitted, default value is 00:00.
end_time Optional	The end date's time (24 hours format, like 09:00 or 15:00, but not 3pm) If omitted, default value is 23:59.
configuration Optional	The name of the regional preset configuration. See the list of configurations Each country comes with a set of preset configurations (applicable public holidays in that region). For instance in the USA, you don't have the same public holidays in New York and in California. If you are interested with the working days calendar in New York State, you would go : contry_code=US&configuration=New+York. If you are interested in the american stock exchange opening calendar, you would go : contry_code=US&configuration=New+York+Stock+Exchange. If you don't provide the configuration parameter, the default configuration will be applied. In the case of the USA, the default configuration is California. Many countries have only one preset configuration (Chile, Denmark, China, Colombia, etc..), in that case this parameter is not necessary and will be ignored.
weekend Optional	Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday. 1: weekend day, 2: half weekend day (morning only), 3 half weekend day (afternoon only), 0: day of week Default value is 1000001 (weekend days on saturdays, sundays) except for Israel (weekend days on fridays, saturdays). If the weekend for you is sunday and monday, you can send: 1100000 If the weekend is saturday afternoon and sunday: 1000003 Alternating week structure (up to 4 weeks) is also possible (see this example)
week_hours Optional	Your week working hours structure. This parameter maybe useful when computing work hours over a period. Sunday morningSunday afternoonMonday morningMonday afternoonTuesday morningTuesday afternoonWednesday morningWednesday afternoonThursday morningThursday afternoonFriday morningFriday afternoonSaturday morningSaturday afternoon. Default value is 00444444444400* (4 working hours every morning and 4 working hours every afternoon except on saturday, sunday ; the morning ending at 12:00 (noon) and afternoon starting at 14:00 (2pm)). If you need a completely personalized week time schedule, go for a custom configuration. See this example.
week_times Optional	Your week working schedule structure. This parameter is useful when computing work hours over a period. When used, this parameter overides the week_hours parameter. For each day of the week define when working morning starts and ends, and when working afternoon starts and ends. Sunday morning startSunday morning endSunday afternoon startSunday afternoon endMonday morning startMonday morning endMonday afternoon startMonday afternoon end....Saturday morning startSaturday morning endSaturday afternoon startSaturday afternoon end* Defaut value is : 08:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:00 (working mornings from 8 to 12, working afternoons from 14 to 18) Note that a working schedule for a weekend day is simply ignored. Use the API TEST TOOL to easily define this parameter.
start_template Optional	The start date of an alternating week template (YYYY-MM-DD) If you define an alternating week template schedule, you have to tell which sunday the template is starting. Read this chapter of the documentation in order to learn more about alternating weeks template.
use_custom_configuration Optional	Take into account your own personal configuration. Send 1 for true. Default value is false. See this example.
profile_id Optional	If you created several profiles under your custom configuration, the ID of the profile to be used. 6 caracters. See this example.

Suppose we want to analyse the period from 1st january 2013 to 31th december 2013 in Canada, with default parameters, the URL to request is going to be¹:

https://api.workingdays.org/1.2/analyse?key=MYPERSONALKEY&country_code=CA&start_date=2013-01-01&end_date=2013-12-31

and the service is going to reply with a JSON response like that (because the parameter is omitted, default configuration Ontario is used):

 {
  "result": {
	"days": {
	  "total": "365",
	  "mondays": "52",
	  "tuesdays": "53",
	  "wednesdays": "52",
	  "thursdays": "52",
	  "fridays": "52",
	  "saturdays": "52",
	  "sundays": "52",
	  "hours": "8759.9833333333"
	},
	"working_days": {
	  "total": "250",
	  "mondays": "45",
	  "tuesdays": "52",
	  "wednesdays": "51",
	  "thursdays": "51",
	  "fridays": "51",
	  "saturdays": "0",
	  "sundays": "0",
	  "work_hours": "2008"
	},
	"weekend_days": {
	  "total": "104",
	  "mondays": "0",
	  "tuesdays": "0",
	  "wednesdays": "0",
	  "thursdays": "0",
	  "fridays": "0",
	  "saturdays": "52",
	  "sundays": "52"
	},
	"public_holidays": { 
		"2013-01-01":"New Year's Day",
		"2013-02-18":"Family Day",
		"2013-03-29":"Good Friday",
		"2013-05-20":"Victoria Day",
		"2013-07-01":"Canada Day",
		"2013-08-05":"August Civic Holiday",
		"2013-09-02":"Labour Day",
		"2013-10-14":"Thanksgiving Day",
		"2013-11-11":"Remembrance Day",
		"2013-12-25":"Christmas",
		"2013-12-26":"Boxing Day"
	 }
	}
 }

Suppose now we want to analyse the period from 1st january 2013 to 31th december 2013 in Germany with the public holidays calendar applicable in the state of Baden-Württemberg, and our non working weekend days are on sundays and mondays, the URL to request is going to be :

https://api.workingdays.org/1.2/analyse?key=MYPERSONALKEY&country_code=DE&configuration=Baden-Württemberg&start_date=2013-01-01&end_date=2013-12-31&weekend=1100000

and the service is going to reply with a JSON response like that:

{ 
"result": 
	{ 
		"days": { 
			"total": "365", 
			"mondays": "52", 
			"tuesdays": "53", 
			"wednesdays": "52", 
			"thursdays": "52", 
			"fridays": "52", 
			"saturdays": "52", 
			"sundays": "52",
			"hours": "8746"
		},
		"working_days": { 
			"total": "252", 
			"mondays": "0", 
			"tuesdays": "52", 
			"wednesdays": "50", 
			"thursdays": "48", 
			"fridays": "50", 
			"saturdays": "52", 
			"sundays": "0",
			"work_hours": "2016" 
		}, 
		"weekend_days": { 
			"total": "104", 
			"mondays": "52", 
			"tuesdays": "0", 
			"wednesdays": "0", 
			"thursdays": "0", 
			"fridays": "0", 
			"saturdays": "0", 
			"sundays": "52" 
		}, 
		"public_holidays": { 
			"2013-01-01":"Neujahrstag", 
			"2013-01-06":"Heilige Drei Könige", 
			"2013-03-29":"Karfreitag", 
			"2013-04-01":"Ostermontag", 
			"2013-05-01":"Tag der Arbeit", 
			"2013-05-09":"Christi Himmelfahrt", 
			"2013-05-20":"Pfingstmontag", 
			"2013-05-30":"Fronleichnam", 
			"2013-10-03":"Tag der Deutschen Einheit", 
			"2013-11-01":"Allerheiligen", 
			"2013-12-25":"Weihnachtstag", 
			"2013-12-26":"Zweiter Weihnachtstag"
		} 
	} 
}

Example PHP client code

$key="MYPERSONALKEY";

$country_code="DE";

$configuration=urlencode("Baden-Württemberg");  // $configuration="DE-BW"; would be equivalent (using the ISO code of the region)


$url="https://api.workingdays.org/1.2/analyse?key=$key&country_code=$country_code&configuration=$configuration&start_date=2013-01-01&end_date=2013-12-31&weekend=1100000";

echo $url . "<br><br>";

$options = array(
    'http' => array(
    'method'  => 'GET',
    'ignore_errors' => false
    )
);
$context  = stream_context_create($options);
$json_response = file_get_contents($url,false, $context);

if (mb_strrpos($http_response_header[0], '400')) // HTTP RESPONSE 400 is a bad request  ; you will end up here if your key is invalid or your paramaters are not correct or your monthly quota is exceeded
{
		echo "Something's wrong with my request : " .$json_response;
		return;
}
else if (mb_strrpos($http_response_header[0], '200')) //HTTP RESPONSE 200, all is OK
{
		$obj = json_decode($json_response);

		/* Please note that numbers values are represented within the JSON result as Strings.
		   For further operations they should be parsed into Floats numbers (and not integers) */
		echo "Number of working days on that period :". $obj->{'result'}->{'working_days'}->{'total'} . "<br><br>";

		echo "Number of fridays on that period :". $obj->{'result'}->{'days'}->{'fridays'}. "<br><br>";

		$public_holidays=$obj->{'result'}->{'public_holidays'};

		echo "The public holidays on that period :<br>";

		foreach($public_holidays as $key => $value) {
		  echo $key . " : " . $value. "<br>";
		}
 
}
else   // for instance a 500 internal server error.. I do not hope that !
{
		echo "Something's wrong : " .$http_response_header[0]." ".$json_response;
		return;
}

Add working days to a date

Endpoint /add_working_days

Arguments

Name	Description
key Required	Your personal API key
country_code Required	The ISO country code (2 letters). See the list of countries For instance, if you want to take into account the french calendar, send country_code=FR
start_date Required	The start date (YYYY-MM-DD)
increment Required	The number of working days you want to add to your start date (positive or negative integer but not zero)
include_start Optional	Should the count include the start_date? Default value is true. If you set include_start to false ("false" or "0"), the count will start at the next working day (or previous working day, if increment is negative)
configuration Optional	The name of the regional preset configuration. See the list of configurations Each country comes with a set of preset configurations (applicable public holidays in that region). For instance in the USA, you don't have the same public holidays in New York and in California. If you are interested with the working days calendar in New York State, you would go : contry_code=US&configuration=New+York. If you are interested in the american stock exchange opening calendar, you would go : contry_code=US&configuration=New+York+Stock+Exchange. If you don't provide the configuration parameter, the default configuration will be applied. In the case of the USA, the default configuration is California. Many countries have only one preset configuration (Chile, Denmark, China, Colombia, etc..), in that case this parameter is not necessary and will be ignored.
weekend Optional	Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday. 1: weekend day, 2: half weekend day (morning only), 3 half weekend day (afternoon only), 0: day of week Default value is 1000001 (weekend days on saturdays, sundays) except for Israel (weekend days on fridays, saturdays). If the weekend for you is sunday and monday, you can send: 1100000 If the weekend is saturday afternoon and sunday: 1000003
week_times Optional	Your week working schedule structure. This parameter is useful when computing work hours over a period. When used, this parameter overides the week_hours parameter. For each day of the week define when working morning starts and ends, and when working afternoon starts and ends. Sunday morning startSunday morning endSunday afternoon startSunday afternoon endMonday morning startMonday morning endMonday afternoon startMonday afternoon end....Saturday morning startSaturday morning endSaturday afternoon startSaturday afternoon end* Defaut value is : 08:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:00 (working mornings from 8 to 12, working afternoons from 14 to 18) Note that a working schedule for a weekend day is simply ignored. Use the API TEST TOOL to easily define this parameter.
start_template Optional	The start date of an alternating week template (YYYY-MM-DD) If you define an alternating week template schedule, you have to tell which sunday the template is starting. Read this chapter of the documentation in order to learn more about alternating weeks template.
use_custom_configuration Optional	Take into account your own personal configuration. Send 1 for true. Default value is false. See this example.
profile_id Optional	If you created several profiles under your custom configuration, the ID of the profile to be used. 6 caracters. See this example.

Suppose we want to add 90 working days to the 1st january 2013 over the french usual calendar, with default parameters, the URL to request is going to be:

https://api.workingdays.org/1.2/add_working_days?key=MYPERSONALKEY&country_code=FR&start_date=2013-01-01&increment=90

and the service is going to reply with a JSON response like that:

{
  "result": {
	"end_date":"2013-05-13",
    "days": {
      "total": "133",
      "mondays": "19",
      "tuesdays": "19",
      "wednesdays": "19",
      "thursdays": "19",
      "fridays": "19",
      "saturdays": "19",
      "sundays": "19",
      "hours": "3178"
    },
    "working_days": {
      "total": "90",
      "mondays": "18",
      "tuesdays": "18",
      "wednesdays": "17",
      "thursdays": "18",
      "fridays": "19",
      "saturdays": "0",
      "sundays": "0",
      "work_hours": "720"
    },
    "weekend_days": {
      "total": "38",
      "mondays": "0",
      "tuesdays": "0",
      "wednesdays": "0",
      "thursdays": "0",
      "fridays": "0",
      "saturdays": "19",
      "sundays": "19"
    },
	"public_holidays": { 
	"2013-01-01":"Jour de l'An",
	"2013-04-01":"Lundi de Pâques",
	"2013-05-01":"Fête du Travail",
	"2013-05-08":"Fête de la Victoire 45",
	"2013-05-09":"Jeudi de l'Ascension"
	}
 }
}

Example PHP client code


$json_response = file_get_contents("https://api.workingdays.org/1.2/add_working_days?key=MYPERSONALKEY&country_code=FR&start_date=2013-01-01&increment=90");

$obj = json_decode($json_response);

// End date
echo $obj->{'result'}->{'end_date'};

echo "<br>";

// Number of fridays on that period
echo $obj->{'result'}->{'days'}->{'fridays'};

// The public holidays on that period
$public_holidays=$obj->{'result'}->{'public_holidays'};

echo "<br>";

foreach($public_holidays as $key => $value) {
  echo $key . " : " . $value. "<br>";
}

Add public holidays to a date

Just change the endpoint to /add_public_holidays . The same logic remains unchanged (see add working days just above).

Add weekend days to a date

Just change the endpoint to /add_weekend_days . The same logic remains unchanged (see add working days just above).

Locating a postal address

Endpoint /address_to_configuration

Sometimes you may wonder which calendar configuration is relevant to a given customer's postal address.
Locating a postal address will remove 600 days from your monthly quota.

Arguments

Name	Description
key Required	Your personal API key
address Required	The postal address. It is a string with no constraint.

Suppose we need to know which calendar is applicable to this customer address: "Paseo del Violón 18006 Granada España"

https://api.workingdays.org/1.2/address_to_configuration?key=MYPERSONALKEY&address=Paseo del Violón 18006 Granada España

and the service is going to reply with a JSON response like that:

{ 
	"result": 
		{
			"status":"OK",
			"country_code":"ES",
			"configuration":"Andalucía",
			"formatted_address":"Paseo del Violón, 18006 Granada, Spain"			
		}
}

Example PHP client code


$address=urlencode("Paseo del Violón 18006 Granada España");
$json_response = file_get_contents("https://api.workingdays.org/1.2/address_to_configuration?key=MYPERSONALKEY&address=$address");

$obj = json_decode($json_response);
$status= $obj->{'result'}->{'status'};
if ($status=="OK")
{
	$country_code= $obj->{'result'}->{'country_code'};
	$configuration= $obj->{'result'}->{'configuration'};
	$formatted_address= $obj->{'result'}->{'formatted_address'}; 
}
else
	echo "The working days API was unable to locate this address";

Then you can use the resulting $country_code and $configuration to query any of the previous API methods.
(Note that if you query a postal address belonging to a region of the world we do not cover, for example Greenland, the address_to_configuration may still be successfully locating your address and reply with a country code and a region but the calendar method will then reply with an invalid country_code parameter.)

Custom configuration & profiles

The calendar of each country can be fully personalised independently.
Through a custom configuration you can:

Define your weekend days one by one

Define your own default week time schedule (1 to 4 weeks templates are supported). It is your own default definition of a regular week (working hours morning and afternoon for each day of the week)

Choose your public holidays one by one, or by selecting one of our preset configurations

Define one or several custom periodic rules: for instance "every second monday of the month is closed" or "every tuesday of january" has specific working hours that overloads your default week time schedule

Add some specific "custom dates" (full day or half day, typically days off). If a custom date is a working day, you can define its working hours, morning and afternoon, overloading your default week time schedule.

If you use this parameter (use_custom_configuration=1 when sending any command) then the configuration used is the one you defined when you are connected into the corresponding working days web site (using the same email as the one associated with your API account ; working days web sites are listed here by country.).
You can thus completely customize your calendar and be able to query it through the API.

Note that this feature can be freely tested over the year 2013 from the API TEST TOOL without an active subscription.

Let's get through a business case example to make it clear:
A flower shop located in Paris (country_code=FR) is willing to accept online orders for bouquets from its website. Preparing a bouquet requires a full working day delay (we want to use command=add_working_days&increment=2 ). The shop follows the usual french calendar but is closed every monday and opens on saturdays.
The shop has also a few annual closure, and that's why we need to define custom dates:

1. Go to the www.joursouvres.fr and connect ("connexion" button on the top right corner).
You can connect using any method you prefer (local account, Google or Facebook login) but you need to be using the same email than the one associated with you API account

2. From the setup screen, choose the public holidays when the shop is closed, and define your default weekend days.

3. In any calendar views, define your custom dates clicking on the period.
This shop is closing after the 15 august (the 14th is a french public holiday and then starts the annual closure period) :

Now our calendar is fully personalised, and we are ready to integrate that PHP code onto the shop website :

$options = array(
    'http' => array(
    'method'  => 'GET',
    'ignore_errors' => false
    )
);

$context  = stream_context_create($options);

$url="https://api.workingdays.org/1.2/add_working_days?key=MYPERSONALKEY&country_code=FR&increment=2&use_custom_configuration=1";



// regular wednesday june 14th, the bouquet can be ready for the day after : 2017-06-15
$start="2017-06-14";
$json_response = file_get_contents($url."&start_date=$start",false, $context);


if (mb_strrpos($http_response_header[0], '400')) 
		echo "Something's wrong with my request : " .$json_response;
else if (mb_strrpos($http_response_header[0], '200')) 
	echo "Next working day following $start is ".json_decode($json_response)->{'result'}->{'end_date'}; 


// order on saturday august 5th, the bouquet can be ready only on tuesday because of 2 weekends days : 2017-08-08
$start="2017-08-05";
$json_response = file_get_contents($url."&start_date=$start",false, $context);

if (mb_strrpos($http_response_header[0], '400')) 
		echo "Something's wrong with my request : " .$json_response;
else if (mb_strrpos($http_response_header[0], '200')) 
	echo "<br>Next working day following $start is ".json_decode($json_response)->{'result'}->{'end_date'}; 



// order on saturday august 12th , the bouquet can be ready only after the annual closure : 2017-09-01
$start="2017-08-12";
$json_response = file_get_contents($url."&start_date=$start",false, $context);

if (mb_strrpos($http_response_header[0], '400')) 
		echo "Something's wrong with my request : " .$json_response;
else if (mb_strrpos($http_response_header[0], '200')) 
	echo "<br>Next working day following $start is ".json_decode($json_response)->{'result'}->{'end_date'};

This script will output :
Next working day following 2017-06-14 is 2017-06-15
Next working day following 2017-08-05 is 2017-08-08
Next working day following 2017-08-12 is 2017-09-01

Have also a look at this other example that goes further into creating a custom configuration.

Profiles

When connected to a working days website, one set of these custom parameters is called a "profile".
You can create up to 5 different user profiles under one user account (for a given country; if you need more, let us know).

From the API, querying any command, if you are using the parameter use_custom_configuration=1 and have created several profiles, you should add the profile_id=yourprofileID parameter in order to specify which profile you intend to use.
The profile_id parameter is optional, if you created several profiles and omit the parameter, the first user profile will be used.
If you provide an invalid profile ID, a 400 error will be raised.
The profile ID can be copied from the user interface:

This new feature can be easily tried from the API TEST TOOL

Overloading a profile

When you provide a profile_id and some other parameters at the same time in a request, the parameters are going to overload the parameters defined at profile level.
Let's look at a real use case to see how this can be useful.

In some situation, you may want to define and maintain a custom calendar with the days all the firm is not working (typically a corporate schedule with public holidays & custom dates). This calendar is saved under a profile.
However, each employees or suppliers have a different week structure (some may have a 4 days work week, some a 5 days work week,..) and you want to be able to query the working days for each type of employees without having to maintain several profiles.

For instance, the profile E97F1F has a 1.5 weekend days per week definition and if you send this query

https://api.workingdays.org/1.2/analyse?key=YOUR-API-KEY&country_code=AU&start_date=2013-01-01&end_date=2013-12-31&profile_id=E97F1F

you will get 275.5 working days.

Now, if you overload the weekend structure with &weekend=1000001 (2 full weekend days)

https://api.workingdays.org/1.2/analyse?key=YOUR-API-KEY&country_code=AU&start_date=2013-01-01&end_date=2013-12-31&profile_id=E97F1F&weekend=1000001

you will get 250 working days as the 2 days weekend parameter is overloading the weekend definition of the profile.

The same logic applies with configuration and week_hours.

Work hours

When you analyse a period, the response also includes the number of work hours over the period.
If you omit the start_time and end_time parameters, the work hours are counted from the begining of the first day (start_date at 00:00) to the end of the last day (last_date at 23:59).
If you provid a start_time, and a end_time, the work hours are counted from start_date at start_time until end_date at end_time.

By default, the calculation of working hours is based on this default week time schedule but you can configure and use a custom week time schedule :

Now let's go through an example that requires customising the week time schedule:

Suppose in your firm located in Bern, Switzerland, friday is a day where your firm closes at 5pm, other days at 6pm.

1. Go to the www.arbeitstage.ch and connect ("connexion" button on the top right corner).
You can connect using any method you prefer (local account, Google or Facebook login) but you need to be using the same email than the one associated with you API account

2. From the setup screen, define your default weekly time schedule:

Now our calendar is personalised, and we are ready to integrate adding the parameter "use_custom_configuration=1".

Let's get the number of work hours on may 2019.

$options = array(
    'http' => array(
    'method'  => 'GET',
    'ignore_errors' => false
    )
);

$context  = stream_context_create($options);

/* you don't need to set the configuration because it is loaded from the custom configuration */
$url=https://api.workingdays.org/1.2/analyse?key=MYPERSONALKEY&country_code=CH&start_date=2019-05-01&end_date=2019-05-31&use_custom_configuration=1";

$json_response = file_get_contents($url,false, $context);

echo "Number of work hours in may 2019 :".json_decode($json_response)->{'result'}->{'work_hours'};

This script will output :
Number of work hours in may 2019 : 171
(because there is one public holidays in that month falling on a thursday)

Suppose now, this firm has 2 offices, one in Freiburg and one Bern. The two offices have the same corporate week schedule, but the public holidays are not the same following canton's local laws.
Suppose you want to compare the work hours in may between those 2 locations. Because the "Bern" configuration is associated with our custom configuration, you cannot use the parameter "use_custom_configuration=1". Instead, you can use the optional parameter at request level "week_hours=0*0*4*4*4*4*4*4*4*4*4*3*0*0*" which defines our week hours structure. It is the number of work hours in sunday morning, sunday afternoon, monday morning, monday afternoon, .., .., saturday morning, saturday afternoon, separated by '*'.
Let's look at the some sample code:

$options = array(
    'http' => array(
    'method'  => 'GET',
    'ignore_errors' => false
    )
);

$context  = stream_context_create($options);


$url="https://api.workingdays.org/1.2/analyse?key=MYPERSONALKEY&country_code=CH&configuration=Bern&start_date=2013-05-01&end_date=2013-05-31&week_hours=0*0*4*4*4*4*4*4*4*4*4*3*0*0*";

$json_response = file_get_contents($url,false, $context);

echo "Number of work hours in may 2013 in Bern:".json_decode($json_response)->{'result'}->{'work_hours'}; 

$url="https://api.workingdays.org/1.2/analyse?key=MYPERSONALKEY&country_code=CH&configuration=Freiburg&start_date=2013-05-01&end_date=2013-05-31&week_hours=0*0*4*4*4*4*4*4*4*4*4*3*0*0*";

$json_response = file_get_contents($url,false, $context);

echo "Number of work hours in may 2013 in Freiburg:".json_decode($json_response)->{'result'}->{'work_hours'};

This script will output:
Number of work hours in may 2013 in Bern: 163
Number of work hours in may 2013 in Freiburg: 155
because those two cantons don't have same public holidays in may.

Note that in that exemple, a custom_configuration was used, but a week_times paramater could have been used define instead.
In that case, no connection to the working days site would have been necessary.

Add working hours to a date

Endpoint /add_working_hours

Adding an amount of working time to a given start date/time, can be very useful (for instance, implementing an SLA for a support team).
An amount of working time can be added or removed, over the default working week time schedule or over a personalised time schedule.
This command will consume 1 day for every 8 hours added/removed from your monthly quota.
Let's look at the command definition and some examples.

Arguments

Name	Description
key Required	Your personal API key
country_code Required	The ISO country code (2 letters). See the list of countries For instance, if you want to take into account the french calendar, send country_code=FR
start_date Required	The start date (YYYY-MM-DD)
start_time Required	The start time in a 24 hours format with leading zeros. For example 08:15 (but not 8:15) or 15:00 (but not 3pm)
increment_time Required	The amount of working time to be added (or removed) to the start date time. Format: H:i For example, to add one hour : 1:00. To add 30 hours and 15 minutes: 30:15. To remove 45 minutes : -0:45 This amount cannot exceed 5000 hours.
configuration Optional	The name of the regional preset configuration. See the list of configurations
weekend Optional	Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday. 1: weekend day, 2: half weekend day (morning only), 3 half weekend day (afternoon only), 0: day of week Default value is 1000001 (weekend days on saturdays, sundays) except for Israel (weekend days on fridays, saturdays). If the weekend for you is sunday and monday, you can send: 1100000 If the weekend is saturday afternoon and sunday: 1000003
week_hours Optional	Your week working hours structure. Sunday morningSunday afternoonMonday morningMonday afternoonTuesday morningTuesday afternoonWednesday morningWednesday afternoonThursday morningThursday afternoonFriday morningFriday afternoonSaturday morningSaturday afternoon. Default value is 00444444444400* (4 working hours every morning and 4 working hours every afternoon except on saturday, sunday ; the morning ending at 12:00 (noon) and afternoon starting at 14:00 (2pm)). If you need a completely personalized week schedule, go for a custom configuration.
week_times Optional	Your week working schedule structure. This parameter is useful when computing work hours over a period. When used, this parameter overides the week_hours parameter. For each day of the week define when working morning starts and ends, and when working afternoon starts and ends. Sunday morning startSunday morning endSunday afternoon startSunday afternoon endMonday morning startMonday morning endMonday afternoon startMonday afternoon end....Saturday morning startSaturday morning endSaturday afternoon startSaturday afternoon end* Defaut value is : 08:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:0008:0012:0014:0018:00 (working mornings from 8 to 12, working afternoons from 14 to 18) Note that a working schedule for a weekend day is simply ignored. Use the API TEST TOOL to easily define this parameter.
start_template Optional	The start date of an alternating week template (YYYY-MM-DD) If you define an alternating week template schedule, you have to tell which sunday the template is starting. Read this chapter of the documentation in order to learn more about alternating weeks template.
use_custom_configuration Optional	Take into account your own personal configuration. Send 1 for true. Default value is false. See this example.
profile_id Optional	If you created several profiles under your custom configuration, the ID of the profile to be used. 6 caracters. See this example.

Suppose we want to add 4 working hours to the January 8th 2013, 11:00 over the south african usual calendar, with default settings, the URL to request is going to be:

https://api.workingdays.org/1.2/add_working_hours?key=MYPERSONALKEY&country_code=ZA&start_date=2013-01-08&start_time=11:00&increment_time=4:00

The service is going to reply with a JSON response like that:
(because the default time schedule is applied, we have a lunch break between 12:00 and 14:00, and adding 4 hours takes us to 17:00 (5pm)).

{
"result": {
  "end_date":"2013-01-08",
  "end_time":"17:00"
	  }
}

Example PHP client code


$json_response = file_get_contents("https://api.workingdays.org/1.2/add_working_hours?key=MYPERSONALKEY&country_code=ZA&start_date=2013-01-08&start_time=11:00&increment_time=2:00");

$obj = json_decode($json_response);

// End date
echo $obj->{'result'}->{'end_date'}." ".$obj->{'result'}->{'end_time'};

Here is the default working hours of the week (for every calendars):

Now let's configure a custom week time schedule.
Let's go to south-africa.workingdays.org sign up or sign in using the same email as the account associated with the API.
Then define your custom time schedule from the setup screen.

Now let's try again adding 4 working hours to the January 8th 2013, 11:00 over the south african usual calendar, this time using our custom configuration:

https://api.workingdays.org/1.2/add_working_hours?key=MYPERSONALKEY&country_code=ZA&start_date=2013-01-08&start_time=11:00&increment_time=2:00&use_custom_configuration=1

The service is going to reply with a JSON response like that:
(because now the lunch break being between 13:00 and 14:00, adding 4 hours takes us to 16:00 (4pm)).

{
"result": {
  "end_date":"2013-01-08",
  "end_time":"16:00"
	  }
}

Alternating weeks

It is not rare that organisations use alternating schedules.
For exemple, on week A a team is off on saturday-sunday, but on week B the same team if off on sunday-monday, the sequence Week A / Week B / Week A / Week B repeating.

The weekend parameter

The first week will be defined as 100001 and the next as 1100000.
The weekend parameter 1000011100000 is valid and defines a 2 weeks template.
Up to 4 weeks is accepted which means the weekend parameter length can be 7 (default), 14 (2 weeks alternating schedule), 21 (3 weeks alternating schedules) or 28 (4 weeks alternating schedules)

The start_template parameter

If are using such an alternating week template, you have to tell which sunday this sequence is starting (the sequence will repeat from that date in the future and in the past).

The week_times parameter

The working hours of each of the week of the template can be customized, in order to also let you parameter a different week time schedule on each rotating week.
For example on week A, thursdays end at 16:30, on week B they end at 17:30.
week_times=08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*08:00*12:00*14:00*16:30*08:00*12:00*14:00*18:00*
08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*08:00*12:00*14:00*17:30*
08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*08:00*12:00*14:00*18:00*

Use the API TEST TOOL to easily define those 3 parameters.

(Note that alternatively, all those settings can be defined within the correponding working days website interface and used through a custom configuration.)

Get day information

Endpoint /get_info_day

Get all the detailed information about a specific date.
Each day is characterized by a morning and an afternoon.
If an half day (morning or afternoon) is worked, it has working hours, and wages. It can be a regular working day, or a custom working day.
If an half day is not worked, the number of working hours and the wages are equal to zero. It can be weekend, a public holiday, or a custom non working day.
By default, a day is a working day, a weekend day or a public holiday.
But they can be defined more finely through a custom configuration.

Arguments

Name	Description
key Required	Your personal API key
country_code Required	The ISO country code (2 letters). See the list of countries For instance, if you want to take into account the french calendar, send country_code=FR
date Required	The date to be analysed (YYYY-MM-DD)
configuration Optional	The name of the regional preset configuration. See the list of configurations
weekend Optional	Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday. 1: weekend day, 2: half weekend day (morning only), 3 half weekend day (afternoon only), 0: day of week Default value is 1000001 (weekend days on saturdays, sundays) except for Israel (weekend days on fridays, saturdays). If the weekend for you is sunday and monday, you can send: 1100000 If the weekend is saturday afternoon and sunday: 1000003
use_custom_configuration Optional	Take into account your own personal configuration. Send 1 for true. Default value is false. See this example.
profile_id Optional	If you created several profiles under your custom configuration, the ID of the profile to be used. 6 caracters. See this example.

Here is an example URL:

https://api.workingdays.org/1.2/get_info_day?key=MYPERSONALKEY&country_code=GB&date=2013-01-01

And here is an example JSON response of this service:

{
"result": {
  "working_day":"0",
  "work_hours":"0",
  "wages":"0",
  "morning_start":"",
  "morning_end":"",
  "afternoon_start":"",
  "afternoon_end":"",
  "public_holiday":"1",
  "public_holiday_description":"New Year's Day",
  "weekend_day":"0",
  "custom_date":"0",
  "custom_date_description":"",
  "custom_date_color":"",
	  }
}

And here is the definition of each field of this JSON response:

result->working_day: 0 if's not a working day / 1 if it is a working day / 0.5 in case you defined an half open day through a custom configuration

result->work_hours: the number of working hours in this day (a float between 0 and 24)

result->wages: the wages earned during this day this day (a float). By default, this is equal to the number of work hours x 20, but it can be define more finely through a custom configuration

result->morning_start: the start time of the working morning in a 24 hours format with leading zeros (for instance 08:00). If that morning is not worked, the field is empty.

result->morning_end: the end time of the working morning in a 24 hours format with leading zeros (for instance 12:00). If that morning is not worked, the field is empty.

result->afternoon_start: the start time of the working afternoon in a 24 hours format with leading zeros (for instance 14:00). If that afternoon is not worked, the field is empty.

result->afternoon_end: the end time of the working afternoon in a 24 hours format with leading zeros (for instance 18:00). If that afternoon is not worked, the field is empty.

result->public_holiday: 0 if's not a public holiday / 1 if it is a public holiday / 0.5 if is a public holiday only the morning or the afternoon

result->public_holiday_description: in case that day is a public holiday, you will get it's name here. For example "New year's day"

result->weekend_day: 0 if's not a weekend day / 1 if it is a weekend day / 0.5 if you defined an half weekend day through a custom configuration

result->custom_date: 0 if you did not define any custom date on that day / 1 if you define a custom date on that day / 0.5 if you define an half custom date on that day

result->custom_date_description: In case you defined a custom date through a custom configuration, you get the label you defined here. For example "My firm is closed"

result->custom_date_color: In case you defined a custom date, you get the color you choose here (orange, pink, blue, green, yellow or periodic). Colors can be used to organised your custom dates according to your own categories. "periodic" is the light blue color you get when you define a periodic custom date rule (for instance, "every second friday of the month is closed")

Each request to get_info_day will remove one day from your monthly quota.

Now let's look at a typical example :

« A cultural establishment located in New York is opened to public from tuesday to sunday from 11:00 to 18:00.
It remains open on every federal public holidays except on Thanksgiving Day and Christmas Day.
Every first saturday of the month, it stays open until 23:00.
Each year, there is an annual closure for maintenance, usualy in august but the dates can change every year and needs to be configured easily.
The establishment has a website, it would be nice if it could give the opening hours of the day. »

All that can be implemented in a few minutes:

Go to workingdays.us sign up or sign in using the same email as the one associated with your API subscription (all this process can be tested over the year 2013 without an active subscription from the API TEST TOOL)

Go to the setup screen and define your weekend days, and choose your public holidays:

From the setup screen and define your default week time schedule:

From the setup screen, open the "Custom dates" panel -> "Periodic dates" sub panel and define your custom date rule (they will appear in a light blue on the calendar views):

From any calendar view, click and drag the mouse to define your annual closures periods (you can choose a color, to help you define you own categories : for example orange for inventory closure, yellow for exceptional closures due to the pandemic, and so on..)

Now our calendar is fully configured.
The webmaster of the establishment just need to implement this request every morning (typically through a cron) to display the opening hours of the establishment.
Here we give a PHP example :


$today=new DateTime();
$json_response = file_get_contents("https://api.workingdays.org/1.2/get_info_day?key=MYPERSONALKEY&country_code=US&use_custom_configuration=1&date=".$today->format("Y-m-d"));

$obj = json_decode($json_response);

if ($obj->{'result'}->{'working_day'}=="0")
	echo "Closed today";
else
	echo "Opening hours for today: From ".$obj->{'result'}->{'morning_start'}." to ".$obj->{'result'}->{'afternoon_end'};

List non working days

Endpoint /list_non_working_days

List the non working days (weekend days, public holidays and custom dates) between 2 dates.

Arguments

Name	Description
key Required	Your personal API key
country_code Required	The ISO country code (2 letters). See the list of countries
start_date Required	The start date (YYYY-MM-DD)
end_date Required	The end date (YYYY-MM-DD)
configuration Optional	The name of the regional preset configuration. See the list of configurations Each country comes with a set of preset configurations (applicable public holidays in that region). For instance in the USA, you don't have the same public holidays in New York and in California. If you are interested with the working days calendar in New York State, you would go : contry_code=US&configuration=New+York. If you are interested in the american stock exchange opening calendar, you would go : contry_code=US&configuration=New+York+Stock+Exchange. If you don't provide the configuration parameter, the default configuration will be applied. In the case of the USA, the default configuration is California. Many countries have only one preset configuration (Chile, Denmark, China, Colombia, etc..), in that case this parameter is not necessary and will be ignored.
weekend Optional	Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday. 1: weekend day, 2: half weekend day (morning only), 3 half weekend day (afternoon only), 0: day of week Default value is 1000001 (weekend days on saturdays, sundays) except for Israel (weekend days on fridays, saturdays). If the weekend for you is sunday and monday, you can send: 1100000 If the weekend is saturday afternoon and sunday: 1000003
use_custom_configuration Optional	Take into account your own personal configuration. Send 1 for true. Default value is false. See this example.
profile_id Optional	If you created several profiles under your custom configuration, the ID of the profile to be used. 6 caracters. See this example.

Suppose we want to get the list of all the non working days (weekend days, public holidays or custom dates) from 1st january 2013 to 31th december 2013 in Canada, with default parameters, the URL to request is going to be:

https://api.workingdays.org/1.2/list_non_working_days?key=MYPERSONALKEY&country_code=CA&start_date=2013-01-01&end_date=2013-12-31

and the service is going to reply with a JSON response like that:

 
{
"result": 
{ 
"non_working_days": {
"2013-01-01":"New Year's Day","2013-01-05":"weekend day","2013-01-06":"weekend day","2013-01-12":"weekend day","2013-01-13":"weekend day","2013-01-19":"weekend day","2013-01-20":"weekend day","2013-01-26":"weekend day","2013-01-27":"weekend day","2013-02-02":"weekend day","2013-02-03":"weekend day","2013-02-09":"weekend day","2013-02-10":"weekend day","2013-02-16":"weekend day","2013-02-17":"weekend day","2013-02-18":"Family Day","2013-02-23":"weekend day","2013-02-24":"weekend day","2013-03-02":"weekend day","2013-03-03":"weekend day","2013-03-09":"weekend day","2013-03-10":"weekend day","2013-03-16":"weekend day","2013-03-17":"weekend day","2013-03-23":"weekend day","2013-03-24":"weekend day","2013-03-29":"Good Friday","2013-03-30":"weekend day","2013-03-31":"weekend day","2013-04-06":"weekend day","2013-04-07":"weekend day","2013-04-13":"weekend day","2013-04-14":"weekend day","2013-04-20":"weekend day","2013-04-21":"weekend day","2013-04-27":"weekend day","2013-04-28":"weekend day","2013-05-04":"weekend day","2013-05-05":"weekend day","2013-05-11":"weekend day","2013-05-12":"weekend day","2013-05-18":"weekend day","2013-05-19":"weekend day","2013-05-20":"Victoria Day","2013-05-25":"weekend day","2013-05-26":"weekend day","2013-06-01":"weekend day","2013-06-02":"weekend day","2013-06-08":"weekend day","2013-06-09":"weekend day","2013-06-15":"weekend day","2013-06-16":"weekend day","2013-06-22":"weekend day","2013-06-23":"weekend day","2013-06-29":"weekend day","2013-06-30":"weekend day","2013-07-01":"Canada Day","2013-07-06":"weekend day","2013-07-07":"weekend day","2013-07-13":"weekend day","2013-07-14":"weekend day","2013-07-20":"weekend day","2013-07-21":"weekend day","2013-07-27":"weekend day","2013-07-28":"weekend day","2013-08-03":"weekend day","2013-08-04":"weekend day","2013-08-10":"weekend day","2013-08-11":"weekend day","2013-08-17":"weekend day","2013-08-18":"weekend day","2013-08-24":"weekend day","2013-08-25":"weekend day","2013-08-31":"weekend day","2013-09-01":"weekend day","2013-09-02":"Labour Day","2013-09-07":"weekend day","2013-09-08":"weekend day","2013-09-14":"weekend day","2013-09-15":"weekend day","2013-09-21":"weekend day","2013-09-22":"weekend day","2013-09-28":"weekend day","2013-09-29":"weekend day","2013-10-05":"weekend day","2013-10-06":"weekend day","2013-10-12":"weekend day","2013-10-13":"weekend day","2013-10-14":"Thanksgiving Day","2013-10-19":"weekend day","2013-10-20":"weekend day","2013-10-26":"weekend day","2013-10-27":"weekend day","2013-11-02":"weekend day","2013-11-03":"weekend day","2013-11-09":"weekend day","2013-11-10":"weekend day","2013-11-16":"weekend day","2013-11-17":"weekend day","2013-11-23":"weekend day","2013-11-24":"weekend day","2013-11-30":"weekend day","2013-12-01":"weekend day","2013-12-07":"weekend day","2013-12-08":"weekend day","2013-12-14":"weekend day","2013-12-15":"weekend day","2013-12-21":"weekend day","2013-12-22":"weekend day","2013-12-25":"Christmas","2013-12-26":"Boxing Day","2013-12-28":"weekend day","2013-12-29":"weekend day" }
}
}

Now, let's go for some sample code.

Our flower shop of the previous example needs to build a custom date picker to let its customers choose a delivery date from the flower online shop (from today and within the next 3 months). We need to take into account the custom calendar of the shop (it is managed in a confortable way within the corrsponding working days site).

First, let's see how we can invalidate some dates with a standard jquery date picker (here we forbid 3 dates from being picked just for demonstration purpose):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>jQuery UI Datepicker - Restrict date range</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.12.1/themes/base/jquery-ui.css">
 
  <script src="https://code.jquery.com/jquery-1.12.4.js"></script>
  <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
  
  <script>
  
  var myoffdays=["2017-05-10","2017-05-26","2017-05-28"]
  
  function isDateOff(date)
  {
	  var day =  parseInt(date.getDate(),10)
	  var month= parseInt(date.getMonth()+1,10)
	  var year=  parseInt(date.getFullYear(),10)
	  
	  var found=false
	  for (var i=0;i<myoffdays.length;i++)
	  {
		 // console.log("i="+i "day="+day +"\n")
		  
		  var res=myoffdays[i].split("-")
		  day_off =  parseInt(res[2],10)
		  month_off =  parseInt(res[1],10)
		  year_off =  parseInt(res[0],10)
		  console.log(day +"\n")
		  
		  if (year_off==year &&  month_off==month && day_off==day )
			  return true
		  
	  }
	  return found
  }
  
  function myBeforeShowDay(date)
  {
	  if  (isDateOff(date))
		  return [false,'']
	  else
		  return [true,'']
	
  }
  
  $( function() {
	  $('#datepicker').datepicker(
				{ 	minDate: +1, 
				    maxDate: +90,
                    beforeShowDay: myBeforeShowDay });
    
  }
  );

  </script>
</head>
<body>
 
 <p><input type="text" id="datepicker"></p>
 
</body>
</html>

And here is the result, with those 3 dates being none selectable:

Now, we need to replace those 3 dates with our real non working days over the next 3 months, by sending server side PHP request to our API command list_non_working_days, we can generate that javascript array at runtime :

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>jQuery UI Datepicker - Restrict date range</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.12.1/themes/base/jquery-ui.css">
 
  <script src="https://code.jquery.com/jquery-1.12.4.js"></script>
  <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
  

  
  <script>
  
  var myoffdays=[


<?php

  

$key="MYPERSONALKEY";

$country_code="FR";

$url="http://api.workingdays.org/1.2/api.php?key=$key&command=list_non_working_days&country_code=$country_code&start_date=2017-05-01&end_date=2017-08-01&weekend=1100000&use_custom_dates=1";

$options = array(

    'http' => array(

    'method'  => 'GET',

    'ignore_errors' => true

    )

);

$context  = stream_context_create($options);

$json_response = file_get_contents($url,false, $context);



if (mb_strrpos($http_response_header[0], '400')) 

{

        echo "Something's wrong with my request : " .$json_response;

        return;

}

else if (mb_strrpos($http_response_header[0], '200')) //HTTP RESPONSE 200, all is OK

{

        $obj = json_decode($json_response);

        

        $non_working_days=$obj->{'result'}->{'non_working_days'};

        foreach($non_working_days as $key => $value) {

          echo "'$key',";

        }

    

}

        

  ?>

  ];
  
  function isDateOff(date)
  {
	  var day =  parseInt(date.getDate(),10)
	  var month= parseInt(date.getMonth()+1,10)
	  var year=  parseInt(date.getFullYear(),10)
	  
	  var found=false
	  for (var i=0;i<myoffdays.length;i++)
	  {
		 // console.log("i="+i "day="+day +"\n")
		  
		  var res=myoffdays[i].split("-")
		  day_off =  parseInt(res[2],10)
		  month_off =  parseInt(res[1],10)
		  year_off =  parseInt(res[0],10)
		  console.log(day +"\n")
		  
		  if (year_off==year &&  month_off==month && day_off==day )
			  return true
		  
	  }
	  return found
  }
  
  function myBeforeShowDay(date)
  {
	  if  (isDateOff(date))
		  return [false,'']
	  else
		  return [true,'']
	
  }
  
  $( function() {
	  $('#datepicker').datepicker(
				{ 	minDate: +1, 
				    maxDate: +90,
                    beforeShowDay: myBeforeShowDay ,
					changeMonth: true,
			        changeYear: true});
    
  }
  );

  </script>
</head>
<body>
 
 <p><input type="text" id="datepicker"></p>
 
</body>
</html>

and here is the result (may 11 is a custom closure date, may 25 is a standard public holiday)

Stock exchange calendars

We do cover the following stock exchanges:

Europe

London Stock Exchange

Paris, Amsterdam, Brussels, Lisbon, Madrid, Milan

Börse Frankfurt

Börse Zürich

America

New York Stock Exchange

Toronto Stock Exchange

Pacific

Australian Stock Exchange

When you query the API, the response's working days value correponds to the number of trading days.

Note that in Paris, Amsterdam, Brussels, Lisbon, Madrid, Milan, Sydney, trading ceases at 14:00 on the 24th and 31th of december. Therefore, the API will count each of those days as 0.5 working day and 0.5 public holiday.

What about hours of quotation?

By default, it you omit the work_hours parameter, we apply the week hours schedule of the stock exchange, so the work_hours field in the response correponds to the number of hours of trading hours over the period.
Let's have a look at an example:

Suppose we want to know how many hours the market was open at Euronext on 2013-12-31:

$country_code="FR";

$configuration=urlencode("Calendrier boursier (Euronext Paris)");

$json_response = file_get_contents("https://api.workingdays.org/1.2/analyse?key=MYPERSONALKEY&country_code=$country_code&configuration=$configuration&start_date=2013-12-31&end_date=2013-12-31");

$obj = json_decode($json_response);

$trading_hours=$obj->{'result'}->{'working_days'}->{'work_hours'}; //this a string carrying a float

//let's parse the String into a Float number
$ttimefloat=floatval($trading_hours);
//let's convert the Float into a HHhMM format
$HH=floor($ttimefloat);
$MM=$ttimefloat-$HH;
$MM=round($MM*60);
if ($MM<10)
	$MM="0".$MM;
		
echo "Number of trading hours at Paris Euronext on 2013-12-31 : ".$trading_hours." h (".$HH."h".$MM.")";

This script will output "Number of trading hours at Paris Euronext on 2013-12-31 : 5.083 h (5h05)"
Indeed the market opens at 9:00 and closes at 14:05 on december 24th and 31th.

If you want to visualize the week time schedule applied, you can go to the correponding working days website, in the setup screen, choose the "Bourse de Paris (Euronext)" preset configuation, under the "Work hours" tab-pane :

Hours and Daylight saving time (DST)

When you analyse a period, the response also includes the number of hours over the period (result -> days -> hours).
Notice that is not so simple, to give precisely the number of hours between two dates.
For example, in Europe, between saturday, march 26th, 2022 at 5pm and sunday, march 27th at 5pm there are not 24 hours but only 23 because of the DST (one hour is lost at 2am).

In North America, between saturday, november 5th 2022 at 5pm and sunday, november 6th 2022 at 5pm, there are 25 hours (one hour is gained during the night).
Of course a full year, always have 365 * 24 hours (leap years 366 * 24).

Our API tracks the DST for each region covered.
Some countries like China, Japan, Singapore, Russia, Colombia, Argentina do not change clock over the year.

Know your quota

Endpoint /quota

Each API call consumes part of your monthly quota. The days removed from your quota after a query is equal to the lengh in days of the resulting period.
When you send a request like "country_code=CA&command=analyse&start_date=2019-01-01&end_date=2019-12-31" , it will take off 365 days of your monthly quota because they are 365 days in the year 2019.
When you send a request like "country_code=FR&command=add_working_days&start_date=2020-01-01&increment=100", it will take off 147 days of your monthly quota because the resulting period is 147 days long.
Note that when you send a request like "command=address_to_configuration", it will remove 600 days from your monthly quota for any given address.

Each API response contains the proprietary HTTP header 'consumed-quota' telling you the value of the quota consumed by the request.

The monthly quota is reset at the end of each month at midgnight UTC+1.
During the month, you will receive an automatic email alert when you reach 80% of your quota, and when you reach 100% of your quota.

At any time, you can query your quota through the API, with the command quata. It will return the state of your plan (1:active, 2:cancelled, -2: unknown key), your current quota (days left to be analysed within this month) and the quota that will be available next month.

A request on command=quota does not consume any of your quota.

Arguments

Name	Description
key Required	Your personal API key

The URL

https://api.workingdays.org/1.2/quota?key=MYPERSONALKEY

and the service is going to reply with a JSON response like that:

{
"result": 
{ 
"state": "1",
"current": "215000",
"next": "300000"
}
}

Securing your code

Before you go live, you want to make sure your code is robust.

First, adding a changing HTTP parameter can be a good hack to avoid all the caches mechanism that could be met on the road (keep in mind we are regularly updating our public holidays database).

Next handling exception properly is a key thing to do.
You need to check the HTTP STATUS code of the web service response.
If you get an HTTP 200, all is ok.
If you get 400, something is wrong with your request or your quota has been exceeded: you should look at the response string and maybe implement some alert for yourself.
In any other case, you might want to implement one or several retries because networks failures happen.

After you get an HTTP 200, you need to parse the response string (decode the JSON). This operation can fail too for an unknown reason: we suggest handling and logging any exception there also.

PHP example

$key="MY-PERSONAL-KEY";

$country_code="DE";

/* url encode special characters */
$configuration=urlencode("Baden-Württemberg"); 

/* adding a changing parameter just to make sure this request will never be cached; this parameter will simply be ignored by the API */
$nocache="nocache=".microtime(true); 

$url="https://api.workingdays.org/1.2/analyse?key=$key&country_code=$country_code&configuration=$configuration&start_date=2013-01-01&end_date=2013-12-31&weekend=1100000&$nocache";

echo $url . "<br><br>";

$options = array(
    'http' => array(
    'method'  => 'GET',
    'ignore_errors' => true
    )
);
$context  = stream_context_create($options);
$json_response = file_get_contents($url,false, $context);
$response_code=$http_response_header[0];  //should be "HTTP/1.1 200 OK"


/* the API will raise an HTTP 400 when something is wrong with the parameters */
if (mb_strrpos($http_response_header[0], '400')) 
{
		echo "Something's wrong with my request or my quota is exceeded: " .$json_response; //THERE IS SOMETHING TO DO AT CODE LEVEL..
		exit(1);
}
else if  (!mb_strrpos($response_code, '200')) // SOMETHING UNKOWN HAPPENED (it might be a network failure on your side)
{
	echo "LETS GO FOR A RETRY BECAUSE SOMETHING HAPPENED ON THE FIRST CALL: ($response_code)";
	sleep(2);
	$json_response = file_get_contents($url,false, $context);
	$response_code=$http_response_header[0];  
	if (!mb_strrpos($response_code, '200'))
				{
					echo "FAILURE AGAIN NOW WE STOP";
					exit(2);
				}
	
}

//NOW EVERYTHING IS OK
$obj = json_decode($json_response);
$jsonerror=json_last_error(); //LETS CHECK IF PARSING IS OK
if ($jsonerror==JSON_ERROR_NONE)
{
	
		

		echo "Number of working days on that period :". $obj->{'result'}->{'working_days'}->{'total'} . "<br><br>";

		echo "Number of fridays on that period :". $obj->{'result'}->{'days'}->{'fridays'}. "<br><br>";

		$public_holidays=$obj->{'result'}->{'public_holidays'};

		echo "The public holidays on that period :<br>";

		foreach($public_holidays as $key => $value) {
		  echo $key . " : " . $value. "<br>";
		}
}
else
{
	echo "Error decoding JSON : $jsonerror"; //HERE YOU SHOULD LOOK AT THE RESPONSE STRING IN DETAILS
	exit(3);
}
 
exit(0); //EVERYTHING WAS FINE

Open API documentation

[19 august 2022] We now propose an Open API documentation and a Swagger definition.

Proposing an Open API documentation comes with an effort on our part to offering a standard API (OAS3) that can be discovered and interfaced easily with usual developer tools.

Footnote about endpoints

The URL endpoint of the API can be replace with a command parameter. Both URL are working and equivalent:

https://api.workingdays.org/1.2/api.php?command=analyse&start_date=....

https://api.workingdays.org/1.2/analyse?start_date=....

We will support both URL structure for ascending compatibility considerations. However, from now on (August 2022), we do encourage the second structure (abandonning the command parameter) because it is more standard and won't be documentating anymore the first approach (although it will sill be supported).

Analyse a period

Endpoint /analyse

Arguments

key

country_code

start_date

end_date

start_time

end_time

configuration

weekend

week_hours

week_times

start_template

use_custom_configuration

profile_id

Add working days to a date

Endpoint /add_working_days

Arguments

key

country_code

start_date

increment

include_start

configuration

weekend

week_times

start_template

use_custom_configuration

profile_id

Add public holidays to a date

Add weekend days to a date

Locating a postal address

Endpoint /address_to_configuration

Arguments

key

address

Custom configuration & profiles

Profiles

Overloading a profile

Work hours

Add working hours to a date

Endpoint /add_working_hours

Arguments

key

country_code

start_date

start_time

increment_time

configuration

weekend

week_hours

week_times

start_template

use_custom_configuration

profile_id

Alternating weeks

The weekend parameter

The start_template parameter

The week_times parameter

Get day information

Endpoint /get_info_day

Arguments

key

country_code

date

configuration

weekend

use_custom_configuration

profile_id

List non working days

Endpoint /list_non_working_days

Arguments

key

country_code

start_date

end_date

configuration

weekend

use_custom_configuration