Skip to content
Reference

API Reference

Use the interactive OpenAPI 3 reference to authorize with a direct Bearer key and try requests from the page. Each endpoint has a concise guide with parameters and code samples below.

Try requests live: click Authorize, paste a direct API key, then expand any operation and use Try it out → Execute.Moving from worldtimeapi.org? The /api/timezone and /api/ip routes have their own interactive WorldTimeAPI-compatible reference.

Interactive OpenAPI reference

The browser version loads Swagger UI so you can authorize and try requests. The endpoint guides below are available as crawlable HTML and include request, response, and authentication details.

Download the OpenAPI YAML

Endpoint guides

Short, copy-ready guides for the request, response, and parameters of each endpoint.

Get current time

GET /v1/time/current

Resolve the precise current time for any timezone, IP, coordinate or UTC offset.

Parameters
  • tz— IANA timezone, e.g. Europe/Paris. Comma-separated values enable bulk mode.
  • ip— IPv4 or IPv6 address (resolved via GeoLite2). Comma-separated for bulk.
  • lat— Latitude in decimal degrees. Pair with lon.
  • lon— Longitude in decimal degrees. Pair with lat.
  • offset— Fixed UTC offset, URL-encoded e.g. %2B02:00 for +02:00. Comma-separated for bulk.
  • auto_tz— Set true to use the request IP's timezone from Cloudflare metadata.
  • format— strftime pattern for an additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S.
  • sign— Set true to receive a signed response (Ed25519 headers).
Code sample
curl "https://api.timelogicapi.com/v1/time/current?tz=Europe/Paris" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
{
  "unix": 1778093048,
  "unix_ms": 1778093048881,
  "utc": "2026-05-06T18:44:08Z",
  "iso_local": "2026-05-06T20:44:08+02:00",
  "rfc2822": "Wed, 06 May 2026 20:44:08 +0200",
  "human": "May 6, 2026, 8:44 PM Europe/Paris",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": "Europe/Paris"
}
Additional endpoint notes

Use at most one selector family (tz, ip, lat+lon, offset, or auto_tz=true) per request. If no selector is provided, the response is in UTC with "iso_local": null and "timezone": null. An offset target also returns "timezone": null, with a human label such as UTC+02:00. Mixing selector families returns 400 AMBIGUOUS_TARGET.

curl "https://api.timelogicapi.com/v1/time/current?tz=Europe/Paris" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

Bulk mode: pass a comma-separated list (up to 10 values) to one selector to receive an array, in input order. Any comma, even a trailing one, returns an array. Failed items appear in place as { "item", "error", "request_id" } while the response is still HTTP 200 (see Bulk mode):

GET /v1/time/current?tz=Europe/Paris,Asia/Tokyo,America/New_York

Common errors

  • 400 INVALID_PARAMETER — invalid IANA timezone (e.g. tz=Not/AZone) or malformed offset. Use %2B to URL-encode +.
  • 400 AMBIGUOUS_TARGET — multiple selector families in the same request.
  • 404 NOT_FOUND — an ip with no timezone mapping (private or reserved addresses such as 10.0.0.1).

When to use this endpoint

Use Get current time when an application needs a canonical "now" value for a single place or for a batch of places. It is the best fit for dashboards, scheduling previews, user profile defaults, countdowns, and systems that need a server-side timestamp rather than a browser clock.

Request model

Choose one selector family per request: tz, ip, lat + lon, offset, or auto_tz=true. Bulk requests use a comma-separated list inside the same family, which keeps validation predictable and preserves the response order for the caller.

Response notes

The response includes Unix seconds, Unix milliseconds, UTC, local ISO 8601, RFC 2822, human-readable text, day fields, and the resolved timezone. day_number counts from Sunday (1 = Sunday … 7 = Saturday). timezone is the canonical zone, which can differ from the name you sent (Europe/Stockholm returns Europe/Berlin). Prefer unix_ms for ordering events and iso_local for display. For browser and Node.js code that calls this current time API and keeps a clock offset, see the JavaScript guide.

Convert time

GET /v1/time/convert

Convert one input timestamp into a target timezone, offset, IP, coordinate, or UTC. Supports bulk targets.

Parameters
  • unix— Input timestamp as Unix seconds.
  • unix_ms— Input timestamp as Unix milliseconds.
  • iso— Input timestamp as ISO 8601. May include offset (e.g. ...Z) or be local with a source_* hint.
  • source_tz— Interpret a local iso= as wall time in this IANA zone.
  • source_ip— Interpret local iso= using the timezone of this IP.
  • source_lat— Latitude for local iso= zone resolution. Pair with source_lon.
  • source_lon— Longitude for local iso= zone resolution.
  • source_offset— Interpret local iso= against a fixed UTC offset.
  • tz— Target IANA timezone. Comma-separated for bulk.
  • ip— Target via IP address. Comma-separated for bulk.
  • lat— Target latitude. Pair with lon.
  • lon— Target longitude.
  • offset— Target fixed UTC offset. URL-encode + as %2B. Comma-separated for bulk.
  • auto_tz— Set true to target the request IP's timezone.
  • utc— Set true to render the target in UTC (iso_local and timezone are then null).
  • format— strftime pattern for the additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S. Unsupported directives return 400; see /docs#selectors for the list.
  • sign— Set true for a signed response.
