Fraction of year elapsed

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. 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. For example, two strings that describe the same instant with different offsets produce the same normalized datetime and the same fraction. A successful automated request costs $0.002; the calculation can also run locally in the browser.

Where a deterministic year-progress ratio is useful

Use this capability when a model, visualization, report, or test fixture needs a stable position within a calendar year rather than an answer tied to whatever time a machine happens to run. 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.