Get started

API Endpoint

https://api.date-calculator.org/

The Date Calculator API is based on REST, uses standard HTTP protocol, and returns JSON-encoded responses.

No need a key or an authentification to use this API, just have to know what URL to use, and provide the expected input data.

The Date Calculator API manage any operation related to date and time, you can work with every date unit, time unit, or both. As an extra, it provides a Birthday Calculator, an Age Calculator and some Converters.

Date Calculator

ADD

POST /date/add 

{ "years": 2020, "months": 5, "days": 20, "yearsInput":1, "monthsInput":8, "daysInput":5 }
RESPONSE

{ "years": 2022, "months": 1, "days": 25, "successStatus": true, "message": "Date calculated with success" }

To add some values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/date/add


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
yearsInputLongYears to add.
monthsInputLongMonths to add.
daysInputLong Days to add.

SUB

POST /date/sub 

{ "years": 2020, "months": 5, "days": 20, "yearsInput":1, "monthsInput":8, "daysInput":5 }
RESPONSE

{ "years": 2018, "months": 9, "days": 15, "successStatus": true, "message": "Date calculated with success" }

To subtract some values from an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/date/sub


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
yearsInputLongYears to sub.
monthsInputLongMonths to sub.
daysInputLong Days to sub.

Date Converter

POST /date/convert 

{ "years": 2020, "months": 1, "days": 65 }
RESPONSE

{ "years": 2020, "months": 3, "days": 5, "successStatus": true, "message": "" }

When you have to work with some date units values that exceed the range, you can convert them using this URL :
https://api.date-calculator.org/date/convert


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.

Days between Dates Calculator

POST /days/daysbetweendates 

{ "years": 2020, "months": 1, "days": 5, "yearsInput":2020, "monthsInput":1, "daysInput":1 }
RESPONSE

{ "years": 0, "months": 0, "days": 4, "successStatus": true, "message": "Date calculated with success" }

To retrieve the amount of days between two dates, you need to make a POST call to the following URL :
https://api.date-calculator.org/days/daysbetweendates


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
yearsInputLongYears of the second date.
monthsInputLongMonths of the second date.
daysInputLong Days of the second date.

Days Calculator

ADD

POST /days/add 

{ "years": 2020, "months": 1, "days": 5, "daysInput":1 }
RESPONSE

{ "years": 2020, "months": 1, "days": 6, "successStatus": true, "message": "Date calculated with success" }

To add some days values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/days/add


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
daysInputLong Days to add.

SUB

POST /days/sub 

{ "years": 2020, "months": 1, "days": 5, "daysInput":1 }
RESPONSE

{ "years": 2020, "months": 1, "days": 4, "successStatus": true, "message": "Date calculated with success" }

To subtract some days values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/days/sub


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
daysInputLong Days to sub.

Months Calculator

ADD

POST /months/add 

{ "years": 2020, "months": 5, "days": 5, "monthsInput":1 }
RESPONSE

{ "years": 2020, "months": 6, "days": 5, "successStatus": true, "message": "Date calculated with success" }

To add some months values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/months/add


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
monthsInputLongMonths to add.

SUB

POST /months/sub 

{ "years": 2020, "months": 5, "days": 5, "monthsInput":1 }
RESPONSE

{ "years": 2020, "months": 4, "days": 5, "successStatus": true, "message": "Date calculated with success" }

To subtract some months values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/months/sub


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
monthsInputLongMonths to sub.

Weeks Calculator

ADD

POST /weeks/add 

{ "years": 2019, "months": 10, "days": 5, "weeksInput":2 }
RESPONSE

{ "years": 2019, "months": 10, "days": 19, "successStatus": true, "message": "Date calculated with success" }

To add some values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/weeks/add


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
weeksInputLongWeeks to add.

SUB

POST /weeks/sub 

{ "years": 2019, "months": 10, "days": 5, "weeksInput":2 }
RESPONSE

{ "years": 2019, "months": 9, "days": 21, "successStatus": true, "message": "Date calculated with success" }

To subtract some values from an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/weeks/sub


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
weeksInputLongWeeks to sub.

Years Calculator

ADD

POST /years/add 

{ "years": 2020, "months": 1, "days": 5, "yearsInput":1 }
RESPONSE

{ "years": 2021, "months": 1, "days": 5, "successStatus": true, "message": "Date calculated with success" }