Code sample
curl "https://api.timelogicapi.com/v1/time/convert?unix=1711300000&tz=Europe/London" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
{
  "unix": 1711300000,
  "unix_ms": 1711300000000,
  "utc": "2024-03-24T17:06:40Z",
  "iso_local": "2024-03-24T17:06:40+00:00",
  "rfc2822": "Sun, 24 Mar 2024 17:06:40 +0000",
  "human": "March 24, 2024, 5:06 PM Europe/London",
  "day_number": 1,
  "day_short": "Sun",
  "day_full": "Sunday",
  "timezone": "Europe/London"
}
Additional endpoint notes

Provide exactly one input timestamp form (unix, unix_ms, or iso) and exactly one target selector family.

# Numeric input → named zone
curl "https://api.timelogicapi.com/v1/time/convert?unix=1711300000&tz=Europe/London" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

# Local ISO with source zone hint
.https://api.timelogicapi.com/v1/time/convert?iso=2026-04-16T09:00:00&source_tz=America/New_York&tz=Europe/London

# Bulk targets — one comma-separated selector
.https://api.timelogicapi.com/v1/time/convert?unix=1711300000&offset=-04:00,%2B00:00,%2B09:00

# strftime
.https://api.timelogicapi.com/v1/time/convert?unix=1711300000&tz=Europe/London&format=%25Y-%25m-%25d%20%25H:%25M:%25S
# → adds "formatted": "2024-03-24 17:06:40"

Supported format directives: %a %A %b %B %C %d %D %e %F %h %H %I %j %k %l %m %M %n %p %P %r %R %s %S %t %T %u %v %w %x %X %y %Y %z %:z %Z %%, with the -, _ and 0 padding flags on numeric directives. %Z prints the IANA zone name (for example Europe/London), not an abbreviation. Anything else, such as %U, %f or %Q, returns 400 INVALID_PARAMETER naming the directive.

Bulk response: an array of payloads, one per target (up to 10), in input order. A target that fails appears in place as { "item", "error", "request_id" } and the response is still HTTP 200.

Common errors

  • 400 INVALID_TIMESTAMP — no input timestamp provided; a malformed iso; a date that does not exist (2027-02-29); a local time inside a spring-forward gap (2026-03-08T02:30:00 with source_tz=America/New_York); or a value outside 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z (for example unix=99999999999999).
  • 400 MISSING_TARGET — no target selector / utc=true provided.
  • 400 AMBIGUOUS_TARGET — multiple input or target families combined, or a bulk selector mixed with another target (including utc=true).
  • 400 INVALID_PARAMETER — invalid timezone, offset, or unsupported strftime directive.
  • 404 NOT_FOUND — a target ip with no timezone mapping.

When to use this endpoint

Use Convert time when you already have a source timestamp and need to project it into another timezone, fixed offset, IP-derived zone, coordinate-derived zone, or UTC. It is designed for meeting planners, notification systems, travel tools, and scheduling interfaces.

Request model

Provide exactly one input timestamp (unix, unix_ms, or iso). If an ISO value is a local wall time without an embedded offset, add one source hint such as source_tz so TimeLogic can interpret that wall time safely before converting it. Without a hint, a local ISO value is read as UTC. A wall time that occurs twice at a fall-back change (for example 2026-11-01T01:30:00 in America/New_York) resolves to the first occurrence (01:30 EDT); a wall time skipped at a spring-forward change returns 400 INVALID_TIMESTAMP. See Selectors for the accepted ISO shapes.

utc=true is a target of its own and cannot be combined with tz, ip, lat/lon, offset or auto_tz; the resulting 400 AMBIGUOUS_TARGET message lists only the five selector families. With utc=true, iso_local and timezone are null.

Bulk targets

Bulk conversion is useful for world clocks and availability screens. Send comma-separated target selectors in one target family to get an array of converted values in the same order as the input list.

Diff between two moments

GET /v1/time/diff

Absolute duration between two specifier-encoded instants, with optional business-day count.

Parameters
  • from(required)— Start specifier. One of: now, unix=N, unix_ms=N, iso=..., tz=..., ip=..., offset=...
  • to(required)— End specifier. Same forms as from.
  • from_tz— Wall-clock zone hint for from=iso=... (no embedded offset).
  • from_ip— Resolve from=iso=... wall clock via this IP's zone.
  • from_lat— Latitude hint for from=iso=... wall clock. Pair with from_lon.
  • from_lon— Longitude hint for from=iso=... wall clock.
  • from_offset— Fixed offset hint for from=iso=... wall clock.
  • to_tz— Wall-clock zone hint for to=iso=... (no embedded offset).
  • to_ip— Resolve to=iso=... wall clock via this IP's zone.
  • to_lat— Latitude hint for to=iso=... wall clock. Pair with to_lon.
  • to_lon— Longitude hint for to=iso=... wall clock.
  • to_offset— Fixed offset hint for to=iso=... wall clock.
  • format— Duration template using %days %hours %minutes %seconds. Each placeholder is a total, not a remainder.
  • business_days— Set true (or 1 / yes) to include a business_days count in the response. Counted by calendar date, start included, end excluded.
  • holiday_country— Holiday calendar: one of the 249 countries with holiday calendars (ISO 3166-1 alpha-2, e.g. FR, SA, CH), or a combined code such as CH-ZH or FR-6AE. Requires business_days=true. Full list: /docs#holiday-calendars.
  • holiday_subdivision— Subdivision code for the country, e.g. ENG (GB), ZH (CH), MH (IN), 01 (FI), 6AE (FR); digits and leading zeros are part of the code. Requires holiday_country and business_days=true. Full list: /docs#holiday-calendars.
  • sign— Set true for a signed response.
