Browse documentation

Reference / Date & Time

Date & Time API

25 endpoints for date & time workflows. Every call requires bearer authentication and uses the standard ToolsOnDuty response envelope.

Try it

Runs a real request from your browser to your own ToolsOnDuty account. Your key is only kept in this page and is never stored.

EndpointAPI key

dateOfBirth *asOf

POST/v1/datetime/age1 credit / call

Age calculator

Exact calendar age and next-birthday countdown between a date of birth and a reference date.

Parameter	Type	Required	Description
dateOfBirth	string	Yes	Date of birth, YYYY-MM-DD.
asOf	string	No	Reference date, YYYY-MM-DD. Defaults to today (UTC).

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/age \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"dateOfBirth":"1990-05-15","asOf":"2026-01-01"}'

Response

{
  "ok": true,
  "data": {
    "years": 35,
    "months": 7,
    "days": 17
  }
}

POST/v1/datetime/difference1 credit / call

Date difference

Elapsed years, months and days between two dates (exclusive or inclusive of the end date).

Parameter	Type	Required	Description
startDate	string	Yes	Start date, YYYY-MM-DD.
endDate	string	Yes	End date, YYYY-MM-DD.
mode	string	No	exclusive \| inclusive. Default: exclusive.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/difference \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"startDate":"2020-01-01","endDate":"2026-06-15"}'

Response

{
  "ok": true,
  "data": {
    "years": 6,
    "months": 5,
    "days": 14
  }
}

POST/v1/datetime/offset1 credit / call

Add or subtract calendar time

Add or subtract days, weeks, months or years from a date.

Parameter	Type	Required	Description
date	string	Yes	Start date, YYYY-MM-DD.
operation	string	Yes	add \| subtract.
amount	number	Yes	Non-negative whole number amount.
unit	string	Yes	days \| weeks \| months \| years.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/offset \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-01-01","operation":"add","amount":90,"unit":"days"}'

Response

{
  "ok": true,
  "data": {
    "date": {
      "year": 2026,
      "month": 4,
      "day": 1
    }
  }
}

POST/v1/datetime/weekday1 credit / call

Day of the week

Return the Gregorian weekday name and index (0=Sunday) for a date.

Parameter	Type	Required	Description
date	string	Yes	Date, YYYY-MM-DD.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/weekday \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-01-01"}'

Response

{
  "ok": true,
  "data": {
    "dayName": "Thursday",
    "dayIndex": 4
  }
}

POST/v1/datetime/iso-week1 credit / call

ISO week number

ISO-8601 week number, week-year and the start/end dates of that week.

Parameter	Type	Required	Description
date	string	Yes	Date, YYYY-MM-DD.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/iso-week \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-01-01"}'

Response

{
  "ok": true,
  "data": {
    "weekNumber": 1,
    "weekYear": 2026
  }
}

POST/v1/datetime/calendar-month1 credit / call

Monthly calendar grid

A Monday-first calendar grid and metadata for a given year and month.

Parameter	Type	Required	Description
year	number	Yes	Calendar year.
month	number	Yes	Month (1-12).

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/calendar-month \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":1}'

Response

{
  "ok": true,
  "data": {
    "numberOfDays": 31,
    "firstWeekday": "Thursday"
  }
}

POST/v1/datetime/calendar-year2 credits / call

Yearly calendar grid

A full 12-month calendar grid and leap-year metadata for a given year.

Parameter	Type	Required	Description
year	number	Yes	Calendar year.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/calendar-year \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"year":2026}'

Response

{
  "ok": true,
  "data": {
    "isLeapYear": false,
    "numberOfDays": 365
  }
}

POST/v1/datetime/day-of-year1 credit / call

Day of the year

Ordinal day number within the year, days remaining and percent elapsed.

Parameter	Type	Required	Description
date	string	Yes	Date, YYYY-MM-DD.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/day-of-year \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-04-10"}'

Response

{
  "ok": true,
  "data": {
    "dayOfYear": 100,
    "daysRemaining": 265
  }
}

POST/v1/datetime/day-count1 credit / call

Day count between dates

Count calendar days between two dates, exclusive or inclusive of the end date.

Parameter	Type	Required	Description
startDate	string	Yes	Start date, YYYY-MM-DD.
endDate	string	Yes	End date, YYYY-MM-DD.
mode	string	No	exclusive \| inclusive. Default: exclusive.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/day-count \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"startDate":"2026-01-01","endDate":"2026-12-31"}'

