Pen and paper — the basis of good design

REST APIs and SDK

Integrate Calidario in your service

Integrate Calidario into your own services: with our data API, calendar API and SDK for PHP, you can leverage our strengths in your applications.

Would you prefer to use calendar data through an AI assistant? Get to know the Calidario MCP server.

The Calidario Data API

With the Calidario Data API, all the calendar information you need for your products is at your disposal – bundled in a single place, continuously updated and carefully reviewed.

Everything that makes up a calendar

The Data API bundles thirteen categories of data: from public holidays and school holidays via countries, cities and languages to moon phases, name days and zodiac signs. Instead of many individual sources, a single point of contact is sufficient.

Calidario already delivers many labels translated into the languages of the world. Public holidays and vacation dates are additionally supplied with a source reference and a date of the latest update – so you always know what you are relying on.

The API has been in use in Calidario’s calendar configurator for years and is also available to third parties. It is suitable for online applications as well as for offline and print products.

Quick and easy to integrate

Access is provided via a classic REST API. With a token, you have access to all data and can filter it exactly as you need – for example by country, language or year.

You can find the complete technical documentation including all endpoints at api.calidar.io.

Request prices and token now

Comprehensive

All relevant calendar information in one place – for any application and every product.

Always up to date and verified

The data is continuously updated and validated and delivered with a source reference.

Multilingual

Labels in the languages of the world – for international applications and interfaces.

Data for your application

You can retrieve the following with the Data API:

Holidays

The public holidays of all countries with translated names, the federal states or regions concerned and valid substitution rules. The specific calendar data is supplied for every year – in the calendar system used: Western (Gregorian), Orthodox and Julian with their own Easter Sunday, Islamic, Jewish and Chinese.

School holidays

School holidays including their name, start and end as well as the responsible federal state or region – ideal for travel, education and planning products.

Countries

Everything worth knowing about every country in the world: capital, currency, population, languages spoken, continent and geographical location.

Country names

All country names translated into the languages of the world – for multilingual applications and interfaces.

Cities

Cities with postal code, region and geographical coordinates – filtered by country.

Languages

All languages with their language code and the country’s typical calendar system.

Days

The names of the days of the week in almost all languages of the world.

Months

The names of the months in almost all languages of the world.

Moon phases

The names of the moon phases in various languages.

Name days

The name days of all European countries – retrievable by date or by name.

Zodiac signs

The names of the signs of the zodiac in different languages.

Federal states and regions

The federal states and regions of various countries – for regional assignments.

Calendar systems

Sorted by country: the country’s typical calendar system, the start of the year and the year numbering.

Everything else – endpoints, parameters and technical details – you can find in the Data API documentation.

The Calidario Calendar API

Calidario’s calendar API allows the generation of all kinds of calendars.

Generate complete calendars automatically

Our calendar interface enables the fully automated generation of calendar layouts. All relevant data formats are supported, including:

  • Web and print PDF,
  • IDML for Adobe InDesign, QuarkXPress and Affinity,
  • HTML and CSS,
  • JPEG, PNG etc.

The open data allows post-processing of all information and design elements.

Individual calendars with your own corporate design, your own logo, your own images, etc. are possible.

Access is via REST API.

Address and access

The Calendar API can be called at calendar-api.calidar.io. A token is required for queries.

Request prices and token now

The Calidario SDK for PHP

The Calidario SDK processes calendar data in PHP projects. It combines the Calidario Data API with an extensive calculation engine that produces many calendar values itself – without any additional API request.

Data from the Calidario Data API

The SDK retrieves this data via the Calidario Data API. You need a token for this.

  • The public holidays of all countries with translated names, with the federal states and regions concerned, and with valid substitution rules.
  • Substituted public holidays can be identified as such and reported either on the substituted date, on the original date, or on both.
  • Individual observation dates per public holiday and year, including dates from another year.
  • It can be checked whether a certain day includes a public holiday. The distinction between national holidays and partial holidays is possible.
  • The school holidays of a certain country can be queried.
  • Name days can be queried by day or by name.
  • Federal states/regions can be queried for a specific country.
  • Day names can be requested for a specific language.
  • Month names can be queried for a specific language.
  • Moon phases can be queried and output in different languages.
  • Moon phases can also be output for part of a day when the phase changes in the middle of that day.

Computed without a token

These values are computed entirely on your own server. They require neither a token nor network access.

  • The Easter date for the Western and Eastern Churches can be calculated for a specific year.
  • Sunrise and sunset can be computed for any geographical position – including locations where the sun does not rise or set at all.
  • The beginning of spring and autumn with the exact moment.
  • The zodiac sign of the sun – computed astronomically or according to the traditional fixed date ranges.
  • The zodiac sign of the moon, along with the exact moment the sign changes.
  • Whether the moon stands higher or lower from one day to the next – ascending or descending.
  • The twelve Chinese zodiac animals and the Gan-Zhi year.
  • Conversion between the Gregorian calendar, the Hijri calendar and the Julian day number.
  • The Islamic new year and the Jewish new year Rosh Hashana.
  • The week number on a specific date can be calculated.
  • The number of a day in a week can be calculated.
  • The first and last day and the total number of days in a given month can be calculated.

Installation and activation

The Calidario SDK is available as a PHP library and can be integrated via Composer. It is a private library that requires a token.

To do so, the Calidario Private Packagist repository is added to the project configuration. Afterwards, the command composer require calidario/framework is all you need.

Technical requirements

The library requires PHP >= 8.2 as well as the calendar extension (ext-calendar), the JSON extension (ext-json) and the multibyte string extension (ext-mbstring).

For communication, the SDK relies on PSR-18 and PSR-17. You can plug in your own HTTP client, and responses can be cached for a freely chosen time in seconds. The token is sent as a bearer token in the Authorization header and is therefore not part of the URL.

Request prices and token now

Astronomical values in print quality

Moon calendars do not tolerate half measures. That is why the SDK computes the astronomical values following the established methods of the astronomical handbooks – and makes the sources traceable.

Exact change times

The exact moment at which the moon enters or leaves a zodiac sign is determined to within one to two minutes – including on days when the moon changes sign twice.

Three zodiac systems to choose from

You decide whether to use the tropical zodiac sign, the thirteen real constellations including Ophiuchus, or a comparison model with twelve constellation regions. All boundaries are corrected for the precession of the Earth’s axis and remain valid far from the reference year 2000.

The day rule of printed moon calendars

Many moon calendars list in the cell for each day the constellation the moon enters on that day. The SDK provides this day rule, and optionally the exact hour of the change, directly.

Tested and documented

The calculation follows Jean Meeus and his standard work »Astronomical Algorithms«. At twenty reference points between 2011 and 2029, the moon’s declination deviates from the JPL Horizons reference ephemeris by at most 0.007°; Meeus’s example is matched exactly.

Ask

Are you interested in the Calidario API or the Calidario SDK? Write us!