Code sample
curl "https://api.timelogicapi.com/v1/time/diff?from=unix=1711300000&to=tz=America/New_York" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
{
  "seconds": 10195200,
  "minutes": 169920,
  "hours": 2832,
  "days": 118,
  "direction": "forward",
  "human": "2832 hours, 0 minutes, 0 seconds",
  "from": { "unix_ms": 1767312000000 },
  "to":   { "unix_ms": 1777507200000 },
  "business_days": 83
}
Additional endpoint notes

from and to are embedded specifier strings — the value itself is a key=value form:

?from=unix=1711300000&to=now ?from=iso=2026-04-16T09:00:00&from_tz=America/New_York&to=iso=2026-04-16T09:00:00&to_tz=Europe/London ?from=now&to=unix=1711300000

Selector forms (tz=..., ip=..., offset=...) inside from/to resolve to the request-time instant, which is the same in every zone, so they never change seconds or direction (from=ip=8.8.8.8&to=now is 0 seconds). They exist for symmetry, and their zone is used to pick the calendar date when counting business days. Coordinates are not a specifier (from=lat=… returns "Unsupported time specifier."); use them only as the from_lat/from_lon hint for a local iso.

curl "https://api.timelogicapi.com/v1/time/diff?from=iso=2026-01-02T00:00:00Z&to=iso=2026-04-30T00:00:00Z&business_days=true&holiday_country=FR" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

direction is forward, backward, or same. Magnitudes are absolute. seconds, minutes, hours and days are each the whole duration in that unit (rounded down), not parts of one breakdown. format=%25days%20days%20%25hours%20hours adds a formatted field; its placeholders are totals too, so a 118-day range renders as 118 days 2832 hours, not 118 days 0 hours. human is always written in hours, minutes and seconds (2832 hours, 0 minutes, 0 seconds), never in days.

Business days. With business_days=true the count uses calendar dates, start included and end excluded, so the example above returns 83 (January 2 through April 29). Each endpoint's date is taken in its own zone when one is known (from_tz/to_tz or the other hints, or a tz=/ip=/offset= specifier), and in UTC otherwise. Weekends follow the calendar's country (Friday and Saturday for SA, for example). Full rules: Diff & business days; all 249 countries and their subdivision codes: Holiday calendars.

Common errors

  • 400 INVALID_PARAMETER — missing from/to, malformed specifier ("Unsupported time specifier."), a country with no holiday calendar ("Unsupported holiday calendar.", for example LK or ZZ), an unknown subdivision ("Unknown holiday_subdivision 'XX' for country DE.", also for FI-1, which must be written FI-01), a malformed code ("Invalid holiday_country parameter." / "Invalid holiday_subdivision parameter."), or a business-day range outside 1900–2100 with a calendar ("Holiday calendar coverage is only available for years 1900-2100.").
  • 400 INVALID_TIMESTAMP — an iso/unix value inside a specifier that is malformed, not a real date, or out of range.
  • 400 INVALID_PARAMETER — holiday_subdivision without holiday_country, or holiday params without business_days=true.

When to use this endpoint

Use Diff between two moments to calculate elapsed duration between any two specifier-encoded instants. It works well for SLA counters, age calculations, countdowns, and workflows that compare a stored event time to a user-local or zone-local target.

Request model

The from and to parameters are required. Each can be now, a Unix value, an ISO value, or a selector-backed instant such as a timezone, IP, or fixed offset (which all mean "now"). Zone hints disambiguate local ISO wall times.

Business-day mode

Enable business-day counting when product logic needs calendar-aware duration instead of pure elapsed seconds. Pair it with the business-day documentation for holiday calendar and weekend assumptions.

Add to a timestamp

GET /v1/time/add

Add days, hours, minutes, and seconds to a base timestamp. Modifiers may be negative.

