Calendar projection
GET /v1/time/calendarOpenAPI YAMLCalendar fields (year, month, day) for a target instant resolved through any selector.
What do I need to send?
Choose one target selector: tz, ip, lat + lon, or offset. The timestamp input is optional and defaults to now.
unix, unix_ms, iso, week, format, and sign are optional.
Rule: The response adds calendar fields after resolving the target instant.
| Name | Needed? | Use it for |
|---|---|---|
unix | Choose one input | Input timestamp as Unix seconds. Defaults to now. |
unix_ms | Choose one input | Input timestamp as Unix milliseconds. |
iso | Choose one input | Input timestamp as ISO 8601. A local value without an offset needs a source_* hint, or it is read as UTC. |
source_tz | Conditional hint | Interpret a local iso= as wall time in this IANA zone. |
source_ip | Conditional hint | Interpret a local iso= using this IP address timezone. |
source_lat | Pair parameter | Latitude hint for local iso=. Pair with source_lon. |
source_lon | Pair parameter | Longitude hint for local iso=. Pair with source_lat. |
source_offset | Conditional hint | Interpret a local iso= against a fixed UTC offset. |
tz | Choose one target | Project into this IANA zone. |
ip | Choose one target | Project into the zone of this IP. |
lat | Pair parameter | Latitude, pair with lon. |
lon | Pair parameter | Longitude. |
offset | Choose one target | Project against a fixed UTC offset (URL-encode + as %2B). |
auto_tz | Choose one target | Set true to project into the request IP's timezone. |
week | Optional | Set true to include the ISO 8601 week_number. It is paired with the ISO week-year, which can differ from year near January 1. |
format | Optional | strftime pattern for an extra `formatted` field. |
sign | Optional | Set true for a signed response. |
Code samples
Copy a request in your preferred language and replace YOUR_TIMELOGIC_API_KEY with your direct API key.
curl "https://api.timelogicapi.com/v1/time/calendar?tz=Europe/Paris&week=true" \
-H "Authorization: Bearer $TIMELOGIC_API_KEY"Example response
{
"unix": 1778093026,
"unix_ms": 1778093026668,
"utc": "2026-05-06T18:43:46Z",
"iso_local": "2026-05-06T20:43:46+02:00",
"rfc2822": "Wed, 06 May 2026 20:43:46 +0200",
"human": "May 6, 2026, 8:43 PM Europe/Paris",
"day_number": 4,
"day_short": "Wed",
"day_full": "Wednesday",
"timezone": "Europe/Paris",
"year": 2026,
"month": 5,
"month_name": "May",
"day": 6,
"week_number": 19
}
Additional endpoint notes
https://api.timelogicapi.com/v1/time/calendar?tz=Europe/Paris&week=true
https://api.timelogicapi.com/v1/time/calendar?unix=1711300000&tz=Europe/Paris
https://api.timelogicapi.com/v1/time/calendar?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Asia/Tokyo
With no selector the projection is in UTC (iso_local and timezone are null).
Common errors
400 AMBIGUOUS_TARGET— multiple input or target selector families.400 INVALID_PARAMETER— bad timezone, offset, or unsupported strftime directive.400 INVALID_TIMESTAMP— a malformed, nonexistent (2027-02-29) or out-of-range input timestamp.
When to use this endpoint
Use Calendar projection when you need calendar fields for a target instant after resolving it through a timezone, IP address, coordinates, or fixed offset. It is useful for reports, date pickers, locale-aware grouping, and analytics labels.
Request model
Choose a timestamp input or omit it to project the current request time. Then choose a single target selector family (tz, ip, lat + lon, offset, or auto_tz=true) to define the calendar context.
Response notes
Calendar fields are derived after timezone resolution, so the same UTC instant can produce different year, month, day and weekday values in different zones. The calendar fields are year, month (1–12), month_name, day and, with week=true, week_number; there is no day-of-year field, so use format=%25j if you need it.
week_number is the ISO 8601 week, but no ISO week-year is returned, and the two years differ around January 1. For example iso=2027-01-01T12:00:00Z&tz=UTC&week=true returns "year": 2027, "week_number": 53: January 1, 2027 belongs to ISO week 2026-W53. Do not build a week label from year + week_number; derive the week-year yourself (the year of that week's Thursday).
Frequently asked questions
How do I get the ISO week number from an API?
Call GET /v1/time/calendar?tz=Europe/Paris&week=true. week_number is the ISO 8601 week.
Why can the year and the ISO week disagree?
No ISO week-year is returned. Around January 1 the calendar year and the ISO week-year can differ, so derive the week-year from that week's Thursday instead of combining year and week_number.
Is there a day-of-year field?
No. Use format=%25j to add the day of the year as a formatted value.