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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
yearsInput	Long	Years to add.
monthsInput	Long	Months to add.
daysInput	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
yearsInput	Long	Years to sub.
monthsInput	Long	Months to sub.
daysInput	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
yearsInput	Long	Years of the second date.
monthsInput	Long	Months of the second date.
daysInput	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
daysInput	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
daysInput	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
monthsInput	Long	Months 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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
monthsInput	Long	Months 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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
weeksInput	Long	Weeks 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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
weeksInput	Long	Weeks 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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
yearsInput	Long	Years 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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
yearsInput	Long	Years 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

Field	Type	Description
yearsInput	Long	Year of birth.
monthsInput	Long	Month of birth.
daysInput	Long	Day of birth.
hoursInput	Long	Hour of birth.
minutesInput	Long	Minute of birth.
secondsInput	Long	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

Field	Type	Description
yearsInput	Long	Age years.
monthsInput	Long	Age Months.
daysInput	Long	Age Days.
hoursInput	Long	Age Hours.
minutesInput	Long	Age Minutes.
secondsInput	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
yearsInput	Long	Years to add.
monthsInput	Long	Months to add.
days	Long	Days to add.
hoursInput	Long	Hours to add.
minutesInput	Long	Minutes to add.
seconds	Long	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

Field	Type	Description
years	Long	Years of the initial date.
months	Long	Months of the initial date.
days	Long	Days of the initial date.
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
yearsInput	Long	Years to sub.
monthsInput	Long	Months to sub.
days	Long	Days to sub.
hoursInput	Long	Hours to sub.
minutesInput	Long	Minutes to sub.
seconds	Long	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

Field	Type	Description
yearsInput	Long	Years to convert.
monthsInput	Long	Months to convert.
days	Long	Days to convert.
hoursInput	Long	Hours to convert.
minutesInput	Long	Minutes to convert.
seconds	Long	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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
hoursInput	Long	Hours 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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
hoursInput	Long	Hours 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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
minutesInput	Long	Minutes 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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
minutesInput	Long	Minutes 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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
secondsInput	Long	Seconds 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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
secondsInput	Long	Seconds 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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
hoursInput	Long	Hours to add.
minutesInput	Long	Minutes to add.
secondsInput	Long	Seconds 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

Field	Type	Description
hours	Long	Hours of the initial time.
minutes	Long	Minutes of the initial time.
seconds	Long	Seconds of the initial time.
hoursInput	Long	Hours to sub.
minutesInput	Long	Minutes to sub.
secondsInput	Long	Seconds 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

Field	Type	Description
hoursInput	Long	Hours to convert.
minutesInput	Long	Minutes to convert.
secondsInput	Long	Seconds 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.