Age calculation API
Exact age in years, months and days, plus the next birthday, with an explicit rule for 29 February birthdays.
POST https://api.curatedapi.com/v1/calc/date/age
- Version 1
- MCP tool
calc_date_age - Try it in the browser
Age on a given date as completed years, months and days. People born on 29 February reach a new age on 28 February in common years by default (the rule in New Zealand and Taiwan, and the one consistent with date arithmetic); choose mar1 for the 1 March rule used in the UK and Hong Kong.
Formula
years = completed anniversaries; then months and days as in date/difference
- Dates use the Gregorian calendar (ISO 8601). Adding months clamps to the month's last day (Jan 31 + 1 month = Feb 28 or 29).
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
birth_date required |
date (YYYY-MM-DD) | Date of birth (YYYY-MM-DD). |
on_date |
date (YYYY-MM-DD) | Date to calculate the age on. Defaults to today in UTC. |
leap_day_birthday |
feb28 | mar1 default feb28 |
When someone born on 29 February has a birthday in a common year. Options: feb28: on 28 February; mar1: on 1 March |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
years | integer | Completed years. |
months | integer | Completed months since the last birthday. |
days | integer | Days since the last whole month. |
total_months | integer | Completed months since birth. |
total_weeks | integer | Completed weeks since birth. |
total_days | integer | Days since birth. |
on_date | date (YYYY-MM-DD) | The date the age was calculated on. |
next_birthday | date (YYYY-MM-DD) | Date of the next birthday. |
days_until_next_birthday | integer | Days until the next birthday. |
Examples
Age on a date
curl https://api.curatedapi.com/v1/calc/date/age \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth_date": "1990-05-15",
"on_date": "2026-10-20"
}'
{
"calculator": "date/age@1",
"result": {
"years": 36,
"months": 5,
"days": 5,
"total_months": 437,
"total_weeks": 1901,
"total_days": 13307,
"on_date": "2026-10-20",
"next_birthday": "2027-05-15",
"days_until_next_birthday": 207
},
"exactness": {},
"precision": null,
"inputs": {
"birth_date": "1990-05-15",
"on_date": "2026-10-20",
"leap_day_birthday": "feb28"
},
"formula": "years = completed anniversaries; then months and days as in date/difference",
"references": [
{
"title": "ISO 8601 date and time format",
"url": "https://www.iso.org/iso-8601-date-and-time-format.html"
},
{
"title": "IANA Time Zone Database",
"url": "https://www.iana.org/time-zones"
},
{
"title": "UK Family Law Reform Act 1969, s.9 (time at which a person attains an age)",
"url": "https://www.legislation.gov.uk/ukpga/1969/46/section/9"
}
],
"warnings": []
}
Leap-day birthday, 28 Feb rule
curl https://api.curatedapi.com/v1/calc/date/age \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth_date": "2000-02-29",
"on_date": "2001-02-28"
}'
{
"calculator": "date/age@1",
"result": {
"years": 1,
"months": 0,
"days": 0,
"total_months": 12,
"total_weeks": 52,
"total_days": 365,
"on_date": "2001-02-28",
"next_birthday": "2002-02-28",
"days_until_next_birthday": 365
},
"exactness": {},
"precision": null,
"inputs": {
"birth_date": "2000-02-29",
"on_date": "2001-02-28",
"leap_day_birthday": "feb28"
},
"formula": "years = completed anniversaries; then months and days as in date/difference",
"references": [
{
"title": "ISO 8601 date and time format",
"url": "https://www.iso.org/iso-8601-date-and-time-format.html"
},
{
"title": "IANA Time Zone Database",
"url": "https://www.iana.org/time-zones"
},
{
"title": "UK Family Law Reform Act 1969, s.9 (time at which a person attains an age)",
"url": "https://www.legislation.gov.uk/ukpga/1969/46/section/9"
}
],
"warnings": []
}
Leap-day birthday, 1 Mar rule
curl https://api.curatedapi.com/v1/calc/date/age \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth_date": "2000-02-29",
"on_date": "2001-02-28",
"leap_day_birthday": "mar1"
}'
{
"calculator": "date/age@1",
"result": {
"years": 0,
"months": 0,
"days": 0,
"total_months": 0,
"total_weeks": 52,
"total_days": 365,
"on_date": "2001-02-28",
"next_birthday": "2001-03-01",
"days_until_next_birthday": 1
},
"exactness": {},
"precision": null,
"inputs": {
"birth_date": "2000-02-29",
"on_date": "2001-02-28",
"leap_day_birthday": "mar1"
},
"formula": "years = completed anniversaries; then months and days as in date/difference",
"references": [
{
"title": "ISO 8601 date and time format",
"url": "https://www.iso.org/iso-8601-date-and-time-format.html"
},
{
"title": "IANA Time Zone Database",
"url": "https://www.iana.org/time-zones"
},
{
"title": "UK Family Law Reform Act 1969, s.9 (time at which a person attains an age)",
"url": "https://www.legislation.gov.uk/ukpga/1969/46/section/9"
}
],
"warnings": []
}
References
- ISO 8601 date and time format
- IANA Time Zone Database
- UK Family Law Reform Act 1969, s.9 (time at which a person attains an age)
Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.