To add some values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/years/add


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
yearsInputLongYears to add.

SUB

POST /years/sub 

{ "years": 2020, "months": 1, "days": 5, "yearsInput":1 }
RESPONSE

{ "years": 2019, "months": 1, "days": 5, "successStatus": true, "message": "Date calculated with success" }

To subtract some values from an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/years/sub


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
yearsInputLongYears to sub.

Age Calculator

POST /age/calculate 

{ "yearsInput":1985, "monthsInput":6, "daysInput":8, "hoursInput":19, "minutesInput":15, "secondsInput":0 }
RESPONSE

{ "years": 35, "months": 2, "days": 3, "hours": 16, "minutes": 27, "seconds": 27, "successStatus": true, "message": "Age calculated with success" }

To calculate your exact age, you need to make a POST call to the following URL :
https://api.date-calculator.org/age/calculate


BODY PARAMETERS

FieldTypeDescription
yearsInputLongYear of birth.
monthsInputLongMonth of birth.
daysInputLong Day of birth.
hoursInputLongHour of birth.
minutesInputLongMinute of birth.
secondsInputLong Second of birth.

Birthday Calculator

POST /birthday/calculate 

{ "yearsInput":27, "monthsInput":10, "daysInput":4, "hoursInput":0, "minutesInput":0, "secondsInput":0 }
RESPONSE

{ "years": 1992, "months": 10, "days": 8, "hours": 11, "minutes": 46, "seconds": 36, "successStatus": true, "message": "Birthday calculated with success" }

To calculate your exact birthday, you need to make a POST call to the following URL :
https://api.date-calculator.org/birthday/calculate


BODY PARAMETERS

FieldTypeDescription
yearsInputLongAge years.
monthsInputLongAge Months.
daysInputLong Age Days.
hoursInputLongAge Hours.
minutesInputLongAge Minutes.
secondsInputLong Age Seconds.

Date and Time Calculator

ADD

POST /datetime/add 

{ "years": 2020, "months": 1, "days": 5, "hours": 1, "minutes": 0, "seconds": 0, "yearsInput":1, "monthsInput":13, "daysInput":2, "hoursInput":0, "minutesInput":55, "secondsInput":55 }
RESPONSE

{ "years": 2022, "months": 2, "days": 7, "hours": 1, "minutes": 55, "seconds": 55, "successStatus": true, "message": "Date and Time calculated with success" }

To add some values to an initial given date and time, you need to make a POST call to the following URL :
https://api.date-calculator.org/datetime/add


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
yearsInputLongYears to add.
monthsInputLongMonths to add.
daysLong Days to add.
hoursInputLongHours to add.
minutesInputLongMinutes to add.
secondsLong Seconds to add.

SUB

POST /datetime/sub 

{ "years": 2020, "months": 1, "days": 5, "hours": 1, "minutes": 0, "seconds": 0, "yearsInput":1, "monthsInput":13, "daysInput":2, "hoursInput":0, "minutesInput":55, "secondsInput":55 }
RESPONSE

{ "years": 2018, "months": 0, "days": 3, "hours": 0, "minutes": 4, "seconds": 5, "successStatus": true, "message": "Date and Time calculated with success" }

To subtract some values from an initial given date and time, you need to make a POST call to the following URL :
https://api.date-calculator.org/datetime/sub


BODY PARAMETERS

FieldTypeDescription
yearsLongYears of the initial date.
monthsLongMonths of the initial date.
daysLong Days of the initial date.
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
yearsInputLongYears to sub.
monthsInputLongMonths to sub.
daysLong Days to sub.
hoursInputLongHours to sub.
minutesInputLongMinutes to sub.
secondsLong Seconds to sub.

Date and Time Converter

POST /datetime/convert 

{ "yearsInput":1, "monthsInput":13, "daysInput":2, "hoursInput":0, "minutesInput":55, "secondsInput":75 }
RESPONSE

{ "years": 2, "months": 1, "days": 2, "hours": 0, "minutes": 56, "seconds": 15, "successStatus": true, "message": "Date and Time converted with success" }

To add some values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/datetime/convert


BODY PARAMETERS

FieldTypeDescription
yearsInputLongYears to convert.
monthsInputLongMonths to convert.
daysLong Days to convert.
hoursInputLongHours to convert.
minutesInputLongMinutes to convert.
secondsLong Seconds to convert.

