• 📅 Libera.Date.Api Documentation

  🚀 Why Choose Libera.Date.Api?

  Time is money, but calculating it correctly is harder than it looks. Libera.Date.Api is the ultimate solution for developers building HR systems, logistics platforms, and financial applications.

  Stop wrestling with leap years, timezone anomalies, and shifting public holidays. Powered by the industry-standard NodaTime engine and our proprietary Working Days System, this API delivers:

  • Global Awareness: Built-in support for major economies (US, UK, DE, PL, FR) with accurate holiday calendars.
  • Business Logic Ready: Instantly calculate SLAs and delivery dates by excluding weekends and holidays.
  • Precision Engineering: Get exact durations down to the minute, or broad calendar period differences (Years/Months/Days).
  • Smart Fallbacks: Automatically find the next available working day when deadlines hit a holiday.

PL Jeśli jesteś zainteresowany(a) użyciem API, skontaktuj się proszę przez formularz kontaktowy: https://wroclawprogramowanie/contact-form/

EN If you’re interested in using the API, please contact us via the contact form: https://wroclawprogramowanie/contact-form/

🔐 Authentication

All requests must be authenticated. You can use either an API Key or a Bearer Token.

📡 Endpoints Overview

Base URL: http://localhost:8080 (adjust to your deployment)

1. Date Calculator

🔹 Calculate Period Between Dates

Calculates the calendar difference (Years, Months, Days).

• URL: /date-calculator/period/date
• Method: GET
• Parameters:
  • Start (query, required): Start date (ISO 8601, e.g., 2024-01-01)
  • End (query, required): End date (ISO 8601, e.g., 2025-03-15)

Request:

curl -X GET "http://localhost:8080/date-calculator/period/date?Start=2024-01-01&End=2025-03-15" \
     -H "X-Secret: TEST_SECRET"

Response (200 OK):

{
  "years": 1,
  "months": 2,
  "days": 14,
  "description": "1 year, 2 months, 14 days"
}

🔹 Calculate Time Duration

Calculates the duration in total days, hours, and minutes.

• URL: /date-calculator/period/time

• Method: GET

• Parameters:

  • Start (query): 2024-01-01T12:00:00

  • End (query): 2024-01-05T18:30:00

Request:

curl -X GET "<http://localhost:8080/date-calculator/period/time?Start=2024-01-01T12:00:00&End=2024-01-05T18:30:00>" \
     -H "X-Secret: TEST_SECRET"

Response (200 OK):

{
  "totalDays": 4,
  "hours": 102,
  "minutes": 6150
}

2. Working Days & Holidays

Advanced logic for business days, weekends, and public holidays.

Path Parameter: {countryCode} (e.g., PL, US, DE, UK).

🔹 Check Working Day & Find Nearest

Checks if a specific date is a working day. If it is not (due to weekend or holiday), it returns the date of the next immediate working day.

• URL: GET /workingdays/{countryCode}/is-working-day
• Parameters:
  • Date (required, YYYY-MM-DD)

Example Request (Checking Christmas Day in US):

bash
curl -X GET "http://localhost:8080/workingdays/US/is-working-day?Date=2025-12-25"

Response (200 OK):

json{
  "date": "2025-12-25T00:00:00",
  "isWorkingDay": false,
  "nearestWorkingDay": "2025-12-26T00:00:00" 
}

🔹 Get Detailed Non-Working Info

Returns detailed metadata about why a day is not a working day. It distinguishes between weekends (specifying if it’s the 1st or 2nd day of the weekend) and public holidays.

• URL: GET /workingdays/{countryCode}/non-working-info
• Parameters:
  • Date (required, YYYY-MM-DD)

Example Request:

bash
curl -X GET "http://localhost:8080/workingdays/PL/non-working-info?Date=2024-05-01"

Response (200 OK):

json{
  "date": "2024-05-01T00:00:00",
  "isNonWorkingDay": true,
  "type": "holiday",
  "weekendDayNumber": null,
  "holiday": {
    "englishName": "Labor Day",
    "localName": "Święto Pracy"
  }
}

🔹 Analyze Range (Working vs. Non-Working)

Generates a comprehensive breakdown of a date range, splitting all dates into “Working” and “Non-Working” lists. Ideal for rendering calendars or Gantt charts.

• URL: GET /workingdays/{countryCode}/range
• Parameters:
  • Start (required): Range start.
  • End (required): Range end.
  • Note: Max range is limited by server configuration (default 366 days).

Example Request:

bash
curl -X GET "http://localhost:8080/workingdays/US/range?Start=2024-07-03&End=2024-07-05"

Response (200 OK):

json{
  "start": "2024-07-03T00:00:00",
  "end": "2024-07-05T00:00:00",
  "workingDays": [
    { "date": "2024-07-03T00:00:00" },
    { "date": "2024-07-05T00:00:00" }
  ],
  "nonWorkingDays": [
    {
      "date": "2024-07-04T00:00:00",
      "type": "holiday",
      "englishName": "Independence Day",
      "localName": "Independence Day"
    }
  ]
}

🔹 Count Working Days

Calculates the number of business days between two dates. (excluding weekends and holidays).

• URL: /workingdays/{countryCode}/count

• Method: GET

• Parameters:

  • Start (query): 2024-05-01

  • End (query): 2024-05-10

Request:

curl -X GET "<http://localhost:8080/workingdays/PL/count?Start=2024-05-01&End=2024-05-10>" \
     -H "X-Secret: TEST_SECRET"

Response (200 OK):

{
  "totalDays": 366,
  "workingDays": 253
}

🔹 Get Off-Days Count

Returns the count of non-working days (weekends + holidays).

• URL: /workingdays/{countryCode}/off-days

• Method: GET

Request:

curl -X GET "<http://localhost:8080/workingdays/PL/off-days?Start=2024-05-01&End=2024-05-10>" \
     -H "X-Secret: TEST_SECRET"

Response (200 OK):

{
  "totalDays": 366,
  "offDays": 113
}

🔹 List Public Holidays

Returns a list of public holidays in the given range.

• URL: /workingdays/{countryCode}/holidays

• Method: GET

Request:

curl -X GET "<http://localhost:8080/workingdays/PL/holidays?Start=2024-01-01&End=2024-01-10>" \
     -H "X-Secret: TEST_SECRET"

Response (200 OK):

[
  {
    "date": "2024-01-01",
    "name": "New Year's Day",
    "localName": "Nowy Rok"
  },
  {
    "date": "2024-01-06",
    "name": "Epiphany",
    "localName": "Święto Trzech Króli"
  }
]

🔹 Get Weekends Count

Returns the number of weekend days (Saturdays and Sundays).

• URL: /workingdays/{countryCode}/weekends

• Method: GET

Request:

curl -X GET "<http://localhost:8080/workingdays/PL/weekends?Start=2024-05-01&End=2024-05-10>" \
     -H "X-Secret: TEST_SECRET"

Response (200 OK):

{
  "totalDays": 91,
  "weekendDaysCount": 26
}

Supported countries