Working Days 
API for Developers 
v1.2


Introduction

Our HTTP JSON API 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, weekend days, the list of the public holidays over the period.
  • Add any number of working days / 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 currently cover 40 countries and more than 230 regional calendars and it is possible to take into account your custom dates.

    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 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 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).



    Analyse a 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

    command

    Required
    The name of the service you want to call. analyse

    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.
    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.

    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/api.php?key=MYPERSONALKEY&country_code=CA&command=analyse&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):



    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/api.php?key=MYPERSONALKEY&command=analyse&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:



    Example PHP client code

    Add working days to a date

    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

    command

    Required
    The name of the service you want to call. 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)

    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.
    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.

    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/api.php?key=MYPERSONALKEY&country_code=FR&command=add_working_days&start_date=2013-01-01&increment=90

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



    Example PHP client code

    Add public holidays to a date

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

    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).

    Using custom configuration

    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).
    You can thus completely customize your calendar (choose your public holidays one by one, add extra custom dates, etc.). When you add use_custom_configuration=1, the parameters configuration and weekend are simply ignored as the configuration applied is the one of your personal account (your custom dates are taken into account).


    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 :


    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

    List non working days

    This command let you 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

    command

    Required
    The name of the service you want to call. Here list_non_working_days

    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.
    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.

    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/api.php?key=MYPERSONALKEY&country_code=CA&command=list_non_working_days&start_date=2013-01-01&end_date=2013-12-31


    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 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):



    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 :



    <?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',";
            }
        
    }
            
      
    ?>

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

    Know your quota

    Each query 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.
    This service will return the state of your plan (1:active, 2:cancelled, -1:error), your current quota (days left to be analysed within this month) and the quota that will be available next month (each new month starts the first day of the month at 00:01 local time GMT+1 Paris).

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

    Arguments

    Name Description

    key

    Required
    Your personal API key

    command

    Required
    The name of the service you want to call. quota


    The URL

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


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

    Securing your code

    Before you go live, you want to make sure your code is robust.
    Handling exception properly is a key element in order to achieve that.

    First, 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 might want to implement an alert for yourself.
    In any other case, you might want to implement one or several retries because networks failures happen.

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

    PHP example