DOCUMENTATION API TEST TOOL SUPPORTED COUNTRIES GET YOUR KEY
Our HTTP JSON API exposes 3 kind of services you can plug to:
- Analyse a period. You provide a start date and a end date, we respond with the number of days, working days, weekend days, public holidays and their ventilation.
- Add any number of working days/weekend days/public holidays 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 currently cover 39 countries and more than 200 regional calendars and it is possible to take into account your custom dates.

On this page we are going to look at the arguments, some sample HTTP requests and JSON replies, and some PHP sample code (JSON libraries are available in all languages).

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. Ask for a key.
Last limitation you will have: the period you want to analyze must not exceed 1600 days in order not to overload our servers and be within the years 1970 to 2037.

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

Finally, if you appreciate this service, provided without charge, don't forget to credit it on your web site.

1- Analyse a period

Arguments

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

configuration (Optional)

The name of the regional preset configuration. See the list
Each contry 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 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.
See the list of countries.

command (Required)

The name of the service you want to call. Here value is 'analyse'.

start_date (Required)

The start date (YYYY-MM-DD)

end_date (Required)

The end date (YYYY-MM-DD)

weekend (Optional)

Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday.
Default value is 1000001 (weekend days on saturday, sunday).
If the weekend for you is sunday and monday, you can send : 1100000

use_custom_configuration (Optional)

Take into account your own personal configuration.
Send 1 for true. Default value is false.
See this example.

Sample request / response

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 :

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


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 :

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

Sample PHP client code

2- Add working days to a date

Arguments

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

configuration (Optional)

The name of the regional preset configuration. See the list
Each contry 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 in that case this parameter is not necessary and will be ignored.
See the list of countries.

command (Required)

The name of the service you want to call. Here value is 'add_working_days'.

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)

weekend (Optional)

Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday.
Default value is 1000001 (weekend days on saturday, sunday).
If the weekend for you is sunday and monday, you can send : 1100000

use_custom_configuration (Optional)

Take into account your own personal configuration.
Send 1 for true. Default value is false.
See this example.

Sample request / response

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 :

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

Sample PHP client code

3- Add public holiday days to a date

Just change the command to 'add_public_holidays' . The same logic remain unchanged (see add working days just above).

4- Add weekend days to a date

Just change the command to 'add_weekend_days' . The same logic remain unchanged (see add working days just above).

5 - Using custom configuration

If you use this parameter (use_custom_configuration=1) then the configuration used is the one you defined when you are connected into the corresponding working days web site (using the same email).
When you use this paramater the parameters configuration and weekend are simply ignored as the configuration applied is the one of your personal account.
You can thus build your own custom calendar and integrate with your website using the API.
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 used in the API

2. From the setupscreen, choose the public holidays where the shop is closed, and define the weekend.

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 :

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

6- List non working days

This command let you list the non working days (weekend days, public holidays and custom dates) between 2 dates.

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

configuration (Optional)

The name of the regional preset configuration. See the list
Each contry 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 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.
See the list of countries.

command (Required)

The name of the service you want to call. Here value is 'list_non_working_days'.

start_date (Required)

The start date (YYYY-MM-DD)

end_date (Required)

The end date (YYYY-MM-DD)

weekend (Optional)

Your weekend structure. Sunday-Monday-Tuesday-Wednesday-Thursday-Friday-Saturday.
Default value is 1000001 (weekend days on saturday, sunday).
If the weekend for you is sunday and monday, you can send : 1100000

use_custom_configuration (Optional)

Take into account your own personal configuration.
Send 1 for true. Default value is false.
The api does not take into account half day custom dates definition.
See this example.

Sample request / response

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 :

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

Now let's go for some sample code.
Our flower shop of the previous example need to build a custom date picker so its customers can 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 a in a confortable way within the 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):


And here is the result, with those 3 dates 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 :



<?php
  
$key
="FloShop@gmail.com";
$country_code="FR";
$url="http://api.workingdays.org/1.1/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',";
        }
    
}
        
  
?>

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