Response

{
  "ok": true,
  "data": {
    "totalDays": 364,
    "mode": "exclusive"
  }
}

POST/v1/datetime/countdown1 credit / call

Countdown timer

Break the gap between two Unix millisecond timestamps into days, hours, minutes and seconds.

Parameter	Type	Required	Description
fromMs	number	Yes	Start instant, Unix milliseconds.
toMs	number	Yes	Target instant, Unix milliseconds.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/countdown \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"fromMs":0,"toMs":90061000}'

Response

{
  "ok": true,
  "data": {
    "days": 1,
    "hours": 1,
    "minutes": 1,
    "seconds": 1
  }
}

POST/v1/datetime/quarter1 credit / call

Calendar and fiscal quarter

Calendar quarter and, given a fiscal-year start month, the fiscal quarter for a date.

Parameter	Type	Required	Description
date	string	Yes	Date, YYYY-MM-DD.
fiscalStartMonth	number	No	Fiscal year start month (1-12). Default: 1.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/quarter \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-04-15"}'

Response

{
  "ok": true,
  "data": {
    "calendarQuarter": 2,
    "calendarQuarterLabel": "Q2"
  }
}

POST/v1/datetime/zodiac1 credit / call

Western zodiac sign

The western (tropical) zodiac sign for a month and day.

Parameter	Type	Required	Description
month	number	Yes	Month (1-12).
day	number	Yes	Day of month (1-31).

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/zodiac \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"month":8,"day":23}'

Response

{
  "ok": true,
  "data": {
    "name": "Virgo",
    "symbol": "♍",
    "element": "Earth"
  }
}

POST/v1/datetime/chinese-zodiac1 credit / call

Chinese zodiac

Chinese zodiac animal, element and yin/yang for a year.

Parameter	Type	Required	Description
year	number	Yes	Year.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/chinese-zodiac \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"year":2026}'

Response

{
  "ok": true,
  "data": {
    "animal": "Horse",
    "element": "Fire",
    "yinYang": "Yang"
  }
}

POST/v1/datetime/moon-phase1 credit / call

Moon phase

Approximate moon phase, illumination and moon age (in days) for a date.

Parameter	Type	Required	Description
date	string	Yes	Date, YYYY-MM-DD.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/moon-phase \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-01-01"}'

Response

{
  "ok": true,
  "data": {
    "phaseName": "Waxing Gibbous",
    "illumination": 0.82
  }
}

POST/v1/datetime/calendar-invite1 credit / call

Calendar (.ics) invite builder

Build a standards-compliant iCalendar (.ics) meeting invite, with optional reminder, recurrence and attendees.

Parameter	Type	Required	Description
title	string	Yes	Event title.
date	string	Yes	Event date, YYYY-MM-DD, in the given time zone.
time	string	Yes	Event start time, HH:mm, in the given time zone.
durationMinutes	number	Yes	Duration in minutes.
timeZone	string	Yes	IANA time zone, e.g. America/New_York.
location	string	No	Event location.
meetingUrl	string	No	Video call URL.
description	string	No	Event description.
organizerEmail	string	No	Organizer email address.
attendees	string	No	Array of attendee email addresses.
reminderMinutes	number	No	Minutes before start to remind. Omit for no reminder.
recurrence	string	No	none \| daily \| weekdays \| weekly \| monthly \| yearly. Default: none.
recurrenceCount	number	No	Number of occurrences. Omit to repeat forever.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/calendar-invite \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"title":"Team sync","date":"2026-01-05","time":"09:00","durationMinutes":30,"timeZone":"America/New_York"}'

Response

{
  "ok": true,
  "data": {
    "result": "BEGIN:VCALENDAR..."
  }
}

POST/v1/datetime/world-clock1 credit / call

World clock

Current wall-clock time, UTC offset and day/night for any IANA time zone.

Parameter	Type	Required	Description
timeZone	string	Yes	IANA time zone, e.g. Asia/Tokyo.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/world-clock \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"timeZone":"Asia/Tokyo"}'

Response

{
  "ok": true,
  "data": {
    "time24": "09:00:00",
    "offsetLabel": "GMT+9"
  }
}

POST/v1/datetime/sunrise-sunset1 credit / call

Sunrise, sunset and solar noon

Approximate sunrise, sunset, solar noon and day length for a date and location (UTC instants).

