Skip to content
Endpoint guide

Embeddable clock

GET /v1/time/clockOpenAPI YAML

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

What do I need to send?

Required / choose this first

style is required. Choose one of the named analog or digital styles.

Optional

Choose one target selector and an optional timestamp to pin the clock.

Rule: This endpoint returns text/html and does not support sign or bulk selectors.

NameNeeded?Use it for
styleRequiredOne of 30 named styles. See list below.
tzChoose one targetTarget IANA timezone.
ipChoose one targetTarget via IP address.
latPair parameterTarget latitude. Pair with lon.
lonPair parameterTarget longitude.
offsetChoose one targetTarget fixed UTC offset (URL-encode + as %2B).
unixChoose one inputPin the clock to a specific Unix-second instant.
unix_msChoose one inputPin the clock to a specific Unix-millisecond instant.
isoChoose one inputPin the clock to a specific ISO 8601 instant.
source_tzConditional hintInterpret a local iso= against this IANA zone.
source_ipConditional hintInterpret a local iso= in the timezone of this IP address.
source_latPair parameterInterpret a local iso= at these coordinates. Pair with source_lon.
source_lonPair parameterLongitude for source_lat.
source_offsetConditional hintInterpret a local iso= at this fixed offset (URL-encode + as %2B).
formatOptionalstrftime pattern for digital styles; defaults to %H:%M:%S. Ignored by analog styles.

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/clock?tz=Europe/Paris&style=analog-station" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

Example 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.

Frequently asked questions

How do I embed a live clock on my website?

Fetch GET /v1/time/clock?tz=Europe/Paris&style=analog-station from your server and drop the returned HTML snippet into the page. The asset URLs are absolute, so it works on any host.

Which clock styles are available?

30 styles: 10 analog (such as analog-station and analog-bauhaus) and 20 digital (such as digital-segment-red and digital-split-flap). style is required.

Does the clock call the API again?

No. It syncs once from the snippet and keeps ticking locally, so the API key never reaches the browser. Fetch a fresh snippet on page load, especially across daylight saving changes.