Ukraine.workingdays.org API documentation for Developers

Our HTTP JSON API exposes 2 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.

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 (typically your email). To get your key, please contact me (with email's object "API access to Ukraine.workingdays.org") and send me your public IP so I can authorize it to access the service (one or several IP corresponding to one or several client servers, but yes, you need a static IP to access the API, typically you should be accessing the service from your web server).
Don't forget to drop me a few lines explaining your use case, and how many queries per days you are planning to send. 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.
Finally, if you appreciate this service, provided without charge, don't forget to credit it on your web site or make a one-off donation (there is a paypal button on the contact page for that).

1- Analyse a period

Arguments

key (Required)

Your personal API key

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)

holidays (Optional)

That is the list of public holidays the service should consider not working days as listed in the setup screen
If you don't provide this parameter, default value will be used: 1111111111

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

Sample request / response

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

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


Suppose now we want to analyse the period from 1st january 2013 to 31th december 2013, but we don't want to take into account the first public holiday (New Year's Day) 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

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)

holidays (Optional)

That is the list of public holidays the service should consider not working days as listed in the setup screen
Default value is 1111111111

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

Sample request / response

Suppose we want to add 53 working days to the 1st january 2013, 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).
comments powered by Disqus