Skip to content
Endpoint guide

Calendar projection

GET /v1/time/calendarOpenAPI YAML

Calendar fields (year, month, day) for a target instant resolved through any selector.

What do I need to send?

Required / choose this first

Choose one target selector: tz, ip, lat + lon, or offset. The timestamp input is optional and defaults to now.

Optional

unix, unix_ms, iso, week, format, and sign are optional.

Rule: The response adds calendar fields after resolving the target instant.

NameNeeded?Use it for
unixChoose one inputInput timestamp as Unix seconds. Defaults to now.
unix_msChoose one inputInput timestamp as Unix milliseconds.
isoChoose one inputInput timestamp as ISO 8601. A local value without an offset needs a source_* hint, or it is read as UTC.
source_tzConditional hintInterpret a local iso= as wall time in this IANA zone.
source_ipConditional hintInterpret a local iso= using this IP address timezone.
source_latPair parameterLatitude hint for local iso=. Pair with source_lon.
source_lonPair parameterLongitude hint for local iso=. Pair with source_lat.
source_offsetConditional hintInterpret a local iso= against a fixed UTC offset.
tzChoose one targetProject into this IANA zone.
ipChoose one targetProject into the zone of this IP.
latPair parameterLatitude, pair with lon.
lonPair parameterLongitude.
offsetChoose one targetProject against a fixed UTC offset (URL-encode + as %2B).
auto_tzChoose one targetSet true to project into the request IP's timezone.
weekOptionalSet true to include the ISO 8601 week_number. It is paired with the ISO week-year, which can differ from year near January 1.
formatOptionalstrftime pattern for an extra `formatted` field.
signOptionalSet 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.