Direct API documentation

1. Create a direct key at /signup — the Free plan starts without a card.
2. Keep the key in your server environment as TIMELOGIC_API_KEY.
3. Make your first request:

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

If your integration already uses RapidAPI, use the RapidAPI compatibility guide and keep its marketplace headers.

Direct API requests use one Bearer key. Keep it server-side; never embed it in browser code or commit it to source control.

Looking for the marketplace integration? See the RapidAPI docs or RapidAPI reference.

Authorization: Bearer YOUR_TIMELOGIC_API_KEY

You can also send the key in X-API-Key:

X-API-Key: YOUR_TIMELOGIC_API_KEY

For constrained clients, the gateway also accepts an api_key query parameter:

curl "https://api.timelogicapi.com/v1/time/current?tz=Europe/Paris&api_key=$TIMELOGIC_API_KEY"

Query-string credentials can be copied, logged, or included in referrers. Prefer the Authorization or X-API-Key header whenever possible, and never place a key in a public browser link.

The direct base URL is https://api.timelogicapi.com. RapidAPI remains available as a separate transport with its own X-RapidAPI-Key and X-RapidAPI-Host headers.

Enterprise customers may use custom auth schemas (mTLS, JWT, IP allowlists) on a dedicated hostname.

Most endpoints accept exactly one selector family per request to identify the location or moment you care about:

• tz — IANA timezone name, e.g. Europe/Paris
• ip — IPv4 or IPv6 address (resolved via MaxMind GeoLite2)
• lat + lon — coordinates in decimal degrees
• offset — fixed UTC offset, URL-encode + as %2B (e.g. offset=%2B02:00)

Mixing families in the same request returns 400 AMBIGUOUS_TARGET. An invalid IANA name returns 400 INVALID_PARAMETER.

On /v1/time/convert, /v1/time/calendar, /v1/time/clock and /v1/time/add, the input timestamp uses a separate set of forms: unix=…, unix_ms=…, or iso=… (optionally paired with a source_tz / source_ip / source_lat+source_lon / source_offset hint when iso is local). The target is then chosen with the standard selector family above.

/v1/time/current and /v1/time/convert support bulk mode by passing a comma-separated list to one selector (tz, ip, or offset). The response is an array in input order.

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

# convert one instant into three target offsets
curl "https://api.timelogicapi.com/v1/time/convert?unix=1711300000&offset=-04:00,%2B00:00,%2B09:00" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY" 

/v1/time/clock is single-target only and rejects comma-separated selectors.

Set sign=true exactly on a supported JSON route to receive a cryptographically signed response. Supported routes are current, convert, diff, add, calendar, DST, elapsed, and timezone. /v1/time/clock does not support signing.

sign=false, a bare ?sign, or repeated sign values do not request a signature.

The JSON body is unchanged. The gateway adds these response headers:

What is signed

Decode X-TimeLogic-Signature-Input as Base64URL UTF-8. For v1 it contains exactly these newline-separated fields:

v1
kid:<key id>
status:<HTTP status>
method:<HTTP method>
path:<origin-form path and query>
timestamp:<Unix seconds>
content-sha256:<standard-base64 SHA-256>

The path includes the query string, including sign=true. For example, it can be /v1/time/current?tz=Europe%2FLondon&sign=true.

Host and proxy behavior

The envelope does not include the scheme, host, or Content-Type. It signs only the origin-form path and query, status, method, timestamp, and body hash.

This is intentional: a request can pass through the RapidAPI hostname and the gateway hostname without making verification depend on either host. Proxies may also normalize Content-Type. Do not rebuild a signing input from the URL host or a response content type; decode and verify the X-TimeLogic-Signature-Input header exactly as received.

Verify a response

1. Keep the response body exactly as received and compute its SHA-256.
2. Decode X-TimeLogic-Signature-Input, confirm its content-sha256 matches the body hash, and use its kid to select the matching public JWK.
3. Verify X-TimeLogic-Signature over the decoded envelope bytes. Do not reconstruct the envelope yourself.
4. Optionally compare the mirrored kid, timestamp, and content-hash headers to the values inside the envelope.

Fetch the public keys from:

GET https://api.timelogicapi.com/.well-known/time-api-public-key

Cache keys by kid; retained historical keys may remain available after rotation. The browser verifier performs these checks locally - paste a complete curl -i response and no response data is uploaded.

Use /v1/time/diff for duration math between two specifier-encoded instants and /v1/time/elapsed for "since now" calculations.

from and to on /v1/time/diff are embedded specifiers — the value itself is a key=value pair: from=unix=1711300000, from=iso=2026-04-16T09:00:00, from=now, etc.

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" 

Add business_days=true to include a business_days count in the response. Pair it with holiday_country (ISO 3166-1 alpha-2) to subtract public holidays, and optionally holiday_subdivision (e.g. ENG, CA) for regional calendars. Not every country code is supported by the upstream calendar — unsupported codes return 400 INVALID_PARAMETER ("Unsupported holiday calendar").

/v1/time/clock returns a self-bootstrapping HTML fragment: a host <div>, a JSON config <script>, and <link>/<script> tags pointing at the hosted CSS and JS bundle. Drop the entire snippet anywhere on your page.

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

style is required and must be one of 30 named styles (10 analog + 20 digital). See the endpoint reference for the full list. Responses are uncached so each fetch reflects the current request.

Errors are JSON with a stable shape:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid timezone.",
    "details": { "tz": "Not/AZone" }
  },
  "request_id": "3534e3fe-f916-4d44-a50b-8f92a74074c4"
}

Common codes:

• INVALID_PARAMETER — bad value (timezone, offset format, strftime directive, unsupported holiday calendar, missing clock style).
• INVALID_TIMESTAMP — required input timestamp missing on /v1/time/elapsed (and similar reference-time inputs).
• MISSING_TARGET — no target selector supplied where one is required (e.g. /v1/time/convert with no tz/ip/lat+lon/offset/utc).
• AMBIGUOUS_TARGET — more than one selector family or input form supplied, or a comma-separated bulk selector combined with another target selector (including utc=true).
• 429 — plan quota exceeded; retry after the Retry-After header.
• 5xx — upstream issue; retry with backoff.

Every response includes an X-Request-Id header — quote it in support tickets.

Rate limits depend on your plan — see Pricing.