Hours Calculator

ADD

POST /hours/add 

{ "hours": 1, "minutes": 59, "seconds": 55, "hoursInput":15 }
RESPONSE

{ "hours": 16, "minutes": 59, "seconds": 55, "successStatus": true, "message": "Time calculated with success" }

To add some hours values to an initial given time, you need to make a POST call to the following URL :
https://api.date-calculator.org/hours/add


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
hoursInputLongHours to add.

SUB

POST /hours/sub 

{ "hours": 15, "minutes": 5, "seconds": 55, "hoursInput":2 }
RESPONSE

{ "hours": 13, "minutes": 5, "seconds": 55, "successStatus": true, "message": "Time calculated with success" }

To subtract some hours values from an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/hours/sub


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
hoursInputLongHours to sub.

Minutes Calculator

ADD

POST /minutes/add 

{ "hours": 1, "minutes": 59, "seconds": 55, "minutesInput":15 }
RESPONSE

{ "hours": 2, "minutes": 14, "seconds": 55, "successStatus": true, "message": "Time calculated with success" }

To add some minutes values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/minutes/add


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
minutesInputLongMinutes to add.

SUB

POST /minutes/sub 

{ "hours": 1, "minutes": 5, "seconds": 55, "minutesInput":15 }
RESPONSE

{ "hours": 0, "minutes": 50, "seconds": 55, "successStatus": true, "message": "Time calculated with success" }

To subtract some minutes values from an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/minutes/sub


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
minutesInputLongMinutes to sub.

Seconds Calculator

ADD

POST /seconds/add 

{ "hours": 1, "minutes": 59, "seconds": 55, "secondsInput":15 }
RESPONSE

{ "hours": 2, "minutes": 0, "seconds": 10, "successStatus": true, "message": "Time calculated with success" }

To add some seconds values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/seconds/add


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
secondsInputLongSeconds to add.

SUB

POST /seconds/sub 

{ "hours": 1, "minutes": 59, "seconds": 5, "secondsInput":15 }
RESPONSE

{ "hours": 1, "minutes": 58, "seconds": 50, "successStatus": true, "message": "Time calculated with success" }

To subtract some values from an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/seconds/sub


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
secondsInputLongSeconds to sub.

Time Calculator

ADD

POST /time/add 

{ "hours": 1, "minutes": 5, "seconds": 55, "hoursInput":15, "minutesInput":15, "SecondsInput":15 }
RESPONSE

{ "hours": 1, "minutes": 20, "seconds": 55, "successStatus": true, "message": "Time calculated with success" }

To add some values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/time/add


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
hoursInputLongHours to add.
minutesInputLongMinutes to add.
secondsInputLongSeconds to add.

SUB

POST /time/sub 

{ "hours": 1, "minutes": 5, "seconds": 55, "hoursInput":15, "minutesInput":15, "SecondsInput":15 }
RESPONSE

{ "hours": 0, "minutes": 50, "seconds": 55, "successStatus": true, "message": "Time calculated with success" }

To subtract some values from an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/time/sub


BODY PARAMETERS

FieldTypeDescription
hoursLongHours of the initial time.
minutesLongMinutes of the initial time.
secondsLong Seconds of the initial time.
hoursInputLongHours to sub.
minutesInputLongMinutes to sub.
secondsInputLongSeconds to sub.

Time Converter

POST /time/convert 

{ "hoursInput": 24, "minutesInput": 59, "secondsInput": 65 }
RESPONSE

{ "hours": 25, "minutes": 0, "seconds": 5, "successStatus": true, "message": "Time converter with success" }

To add some values to an initial given date, you need to make a POST call to the following URL :
https://api.date-calculator.org/time/convert


BODY PARAMETERS

FieldTypeDescription
hoursInputLongHours to convert.
minutesInputLongMinutes to convert.
secondsInputLongSeconds to convert.

Errors

POST /time/convert 

{ "hoursInput": 24, "minutesInput": 59, "secondsInput": -5 }
ERROR

{ "hours": null, "minutes": null, "seconds": null, "successStatus": false, "message": "You`ve submitted negative values" }

The Date Calculator API provide always a 200 code for any HTTP response, even for errors, to check whether a response is a success or a an error check the response body parameter successStatus which is a boolean that have a true value if it is a success and false for errors.