Version 3 of API Services Released

Wednesday, November 13, 2019
The latest version of our API Services enables you to get more out of our API with less effort, and it includes many features and improvements requested by our customers.
Illustration image

Features and Improvements

Version 3 allows you to get more data using fewer requests instead of making multiple requests for a variety of data. Instead of specifying a single object or parameter, you can now specify multiple parameter values and get a larger return set with a single request.

You can keep track of the cost of your queries via the “billing” element of the returning result.

Existing customers with a valid license already have access to the new and improved features described below.

Holidays API

Version 3 of our Holidays API Services includes these new features:

  • Multiple countries per query: Get holiday data for all countries in one go instead of having to make separate queries for each country.
  • Multiple languages per query: Get holiday names and oneliners in different languages using only one query instead of having to make multiple queries.
  • Fun Holidays Database: Our Fun Holidays database is now also available through our API. To query, simply specify country=fun when requesting data from the Holidays API. The "types" parameter will automatically be set to types=fun in the service, so this field can be omitted.
Improved Feature: Added Holiday Types

You will now have more granular control of the holiday types you wish to receive. We have added five new types of holidays:

  • defacto – days that aren't official holidays but are traditionally treated as such by businesses, offices, and the general population
  • halfday – these usually start as regular working days but the second half of the day is off for workers (e.g., the day before Maundy Thursday in Norway)
  • optional – in some countries, employees can choose a limited number of optional holidays per year as non-working days (these are often religious festivities)
  • otherreligion – religious holidays not categorized under one of the major world religions
  • sport – sporting events

Astronomy API

This iteration of the Astronomy API offers more precision in querying for astronomical calculations by allowing you to query not only for dates but also for specific times. New features include:

  • Moon Orientation: Query the current orientation of the Moon. This element, called posangle, provides the angle of the line connecting the geometric center of the Moon's disk to the midpoint of the illuminated lunar limb, measured counter-clockwise from the top.
  • Astrodata: The astrodata service lets you query at an even more granular level. Instead of querying for a specific date or a range of dates, you can now specify up to 50 different ISO 8601 timestamps in a single query, specify multiple objects at the same time (e.g., calculate for both the Sun and the Moon), and make a calculation for all timestamps, at all locations, and for all objects in one go.
Improved Feature: Increased Precision

The timestamp for all featured events now also includes seconds, in addition to hours and minutes.

Business Date and Business Days API

For these two API Services, which allow you to calculate the number of business days between two dates (or simply the number of days), we have added one of the same new features as for the Holidays API Service:

  • Multiple languages per query: Receive holiday names and oneliners in the different languages we have available in our database.

Signature Calculator

We strongly advise our customers to use HMAC-based authentication when querying our API Services. While we do offer alternative methods for authentication, this one is by far the most secure. Find out how to create an HMAC-based signature in the chapter on authentication in the API Service documentation.

We have now created an interactive API Signature Calculator that describes and visualizes the process of creating a signature, making it easier for you as a developer to create this for your programming language.

Why a new version number?

We strive to ensure 100% backward compatibility when launching new features in our APIs. This means that we may introduce new features in existing versions of our API, as long as their implementation does not change the current format and functions. As our customer, you can be sure that requests that worked yesterday will continue to work today and tomorrow.

When increasing the version number, we allow for potentially breaking changes to backward compatibility of both the request parameters and the response format. Requests that returned one kind of format in version 2 may return another type of format in version 3. A good example of this are the names of holidays in different languages. Previously, when querying for holidays in a specific language, you would receive a single result showing the name of the holiday in that specific language; now, that same field can include an array of multiple translations of that holiday name.

Get Started Now!

If you are not already a Time and Date API customer, you can start via our Getting Started Page!

If you already are a Time and Date API customer, all of these features are already available in the services for which you have a license!

You can start testing the new features and improvements in our APIs in the Query Builder.

Related Links

Terms & Conditions Copyright © Time and Date AS
All data supplied by