curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

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

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).

InputTypeDescription
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.

ResultTypeDescription
yearsintegerCompleted years.
monthsintegerCompleted months since the last birthday.
daysintegerDays since the last whole month.
total_monthsintegerCompleted months since birth.
total_weeksintegerCompleted weeks since birth.
total_daysintegerDays since birth.
on_datedate (YYYY-MM-DD)The date the age was calculated on.
next_birthdaydate (YYYY-MM-DD)Date of the next birthday.
days_until_next_birthdayintegerDays until the next birthday.

Examples

Age on a date

Requestcurl
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"
  }'
200 OKResponse
{
  "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

Requestcurl
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"
  }'
200 OKResponse
{
  "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

Requestcurl
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"
  }'
200 OKResponse
{
  "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

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.