Practical guide
Convert Day of Year to a Date: Leap Years and the Off-by-One Check
For a one-based day-of-year number N, add N − 1 days to January 1 of the supplied Gregorian year. Validate N against 365 or 366 first. Day 60 is March 1 in 2027 but February 29 in 2028; an absolute day ordinal counted from year 1 is a different input.
On this page
Identify the day-number system before converting
A number such as 60 is not a complete date. Ask which year it belongs to and whether the first day is numbered 0 or 1. A day-of-year index resets every January; an absolute ordinal continues across years. An astronomical Julian day is another system and is outside this conversion.
This guide uses one-based day-of-year numbers in the proleptic Gregorian calendar: January 1 is 1. Python’s documented date timetuple defines the annual day number as the date’s absolute ordinal minus January 1’s absolute ordinal, plus 1. Keep the supplied year in the input.
A label such as 2028-061 can be used as a stated year/day-number notation here. Do not assume every parser accepts that form: Python’s documented date.fromisoformat does not support ordinal-date strings, even though it supports some other ISO representations.
Check the year and the valid range
A common year allows day 1 through 365; a leap year allows 1 through 366. The Gregorian leap rule is divisible by 4 except century years not divisible by 400. Thus 2000 is leap, 2028 is leap and 2100 is common.
Reject 0 under this one-based convention. Reject 366 for 2027 rather than silently returning January 1, 2028. If the source explicitly uses a zero-based index, use January 1 plus that index; do not apply both conventions at once.
The year is essential around leap day. February 29 without a year may be a valid recurring label, but it is not a fully specified dated result.
Add N − 1 days and check the result
- Confirm a full year and an integer one-based number N.
- Validate 1≤N≤the year’s length.
- Start at January 1 of that year.
- Add N − 1 calendar days.
- Check that the result is still in the supplied year, then recompute its day-of-year number.
The subtraction of 1 is deliberate: January 1 plus zero days is still January 1, which is day 1. Adding N days would shift every valid result forward by one date.
You can use the add-days calculator with January 1 and N − 1 as inputs after this range check. Keep the annual day number separate from the offset you actually enter.
Compare the leap-day boundary
| Year | Day-of-year | Offset from January 1 | Date |
|---|---|---|---|
| 2027 | 60 | 59 days | 1 March 2027 |
| 2027 | 61 | 60 days | 2 March 2027 |
| 2028 | 60 | 59 days | 29 February 2028 |
| 2028 | 61 | 60 days | 1 March 2028 |
| 2028 | 366 | 365 days | 31 December 2028 |
On a narrow screen, scroll inside the table to read its remaining columns. Keyboard users can focus the table and use the arrow keys.
January contributes 31 days. A common-year February contributes 28, bringing the end of February to day 59; March 1 is 60. A leap-year February contributes 29, placing February 29 at 60 and March 1 at 61.
The same number can therefore identify different month/day pairs in different years. Keeping a table of indices from one common year and reusing it in a leap year shifts every date after February 28.
Use an inverse check and separate absolute ordinals
For a known date, calculate (date − January 1).days + 1. March 1, 2028 is 60 elapsed days after January 1, so its annual index is 61. January 1 itself has zero elapsed days and annual index 1.
Python’s date.toordinal is an absolute count with January 1 of year 1 as 1. It is suitable for exact differences when both dates use that system, but its large result is not the date’s annual day number. Subtract the same year’s January 1 ordinal and add 1 to recover the annual index.
These are date calculations. They do not identify an hour, time zone, local midnight or elapsed 24-hour periods. If the source supplies a timestamp instead, determine which date it represents before applying an annual index.
Two complete day-number decisions
Case 1
A supplied 2028 day-of-year is 61. Someone adds 61 days to January 1 and obtains March 2. What changed?
Show answer and explanation for case 1
They used the annual index as the offset. The correct offset is 60 days, giving March 1, 2028.
Day 1 is January 1 with no offset. The one-based conversion requires N − 1. The inverse check for March 1 returns 60 elapsed days plus 1, confirming 61.
Case 2
A record says 2027 day 366. Should the converter return January 1, 2028?
Show answer and explanation for case 2
No. Reject the annual index for that year or ask for a corrected year/number.
2027 is common and ends at day 365. Crossing into 2028 would hide the invalid input. 2028 day 366 is valid and returns December 31, 2028.
Sources and further reading
- Python date objects — documented calendar and arithmeticProleptic Gregorian dates, valid month/day ranges, exact day differences, ISO calendar fields and one-based day-of-year definition. Only the complete date-objects section was used.
- RFC 3339 Appendix C — leap-year ruleGregorian leap-year arithmetic, including the century/400 year distinction.