ForHosting KIT · Developer Utilities

Date difference and age calculator

People search for the number of days between two dates and for a reliable age in years, months and days. This tool answers both with civil calendar rules only: no time zones, no business-day exceptions and no hidden rounding. You get total days, a signed year-month-day breakdown and a clear record of the ordered pair used for the calculation.

● BetaFree · in your browser

Run — free How it works & API

Use it from WebAPIEmailTelegramApp soon

Civil dates only — no clocks and no time zones

Every input is a pure calendar day in YYYY-MM-DD form. The calculation never consults hours, daylight saving transitions or a server clock for the difference itself. That keeps the same pair of dates stable whether you run the free browser tool or the API. Invalid days such as 2023-02-29 or 2024-04-31 are rejected instead of being silently clamped, so a typing mistake cannot become a wrong anniversary.

Years, months and days with a consistent end-of-month rule

The breakdown uses calendar months with end-of-month clamping: adding one month to 2024-01-31 lands on 2024-02-29, not on an invented March day. When a provisional month would overshoot the end date, the algorithm steps back one month and reports the remaining whole days. That is why 2024-01-31 to 2024-02-29 is one month and zero days, while 2024-01-31 to 2024-02-28 is zero months and twenty-eight days. Total days are exclusive of the start day: the same date yields zero.

Difference mode and age mode share one oracle

Difference mode compares date_from with date_to and returns total_days, years, months, days, sign and the ordered pair. Age mode uses birthdate and an explicit reference_date for deterministic results; if you omit the reference in the free tool, the device's local civil date is used. Numerically, age is the same function as difference with renamed fields, so an age reported for a fixed reference cannot disagree with the date difference for the same pair.

Signed results when the order is reversed

If the end date is earlier than the start date, the tool does not silently swap the inputs. It keeps the submitted order in the echo fields and applies a negative sign to total days and to the year-month-day components. That symmetry covers future birthdays, reversed ranges and automated checks that must detect inverted intervals without a second code path.

What you can do with it

Days between two project milestones

Measure exclusive calendar days between kickoff and deadline without mixing weekends, holidays or time zones into the count.

Civil age for forms and eligibility

Compute age in years, months and days against a fixed reference date so reviews and exports stay reproducible.

Anniversary and leap-day edge cases

Handle 29 February birthdays and end-of-month pairs with the same clamp rule used for ordinary months.

Automated interval checks

Call the API in a pipeline and store total_days together with the signed breakdown for audit logs.

FAQ

Is the day count inclusive or exclusive?

Exclusive of the start day. The same date yields zero total days; the next calendar day yields one.

How is end of month handled?

Months are added with clamp to the last valid day of the target month, then corrected if that intermediate date would pass the end date. Remaining whole days complete the breakdown.

What happens on 29 February in a non-leap year?

An anniversary from 2024-02-29 to 2025-02-28 is one year, zero months and zero days under the clamp rule. Invalid inputs such as 2023-02-29 are rejected.

How does this differ from business days?

This capability counts natural calendar difference and civil age. Business days and holidays belong to a separate tool and are not applied here.

Can the result be negative?

Yes. When the end date precedes the start date, total_days and the year-month-day fields carry a negative sign without swapping the submitted values.

Is the calculator free on desktop and mobile?

The page runs locally and free in desktop and mobile browsers. The native app invokes the API and shows the task price; the same API request costs $0.002 from prepaid KIT balance.

For developers — API access

Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.

API endpoint

POSThttps://api.kit.forhosting.com/dev/date-diff

Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.

Call it from your stack

curl -X POST https://api.kit.forhosting.com/dev/date-diff \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_from":"2024-01-31","date_to":"2024-02-29"}'

const res = await fetch("https://api.kit.forhosting.com/dev/date-diff", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "date_from": "2024-01-31",
    "date_to": "2024-02-29"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/dev/date-diff",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "date_from": "2024-01-31",
    "date_to": "2024-02-29"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/date-diff", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"date_from":"2024-01-31","date_to":"2024-02-29"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"date_from":"2024-01-31","date_to":"2024-02-29"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/date-diff", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Example request

{
  "date_from": "2024-01-31",
  "date_to": "2024-02-29"
}

Example response

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "dev.date_diff",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.

Pricing

Per request$0.002

Published price — no tokens, no invented credits. A failed task is never charged.

Limits

`year_min`	1
`year_max`	9999

Errors

HTTP	Code	Meaning
`401`	`unauthorized`	Missing or invalid API key.
`402`	`insufficient_balance`	Your balance doesn't cover the task price.
`404`	`unknown_type`	That task type doesn't exist.
`429`	`rate_limited`	Too many requests. Use the webhook instead of polling.

Read the full KIT documentation →

Run — free