Parameter	Type	Required	Description
date	string	Yes	Date, YYYY-MM-DD.
latitude	number	Yes	Latitude, -90 to 90.
longitude	number	Yes	Longitude, -180 to 180.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/sunrise-sunset \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-06-21","latitude":51.5,"longitude":-0.13}'

Response

{
  "ok": true,
  "data": {
    "dayLengthMinutes": 973
  }
}

POST/v1/datetime/dst1 credit / call

Daylight saving transitions

Find daylight-saving clock-change dates for an IANA time zone in a given year.

Parameter	Type	Required	Description
timeZone	string	Yes	IANA time zone, e.g. America/New_York.
year	number	Yes	Year.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/dst \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"timeZone":"America/New_York","year":2026}'

Response

{
  "ok": true,
  "data": {
    "observesDst": true,
    "transitions": []
  }
}

POST/v1/datetime/time-in-words1 credit / call

Time in words

Spell a 24-hour clock time as a natural English phrase, e.g. "quarter past nine".

Parameter	Type	Required	Description
hour	number	Yes	Hour, 0-23.
minute	number	No	Minute, 0-59. Default: 0.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/time-in-words \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"hour":9,"minute":15}'

Response

{
  "ok": true,
  "data": {
    "result": "quarter past nine"
  }
}

POST/v1/datetime/relative-time1 credit / call

Relative time formatter

Format the largest meaningful difference between a target date and comparison date.

Parameter	Type	Required	Description
date	string	Yes	Target ISO date or date-time.
now	string	No	Comparison ISO date or date-time. Defaults to the current time.
locale	string	No	BCP 47 locale. Default: en.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/relative-time \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-01-02T00:00:00Z","now":"2026-01-01T00:00:00Z"}'

Response

{
  "ok": true,
  "data": {
    "value": 1,
    "unit": "day",
    "formatted": "tomorrow"
  }
}

POST/v1/datetime/julian-day1 credit / call

Julian Day calculator

Convert an ISO date-time to Julian Day and Modified Julian Day.

Parameter	Type	Required	Description
date	string	Yes	ISO-compatible date or date-time.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/julian-day \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2000-01-01T12:00:00Z"}'

Response

{
  "ok": true,
  "data": {
    "julianDay": 2451545,
    "modifiedJulianDay": 51544.5
  }
}

POST/v1/datetime/mayan-calendar1 credit / call

Mayan calendar converter

Convert a Gregorian date to Long Count, Tzolk'in and Haab values using the GMT correlation.

Parameter	Type	Required	Description
date	string	Yes	Gregorian ISO date.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/mayan-calendar \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"date":"2012-12-21"}'

Response

{
  "ok": true,
  "data": {
    "longCount": "13.0.0.0.0"
  }
}

POST/v1/datetime/daylight-duration1 credit / call

Daylight duration calculator

Estimate daylight duration from latitude and date using solar declination.

Parameter	Type	Required	Description
latitude	number	Yes	Latitude from -90 to 90.
date	string	Yes	ISO date.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/daylight-duration \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"latitude":28.6139,"date":"2026-10-01"}'

Response

{
  "ok": true,
  "data": {
    "daylightHours": 11.9,
    "formatted": "11h 54m"
  }
}

POST/v1/datetime/weather-season1 credit / call

Weather season calculator

Return the meteorological season for a month and hemisphere.

Parameter	Type	Required	Description
month	number	Yes	Month from 1 to 12.
hemisphere	string	No	northern \| southern. Default: northern.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/weather-season \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"month":7,"hemisphere":"northern"}'

Response

{
  "ok": true,
  "data": {
    "meteorologicalSeason": "summer"
  }
}

POST/v1/datetime/business-days1 credit / call

Business days calculator

Count working days between dates or add/subtract working days with configurable weekends and holidays.

Parameter	Type	Required	Description
startDate	string	Yes	Start date, YYYY-MM-DD.
endDate	string	No	End date for count mode.
amount	number	No	Working days for offset mode.
direction	string	No	add \| subtract. Default: add.
weekendDays	string	No	Comma-separated weekday indexes (0=Sunday). Default: 0,6.
holidays	string	No	Comma-separated YYYY-MM-DD dates.

Request

curl -X POST https://toolsonduty.com/api/v1/datetime/business-days \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"startDate":"2026-01-01","endDate":"2026-01-31"}'

Response

{
  "ok": true,
  "data": {
    "mode": "count",
    "businessDays": 22
  }
}