Parameters
  • unix— Base timestamp as Unix seconds. Defaults to current request time when omitted.
  • unix_ms— Base timestamp as Unix milliseconds.
  • iso— Base timestamp as ISO 8601.
  • days— Whole days to add, each exactly 24 hours (86,400 seconds). Negative subtracts.
  • hours— Hours to add. Negative subtracts.
  • minutes— Minutes to add. Negative subtracts.
  • seconds— Seconds to add. Negative subtracts.
  • source_tz— Interpret a local iso= base as wall time in this IANA zone.
  • source_ip— Interpret a local iso= base using this IP address timezone.
  • source_lat— Latitude hint for local iso=. Pair with source_lon.
  • source_lon— Longitude hint for local iso=. Pair with source_lat.
  • source_offset— Interpret a local iso= base against a fixed UTC offset.
  • tz— Render the result in this IANA timezone.
  • ip— Render the result in the timezone of this IP address.
  • lat— Target latitude. Pair with lon.
  • lon— Target longitude. Pair with lat.
  • offset— Render the result against a fixed UTC offset (URL-encode + as %2B).
  • auto_tz— Set true to render the result in the request IP's timezone.
  • utc— Set true to render the target in UTC.
  • format— strftime pattern for an additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S.
  • sign— Set true for a signed response.
Code sample
curl "https://api.timelogicapi.com/v1/time/add?unix=1711300000&days=3&hours=2" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
{
  "unix": 1711566400,
  "unix_ms": 1711566400000,
  "utc": "2024-03-27T19:06:40Z",
  "iso_local": null,
  "rfc2822": "Wed, 27 Mar 2024 19:06:40 +0000",
  "human": "March 27, 2024, 7:06 PM UTC",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": null
}
Additional endpoint notes
# Add 3 days and 2 hours to a Unix timestamp
.https://api.timelogicapi.com/v1/time/add?unix=1711300000&days=3&hours=2

# Add 2h30m to an ISO timestamp
.https://api.timelogicapi.com/v1/time/add?iso=2026-04-16T09:00:00Z&hours=2&minutes=30

# Subtract one day
.https://api.timelogicapi.com/v1/time/add?unix=1711300000&days=-1

Provide at most one base form. With no base, the modifier is applied to the current request time. With no target selector the result is rendered in UTC with iso_local and timezone set to null, as in the sample above.

Units. Only days, hours, minutes and seconds exist. There are no weeks, months or years parameters, and unknown parameters are ignored rather than rejected, so weeks=1 returns the base time unchanged. Modifiers are added as exact durations: days=1 always adds 24 hours, so across a daylight-saving change the local wall-clock time shifts by an hour (in America/New_York, 09:00 on March 7, 2026 plus days=1 is 10:00 on March 8). This endpoint is not calendar-aware and does not skip weekends or holidays; it is not a business-day adder.

Range. The base and the result must both fall between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59Z. A result outside that range returns 400 INVALID_PARAMETER ("The resulting timestamp is out of range. Supported range: …").

Common errors

  • 400 AMBIGUOUS_TARGET — multiple base forms supplied.
  • 400 INVALID_PARAMETER — non-integer modifier values, or a result outside the supported range.
  • 400 INVALID_TIMESTAMP — a malformed, nonexistent (2027-02-29) or out-of-range base timestamp.

When to use this endpoint

Use Add to a timestamp when you need deterministic date math around an input moment. Common use cases include trial expiration, reminder scheduling, countdown targets, and generating future or past timestamps from a known base.

Request model

Pass one base timestamp (unix, unix_ms, or iso) or omit it to use the current request time. Then provide any combination of days, hours, minutes, and seconds; negative values subtract time.

Date math guidance

Use this endpoint when you want server-side consistency across clients. Store machine-readable values such as unix_ms for comparisons, then display the returned ISO or human string in the user's target context.

Elapsed since

GET /v1/time/elapsed

Time between a reference timestamp and now (or a compare timestamp), with direction (passed or left).

Parameters
  • unix— Reference timestamp as Unix seconds.
  • unix_ms— Reference timestamp as Unix milliseconds.
  • iso— Reference timestamp as ISO 8601.
  • source_tz— Interpret a local iso= reference as wall time in this IANA zone.
  • source_ip— Interpret a local iso= reference using this IP address timezone.
  • source_lat— Latitude hint for local iso=. Pair with source_lon.
  • source_lon— Longitude hint for local iso=. Pair with source_lat.
  • source_offset— Interpret a local iso= reference against a fixed UTC offset.
  • compare_unix— Optional comparison timestamp as Unix seconds instead of now.
  • compare_unix_ms— Optional comparison timestamp as Unix milliseconds instead of now.
  • compare_iso— Optional comparison timestamp as ISO 8601 instead of now.
  • compare_source_tz— Interpret a local compare_iso= timestamp as wall time in this IANA zone.
  • compare_source_ip— Interpret a local compare_iso= timestamp using this IP address timezone.
  • compare_source_lat— Latitude hint for local compare_iso=. Pair with compare_source_lon.
  • compare_source_lon— Longitude hint for local compare_iso=. Pair with compare_source_lat.
  • compare_source_offset— Interpret a local compare_iso= timestamp against a fixed UTC offset.
  • tz— Accepted for symmetry: "now" is the same instant in every zone, so this does not change the result. Cannot be combined with compare_*.
  • ip— Accepted for symmetry; does not change the result. Cannot be combined with compare_*.
  • lat— Accepted for symmetry with lon; does not change the result.
  • lon— Accepted for symmetry with lat; does not change the result.
  • offset— Accepted for symmetry; does not change the result. Cannot be combined with compare_*.
  • auto_tz— Accepted for symmetry; does not change the result.
  • format— Duration template using %days %hours %minutes %seconds for an additional `formatted` field.
  • business_days— Set true (or 1 / yes) to include a business_days count in the response. Counted by calendar date, start included, end excluded.
  • holiday_country— Holiday calendar: one of the 249 countries with holiday calendars (ISO 3166-1 alpha-2, e.g. FR, SA, CH), or a combined code such as CH-ZH or FR-6AE. Requires business_days=true. Full list: /docs#holiday-calendars.
  • holiday_subdivision— Subdivision code for the country, e.g. ENG (GB), ZH (CH), MH (IN), 01 (FI), 6AE (FR); digits and leading zeros are part of the code. Requires holiday_country and business_days=true. Full list: /docs#holiday-calendars.
  • sign— Set true for a signed response.
