Working Days 
API 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 morning*Sunday afternoon*Monday morning*Monday afternoon*Tuesday morning*Tuesday afternoon*Wednesday morning*Wednesday afternoon*Thursday morning*Thursday afternoon*Friday morning*Friday afternoon*Saturday morning*Saturday afternoon.
    Default value is 0*0*4*4*4*4*4*4*4*4*4*4*0*0* (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 start*Sunday morning end*Sunday afternoon start*Sunday afternoon end*Monday morning start*Monday morning end*Monday afternoon start*Monday afternoon end*....*Saturday morning start*Saturday morning end*Saturday afternoon start*Saturday afternoon end*
    Defaut value is :
    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*18: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 be1:


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



    Example PHP client code

    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 start*Sunday morning end*Sunday afternoon start*Sunday afternoon end*Monday morning start*Monday morning end*Monday afternoon start*Monday afternoon end*....*Saturday morning start*Saturday morning end*Saturday afternoon start*Saturday afternoon end*
    Defaut value is :
    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*18: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:


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



    Example PHP client code



    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.
  • The four layers of 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 ; 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 :



    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


    you will get 275.5 working days.

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


    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.



    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:



    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 morning*Sunday afternoon*Monday morning*Monday afternoon*Tuesday morning*Tuesday afternoon*Wednesday morning*Wednesday afternoon*Thursday morning*Thursday afternoon*Friday morning*Friday afternoon*Saturday morning*Saturday afternoon.
    Default value is 0*0*4*4*4*4*4*4*4*4*4*4*0*0* (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 start*Sunday morning end*Sunday afternoon start*Sunday afternoon end*Monday morning start*Monday morning end*Monday afternoon start*Monday afternoon end*....*Saturday morning start*Saturday morning end*Saturday afternoon start*Saturday afternoon end*
    Defaut value is :
    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*18: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:


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



    Example PHP client code



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

    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:
    And here is an example JSON response of this service:



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

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

  • : the number of working hours in this day (a float between 0 and 24)

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

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

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

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

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

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

  • : in case that day is a public holiday, you will get it's name here. For example "New year's 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

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

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

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

    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:



    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)

    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:



    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:

    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


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