Fraction of year elapsed
At noon UTC on 2 July 2026 the year is exactly half over: the fraction is 0.5. Enter a date and time with Z or an offset such as +05:30 to see how far through its UTC year that moment lies, ready for dashboards. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Datetime
- 2026-07-02T12:00:00Z
- Utc datetime
- 2026-07-02T12:00:00Z
- Utc year
- 2,026
- Elapsed milliseconds
- 15,768,000,000
- Year milliseconds
- 31,536,000,000
This year progress calculator returns the fraction of the UTC calendar year that has elapsed at an explicit ISO 8601 datetime. It converts a supplied Z time or numeric-offset time to UTC, measures the exact milliseconds since January 1 at 00:00:00 UTC, and divides that duration by the full length of the resulting UTC year. Leap years use 366 days; common years use 365. No current date, local timezone, network lookup, random value, or hidden default can affect the answer.
What fraction of the year elapsed means
The returned fraction is a continuous measure of progress through one UTC calendar year. Its numerator is the number of milliseconds from January 1 at 00:00:00.000 UTC to the supplied instant, and its denominator is the number of milliseconds in that entire UTC year. At the first instant of January 1 the result is exactly zero.
It then increases through the year but remains below one for every valid datetime within that year; one belongs to the first instant of the following year, where a new calculation starts again at zero. This is different from a day-of-year percentage that counts whole dates or treats the current date as completely elapsed. Noon contributes half of that date, seconds contribute their exact share, and up to three fractional-second digits are preserved as milliseconds.
The denominator is 365 days in a common year and 366 in a Gregorian leap year. Because the input offset is normalized before the UTC year is selected, an instant written late on December 31 in one offset can correctly belong to January 1 of the next UTC year.
How to supply an unambiguous ISO datetime
Send datetime in the form YYYY-MM-DDTHH:mm:ssZ, optionally adding one to three fractional-second digits, or replace Z with a signed numeric offset such as +05:30 or -04:00. The timezone designator is mandatory because a datetime without one does not identify a unique instant. Date-only values, localized dates, month names, spaces in place of T, and offsets without a colon are rejected rather than guessed.
The parser also validates Gregorian month lengths, leap days, hours, minutes, seconds, and offset fields. Leap seconds are not accepted: seconds range from 00 through 59, matching the fixed-length civil-minute model used by the calculation. For example, two strings that describe the same instant with different offsets produce the same normalized datetime and the same fraction.
Where a deterministic year-progress ratio is useful
Dashboards can turn the fraction into a percentage or progress bar while retaining the exact numerator and denominator for labels and audits. Data pipelines can enrich timestamped records with a normalized annual coordinate for seasonal analysis, interpolation, or cyclic features, knowing that offset-bearing inputs are compared on the same UTC timeline. Test suites can pin boundary cases at New Year, leap day, or the final millisecond of December without mocking a clock.
The result is based on elapsed duration, so it should not be used as a count of completed calendar dates, working days, fiscal periods, or equal-length months. It also deliberately models ordinary UTC civil days as 86,400 seconds and does not insert leap seconds, which makes the operation portable and reproducible. If a consumer needs a percentage, multiply fraction by one hundred without rounding until display time.
If it needs a fiscal-year ratio, use boundaries for that fiscal calendar instead of relabeling this calendar-year result.
What you can do with it
Annual progress dashboards
Convert an explicit report timestamp into an exact zero-to-one UTC year position for progress bars and KPI annotations.
Seasonal data features
Add a consistent continuous annual coordinate to timestamped records after normalizing their explicit offsets to UTC.
FAQ
Can the fraction ever equal one?
No for an instant within its selected UTC year. The first instant of the next year belongs to that new year and returns zero.
How are leap years handled?
The denominator uses 366 days when the UTC year is divisible by four, except century years not divisible by four hundred; otherwise it uses 365 days.
Why is a timezone required?
Without Z or a numeric offset, an ISO local datetime does not identify one UTC instant and could produce different answers in different environments.
Does the calculation include leap seconds?
No. It uses fixed 86,400-second civil days and accepts seconds from 00 through 59, providing a portable deterministic calendar ratio.
Can a time on 31 December count toward the next year?
Yes. The offset is applied first, so a late-December local time can already be 1 January in UTC. In that case it belongs to the new UTC year and its fraction starts again near zero.
Related tools
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
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/date/fraction-of-year-elapsed \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"datetime":"2026-07-02T12:00:00Z"}'const res = await fetch("https://api.kit.forhosting.com/date/fraction-of-year-elapsed", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"datetime": "2026-07-02T12:00:00Z"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/date/fraction-of-year-elapsed",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"datetime": "2026-07-02T12:00:00Z"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/fraction-of-year-elapsed", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"datetime":"2026-07-02T12:00:00Z"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"datetime":"2026-07-02T12:00:00Z"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/fraction-of-year-elapsed", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"datetime": "2026-07-02T12:00:00Z"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "date.fraction_of_year_elapsed",
"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
Published price — no tokens, no invented credits. A failed task is never charged.
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. |
Technical notes
How to supply an unambiguous ISO datetime
After parsing, the offset is applied with integer arithmetic and the resulting instant is expressed as utc_datetime. The response also exposes utc_year, elapsed_milliseconds, and year_milliseconds, making the fraction auditable without recreating calendar rules. A successful automated request costs $0.002; the calculation can also run locally in the browser.
Integration use cases
Deterministic boundary tests
Create reproducible fixtures around New Year and leap day without reading or mocking the system clock.
Technical questions
What does an API request cost?
A successful API calculation costs $0.002 per request. The same pure calculation is also available in the browser.