Code sample
curl "https://api.timelogicapi.com/v1/time/elapsed?unix=1711300000" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
{
  "seconds": 525695,
  "minutes": 8761,
  "hours": 146,
  "days": 6,
  "human": "146 hours, 1 minute, 36 seconds",
  "direction": "passed"
}
Additional endpoint notes

Exactly one input form is required (unix, unix_ms, or iso).

.https://api.timelogicapi.com/v1/time/elapsed?iso=2026-04-30T16:42:11Z
.https://api.timelogicapi.com/v1/time/elapsed?unix=1711300000

# Compare two timestamps instead of using now
.https://api.timelogicapi.com/v1/time/elapsed?iso=2026-01-01T00:00:00Z&compare_iso=2026-01-02T00:00:00Z
# → "seconds": 86400, "direction": "passed"

# Business days between the reference and the compare timestamp
.https://api.timelogicapi.com/v1/time/elapsed?iso=2026-01-02T00:00:00Z&compare_iso=2026-04-30T00:00:00Z&business_days=true&holiday_country=FR
# → "business_days": 83

direction is passed if the reference is before the compared instant (now, or compare_*), and left if it is after. When the two instants are equal, elapsed returns seconds: 0 with direction: "passed" (/v1/time/diff returns same in that case).

seconds, minutes, hours and days are each the whole duration in that unit, and format placeholders (%days %hours %minutes %seconds) are totals, not remainders. human is written in hours, minutes and seconds.

Business days follow the same rules as diff: calendar dates, start included, end excluded, unsigned. The reference date is taken in its source_* zone and the compare date in its compare_source_* zone when given, otherwise in UTC. See Diff & business days.

The target selectors (tz, ip, lat/lon, offset, auto_tz) are accepted but cannot change the result, because "now" is the same instant everywhere. Combining one with a compare_* timestamp returns 400 AMBIGUOUS_TARGET.

Common errors

  • 400 INVALID_TIMESTAMP — no input timestamp provided, or a timestamp that is malformed, not a real date, or out of range.
  • 400 AMBIGUOUS_TARGET — more than one reference form, or compare_unix/compare_unix_ms/compare_iso combined with a target selector ("Provide either compare_unix/compare_unix_ms/compare_iso or a compare target selector, but not both.").
  • 400 INVALID_PARAMETER — a country with no holiday calendar ("Unsupported holiday calendar."), an unknown holiday_subdivision ("Unknown holiday_subdivision 'XX' for country DE."; FI-1 must be written FI-01), a malformed code, or a business-day range outside 1900–2100 with a calendar ("Holiday calendar coverage is only available for years 1900-2100."). The 249 countries and their subdivision codes: Holiday calendars.

When to use this endpoint

Use Elapsed since to show how much time has passed since a timestamp or how much time is left until a future timestamp. It is a compact fit for status pages, billing windows, event countdowns, and audit interfaces.

Request model

Provide exactly one reference timestamp as unix, unix_ms, or iso. The endpoint compares that reference against the current request time, or against an optional compare_unix / compare_unix_ms / compare_iso timestamp, and returns duration fields plus a human-readable string.

Direction semantics

The direction field tells you whether the reference is already passed or still left (equal instants count as passed). Use that value to label UI states without reimplementing comparison logic in the browser.

Calendar projection

GET /v1/time/calendar

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

Parameters
  • unix— Input timestamp as Unix seconds. Defaults to now.
  • unix_ms— Input timestamp as Unix milliseconds.
  • iso— Input timestamp as ISO 8601. A local value without an offset needs a source_* hint, or it is read as UTC.
  • source_tz— Interpret a local iso= as wall time in this IANA zone.
  • source_ip— Interpret a local iso= using this IP address timezone.
  • source_lat— Latitude hint for local iso=. Pair with source_lon.
  • source_lon— Longitude hint for local iso=. Pair with source_lat.
  • source_offset— Interpret a local iso= against a fixed UTC offset.
  • tz— Project into this IANA zone.
  • ip— Project into the zone of this IP.
  • lat— Latitude, pair with lon.
  • lon— Longitude.
  • offset— Project against a fixed UTC offset (URL-encode + as %2B).
  • auto_tz— Set true to project into the request IP's timezone.
  • week— 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— strftime pattern for an extra `formatted` field.
  • sign— Set true for a signed response.
Code sample
curl "https://api.timelogicapi.com/v1/time/calendar?tz=Europe/Paris&week=true" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample 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).

DST status

GET /v1/time/dst

Whether a zone is currently observing daylight saving time, plus the resolved local time.

Parameters
  • tz— IANA timezone.
  • ip— IPv4 or IPv6 address.
  • lat— Latitude, pair with lon.
  • lon— Longitude.
  • offset— Fixed UTC offset (URL-encode + as %2B). Always returns dst_active=false.
  • auto_tz— Set true to use the request IP's timezone.
  • format— strftime pattern for an additional `formatted` field, e.g. %Y-%m-%d %H:%M:%S.
  • next— Set true to include next_transition: the next UTC offset change, or null if none is scheduled.
  • sign— Set true for a signed response.
Code sample
curl "https://api.timelogicapi.com/v1/time/dst?tz=Europe/Paris" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
{
  "unix": 1778093027,
  "unix_ms": 1778093027004,
  "utc": "2026-05-06T18:43:47Z",
  "iso_local": "2026-05-06T20:43:47+02:00",
  "rfc2822": "Wed, 06 May 2026 20:43:47 +0200",
  "human": "May 6, 2026, 8:43 PM Europe/Paris",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": "Europe/Paris",
  "dst_active": true
}
Additional endpoint notes
.https://api.timelogicapi.com/v1/time/dst?tz=Europe/Paris
.https://api.timelogicapi.com/v1/time/dst?ip=8.8.8.8

Use at most one selector family. If no selector is provided, the response is for UTC (iso_local and timezone are null).

Always "now". This endpoint reports DST for the current request time only. It takes no timestamp input, and unix, unix_ms or iso are ignored if sent. To ask whether DST was active at another moment, call /v1/time/convert for that instant and compare its offset with the zone's standard offset.

next_transition. With next=true the response adds next_transition:

{
  "timezone": "America/New_York",
  "dst_active": true,
  "next_transition": "2026-11-01T02:00:00-04:00"
}
  • It is a string: the instant of the next UTC offset change, written in the offset that applies before the change. The new offset is not returned; call convert just after the transition if you need it.
  • It is null when no future offset change is scheduled (for example Asia/Tokyo), for offset targets, and when no selector is given.
  • The key is absent unless next=true.
  • It tracks UTC offset changes only. A zone can change dst_active without an offset change: under tzdata 2026e, America/Vancouver moves from PDT (DST) to permanent MST at the same −07:00 on November 1, 2026, so dst_active becomes false with no next_transition reported.
  • dst_active follows tzdata, including negative DST: Europe/Dublin reports true in winter.

When to use this endpoint

Use DST status to determine whether a resolved target is currently observing daylight saving time. It is best for timezone diagnostics, support tooling, calendar UI warnings, and systems that need to explain offset changes.

Request model

Choose at most one selector family: tz, ip, lat + lon, offset, or auto_tz=true. If no selector is provided, the response defaults to UTC. Fixed offsets are not zones and therefore always return dst_active=false because a numeric offset has no daylight-saving rules.

Display guidance

Pair dst_active with timezone, iso_local, and utc when showing users why local time differs from a standard offset. This is especially helpful around spring-forward and fall-back transitions.

Resolve timezone

GET /v1/timezone

Canonical IANA timezone for a timezone name, IP, coordinate or offset, with current offset and DST flag.

Parameters
  • tz— IANA timezone to resolve directly.
  • ip— IPv4 or IPv6 (resolved via GeoLite2).
  • lat— Latitude. Pair with lon.
  • lon— Longitude.
  • offset— Fixed UTC offset (URL-encode + as %2B). Returns timezone null and the geographic zones currently at that offset in matching_zones.
  • auto_tz— Set true to resolve the request IP's timezone.
  • sign— Set true for a signed response.
Code sample
curl "https://api.timelogicapi.com/v1/timezone?ip=8.8.8.8" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
{
  "unix": 1778093027,
  "unix_ms": 1778093027712,
  "utc": "2026-05-06T18:43:47Z",
  "iso_local": "2026-05-06T20:43:47+02:00",
  "rfc2822": "Wed, 06 May 2026 20:43:47 +0200",
  "human": "May 6, 2026, 8:43 PM Europe/Paris",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": "Europe/Paris",
  "offset": 120,
  "dst": true
}
Additional endpoint notes

offset is the current UTC offset in minutes. timezone is the canonical IANA name. A selector is required: with none, the endpoint returns 400 MISSING_TARGET (unlike the time routes, which default to UTC).

.https://api.timelogicapi.com/v1/timezone?ip=8.8.8.8
.https://api.timelogicapi.com/v1/timezone?lat=48.8566&lon=2.3522
.https://api.timelogicapi.com/v1/timezone?tz=Europe/Stockholm
.https://api.timelogicapi.com/v1/timezone?offset=%2B05:30

Canonical names. tz is resolved to its canonical tzdata zone, so the name you get back can differ from the one you sent: Europe/Stockholm returns Europe/Berlin, Asia/Calcutta returns Asia/Kolkata, US/Eastern returns America/New_York, and UTC returns Etc/UTC. Names are matched case-insensitively.

Offset lookups. offset= returns "timezone": null and a matching_zones list of the zones whose current offset equals the one requested:

{
  "timezone": null,
  "offset": 330,
  "dst": false,
  "matching_zones": [
    { "timezone": "Asia/Colombo", "offset": 330, "dst": false },
    { "timezone": "Asia/Kolkata", "offset": 330, "dst": false }
  ]
}

Matches use today's offsets, so offset=-03:30 returns an empty list while St. John's is on −02:30. The list contains geographic zones only: UTC and Etc/* zones are intentionally excluded, so offset=%2B00:00 lists places such as Europe/London, Europe/Lisbon and Africa/Abidjan but not UTC. Use tz=UTC (or tz=Etc/UTC) when you want UTC itself.

Coordinates and IPs. Coordinates at sea return nautical zones such as Etc/GMT+8 (UTC−08:00; the sign is inverted by POSIX convention), and lat=0&lon=0 returns Africa/Abidjan. IP resolution uses MaxMind GeoLite2; private, reserved and loopback addresses (10.0.0.1, ::1) have no mapping and return 404 NOT_FOUND ("No timezone mapping found for the supplied IP address.").

DST flag. dst follows tzdata, including Ireland's negative DST: Europe/Dublin reports dst: true in winter at +00:00.

Common errors

  • 400 MISSING_TARGET — no selector.
  • 400 AMBIGUOUS_TARGET — more than one selector family.
  • 400 INVALID_PARAMETER — unknown timezone, malformed offset, or invalid coordinates. A comma-separated list is not supported here.
  • 404 NOT_FOUND — an IP address with no timezone mapping.

When to use this endpoint

Use Resolve timezone when you need to turn an IP address or latitude/longitude pair into a canonical IANA timezone. It is useful for onboarding, personalization, analytics enrichment, and timezone-aware defaults.

Request model

Provide exactly one of tz, ip, the lat + lon pair, offset, or auto_tz=true. The endpoint returns the resolved IANA name, current local time, UTC offset in minutes, and a DST flag for the resolved zone.

Accuracy guidance

Coordinate resolution is usually the most explicit option. IP-based resolution is convenient for defaults, but users should be able to override it when precision matters. For JavaScript and Python examples of every selector, see the time zone API guide.

Embeddable clock

GET /v1/time/clock

Returns a self-bootstrapping HTML fragment (host div + JSON config + CSS/JS includes) that renders a live clock.

Parameters
  • style(required)— One of 30 named styles. See list below.
  • tz— Target IANA timezone.
  • ip— Target via IP address.
  • lat— Target latitude. Pair with lon.
  • lon— Target longitude.
  • offset— Target fixed UTC offset (URL-encode + as %2B).
  • unix— Pin the clock to a specific Unix-second instant.
  • unix_ms— Pin the clock to a specific Unix-millisecond instant.
  • iso— Pin the clock to a specific ISO 8601 instant.
  • source_tz— Interpret a local iso= against this IANA zone.
  • source_ip— Interpret a local iso= in the timezone of this IP address.
  • source_lat— Interpret a local iso= at these coordinates. Pair with source_lon.
  • source_lon— Longitude for source_lat.
  • source_offset— Interpret a local iso= at this fixed offset (URL-encode + as %2B).
  • format— strftime pattern for digital styles; defaults to %H:%M:%S. Ignored by analog styles.
Code sample
curl "https://api.timelogicapi.com/v1/time/clock?tz=Europe/Paris&style=analog-station" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
Sample response
<div id="clock-...-1" class="timelogic-clock-host" data-timelogic-clock data-clock-config-id="clock-...-1-config"></div>
<script type="application/json" id="clock-...-1-config">
{
  "version": "v1",
  "style": "analog-station",
  "styleDefinition": { "family": "analog", "renderer": "svg", "...": "..." },
  "unix_ms": 1793043512703,
  "offset_minutes": 60,
  "timezone": "Europe/Paris",
  "timezone_label": "Europe/Paris",
  "format": null,
  "refresh": { "path": "https://api.timelogicapi.com/v1/time/current", "selector": { "kind": "tz", "tz": "Europe/Paris" } }
}
</script>
<link rel="stylesheet" href="https://api.timelogicapi.com/v1/time/clock/assets/v1/clock.css">
<script src="https://api.timelogicapi.com/v1/time/clock/assets/v1/clock.js"></script>
Additional endpoint notes

style is required and must be one of these 30 names:

Analog — analog-station, analog-aviation, analog-bauhaus, analog-graphite, analog-arctic, analog-brass, analog-marine, analog-grid, analog-slate, analog-executive.

Digital — digital-segment-red, digital-segment-amber, digital-segment-ice, digital-terminal-green, digital-terminal-white, digital-broadcast, digital-dashboard, digital-control-room, digital-slate, digital-onyx, digital-frost, digital-card, digital-glass, digital-matrix, digital-timetable, digital-split-flap, digital-cyan, digital-emerald, digital-monolith, digital-minimal.

curl "https://api.timelogicapi.com/v1/time/clock?tz=Europe/Paris&style=analog-station" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

The response is text/html (uncached, Cache-Control: no-store). Drop the entire snippet into a page; the asset URLs are absolute, so it works on any host. The included JS upgrades the host <div> and keeps the clock ticking locally from unix_ms and offset_minutes.

How the clock keeps time. The clock is synced once, from the snippet. It does not call the API again: periodic refresh against refresh.path is off by default, because that request needs an API key, which must not be exposed in the page. As a result, a page left open across a daylight-saving change keeps its original UTC offset and shows the wrong hour until the snippet is fetched again. Fetch a fresh snippet on every page load (from your server, which holds the key); for pages that stay open for days, reload the snippet periodically or set refresh.enabled = true in the config and point refresh.path at a same-origin proxy that adds your key.

Pinned clocks. unix, unix_ms or iso set the clock's starting instant, not a frozen time: the clock starts at that instant and keeps ticking forward from the moment the page loads. A local iso is interpreted with source_tz, source_ip, source_lat+source_lon or source_offset.

Format. Digital styles render format (default %H:%M:%S; same directives as the JSON routes, see Selectors). Analog styles ignore it and return "format": null.

This route is single-target only: no comma-separated selectors ("Bulk selectors are not supported on /v1/time/clock.") and no auto_tz. sign is not supported. There are no labeling or display parameters beyond style and format; timezone_label is always the resolved zone name, and unknown parameters such as label= are ignored.

Common errors

  • 400 INVALID_PARAMETER — missing or unknown style. The error body lists all valid_styles.

When to use this endpoint

Use Embeddable clock when you want TimeLogic to return a ready-to-render live clock fragment for websites, internal dashboards, landing pages, or customer portals without building the display logic yourself.

Request model

Select a required style, then choose the time target with a timezone, IP, coordinates or fixed offset, and optionally a starting timestamp. format (digital styles only) is the one presentation option.

Embedding guidance

Treat the returned fragment as presentation output. For application logic, use JSON endpoints such as current time or convert time; for visual widgets, the clock endpoint keeps markup and behavior together.

Public signing key (JWKS)

GET /.well-known/time-api-public-key

JWKS document containing the Ed25519 public key used to verify signed responses.

Parameters
  • kid— Return only the key with this kid. An unknown kid returns 404 NOT_FOUND.
Code sample
curl "https://api.timelogicapi.com/.well-known/time-api-public-key"
Sample response
{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "alg": "EdDSA",
      "use": "sig",
      "key_ops": ["verify"],
      "ext": true,
      "kid": "ed25519-2026-07-19",
      "x": "LUuZFwpGBGvPS-4vJdLM21_IreJqea-aoyXRhGfH3dI"
    }
  ]
}
Additional endpoint notes

Returned as application/json. This route is public: it needs no API key. The full URL is https://api.timelogicapi.com/.well-known/time-api-public-key (the path does not exist on the website host). Cache the JWKS and rotate when a new kid appears.

Add ?kid=ed25519-2026-07-19 to fetch one key. An unknown kid returns 404 NOT_FOUND ("No signing key found for kid 'nope'.").

When you request a signed response (sign=true), the API returns these headers:

  • X-TimeLogic-Key-Id — JWKS kid to look up. (On unsigned responses this header carries your API key ID instead.)
  • X-TimeLogic-Signature-Alg — currently Ed25519.
  • X-TimeLogic-Signature-Timestamp — Unix seconds when the signature was produced.
  • X-TimeLogic-Content-SHA256 — base64 SHA-256 of the response body.
  • X-TimeLogic-Signature-Input — Base64URL-encoded exact UTF-8 v1 envelope.
  • X-TimeLogic-Signature — base64 Ed25519 signature over the decoded X-TimeLogic-Signature-Input bytes.

Verify by recomputing the SHA-256 of the body, comparing it to content-sha256 inside the decoded envelope, and validating the Ed25519 signature with the JWKS key matching the envelope kid. Do not rebuild the envelope.

When to use this endpoint

Use Public signing key (JWKS) when you request signed TimeLogic responses and need to verify response integrity. It is intended for clients that require tamper-evidence across proxies, logs, or downstream services.

Request model

Fetch the JWKS document and cache it by kid. When a signed API response arrives, decode X-TimeLogic-Signature-Input and use its kid to select the correct public key before verifying the signature.

Verification guidance

The v1 envelope signs status, method, origin-form path plus query, timestamp, and body hash. It deliberately excludes scheme, host, and Content-Type, so clients can verify a response through either the RapidAPI proxy host or gateway host without rebuilding host-dependent bytes. Rotate cached keys when a new kid appears.

Try it on the site: the signed-response verifier runs entirely in your browser — paste a response body and the X-TimeLogic-* headers, pick the kid, and check the signature without sending anything to a server.