Skip to content

Direct API documentation

Everything you need to integrate the direct TimeLogic API: authentication, selectors, bulk requests, signed responses, errors, and endpoint-specific guides. RapidAPI compatibility remains available separately.

Endpoint guides

Read request details and examples for a specific endpoint, or browse them all.

View all endpoints

Getting started

  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.

Authentication

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.

Send the key in one place. If you send more than one credential, the gateway reads them in this order: Authorization, then X-API-Key, then api_key. The same key repeated in several places is accepted; two different keys return 401 UNAUTHORIZED with Conflicting API key credentials. This matters when an HTTP client sets a default header and your code also adds api_key.

Missing or unknown keys return 401 UNAUTHORIZED (Missing API key credentials. or Invalid API key credentials.). A key whose subscription is inactive returns 403 SUBSCRIPTION_INACTIVE. Every route needs a key except the public signing key (/.well-known/time-api-public-key) and the clock's static assets.

Browsers: the API sends CORS headers (methods GET, HEAD, OPTIONS), but a key in browser code is visible to anyone who opens the page. Call the API from your server, or through a server-side proxy that adds the key.

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.

Selectors

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)
  • auto_tz=true: the timezone of the caller's IP address, as seen by the edge network (accepted on every route that takes a target except /v1/time/clock)

Mixing families in the same request returns 400 AMBIGUOUS_TARGET ("Provide only one of tz, ip, lat/lon, offset, auto_tz."). On /v1/time/convert and /v1/time/add, utc=true is a sixth target and cannot be combined with the others either; the error message lists only the five selector families, but utc=true counts as one.

On /v1/time/convert, /v1/time/calendar, /v1/time/clock, /v1/time/add and /v1/time/elapsed, 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.

Timezone names

  • Names are matched case-insensitively: tz=america/new_york works and the response uses the canonical spelling (America/New_York).
  • Links and aliases are resolved to their canonical tzdata zone, so the returned timezone can differ from the name you sent: Europe/Stockholm returns Europe/Berlin, Asia/Calcutta returns Asia/Kolkata, US/Eastern returns America/New_York, and UTC returns Etc/UTC. Always render the returned timezone, not your input.
  • Etc/GMT±N zones use the POSIX sign convention, which is the reverse of what most people expect: Etc/GMT+5 is UTC−05:00. URL-encode the + (tz=Etc/GMT%2B5).
  • An unknown name returns 400 INVALID_PARAMETER ("Invalid timezone.").

Offsets

  • The only accepted form is ±HH:MM, for example %2B05:30 or -03:00. +0530, +5 and +05 are rejected with 400 INVALID_PARAMETER ("Invalid offset. Use ±HH:MM.").
  • An unencoded + in a query string is read as a space, so offset=+02:00 fails with the same message. Send %2B02:00.
  • An offset target has no IANA zone: timezone is null and human ends with a label such as UTC+02:00.
  • /v1/timezone?offset=… lists the real places currently at that offset in matching_zones. It returns geographic zones only: UTC and Etc/* zones are intentionally left out, so offset=%2B00:00 lists places such as Europe/London, Europe/Lisbon and Africa/Abidjan. Use tz=UTC (or tz=Etc/UTC) when you want UTC itself.

No selector, and utc=true

With no selector, /v1/time/current, /v1/time/dst, /v1/time/calendar and /v1/time/add answer in UTC, and the response has "iso_local": null and "timezone": null (the human text ends in UTC). utc=true on convert and add gives the same shape. /v1/time/convert and /v1/timezone need a target and return 400 MISSING_TARGET without one.

Input timestamps

  • unix is whole seconds (1711300000.5 is rejected) and unix_ms whole milliseconds. Negative values (before 1970) are fine.
  • Every timestamp input, and every computed result, must fall between 0001-01-01T00:00:00Z and 9999-12-31T23:59:59Z (unix -62135596800 to 253402300799). Values outside that range return 400 INVALID_TIMESTAMP with the supported range in the message and min_unix / max_unix in details.
  • Accepted iso shapes: 2026-04-16T09:00:00Z, 2026-04-16T09:00:00+05:30, an offset with seconds (1900-06-01T12:09:21+00:09:21, the form iso_local uses for old local-mean-time offsets, so an iso_local value can be sent back as input), fractional seconds (2026-04-16T09:00:00.789Z, kept in unix_ms), a space instead of T (2026-04-16 09:00:00Z, URL-encoded), a local time with no offset (2026-04-16T09:00:00), and a date alone (2026-04-16, read as 00:00). Basic format (20260416T090000Z) and offsets without a colon (+0530) return 400 INVALID_TIMESTAMP.
  • Dates must exist: 2027-02-29 or 2026-04-31 return 400 INVALID_TIMESTAMP ("Invalid ISO timestamp: 2027-02-29 is not a valid calendar date.") instead of rolling over to the next month.
  • A local iso (no Z or offset) is interpreted in the zone given by its source_* hint. Without a hint it is read as UTC, with no warning.
  • Daylight-saving edges for local times: a wall time that does not exist (inside a spring-forward gap, such as 2026-03-08T02:30:00 in America/New_York) returns 400 INVALID_TIMESTAMP ("Local time could not be resolved for the requested timezone."). A wall time that happens twice (fall-back, such as 2026-11-01T01:30:00 in New York) resolves to the first occurrence (01:30 EDT, 05:30Z); there is no parameter to choose the second. Send an explicit offset when you need the later one.

Boolean flags

Flags such as sign, business_days, week, next, utc and auto_tz are turned on by true, 1 or yes, in any letter case. Any other value (false, 0, no, an empty value, a bare ?sign, or an unrecognized word such as maybe) leaves the flag off without an error.

Unknown parameters

Parameters the endpoint does not know are ignored, not rejected. A typo such as day=1 (for days) or time=… (for iso) silently has no effect, so check your parameter names against each endpoint's reference.

Other response conventions

  • day_number counts from Sunday: 1 = Sunday, 2 = Monday … 7 = Saturday. (This is neither ISO 8601, where Monday is 1, nor JavaScript's getDay(), where Sunday is 0.)
  • Coordinates at sea resolve to nautical zones such as Etc/GMT+8 (UTC−08:00, with the POSIX sign); lat=0&lon=0 resolves to Africa/Abidjan.
  • dst follows tzdata, including negative DST: Europe/Dublin reports dst: true in winter (at +00:00) and false in summer. That is tzdata's model for Ireland, not an error.

format

format adds a formatted field rendered with a strftime-style pattern. The supported directives are:

%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 %%

The flags - (no padding), _ (space padding) and 0 (zero padding) work on the numeric directives, for example %-d. Any other directive (for example %U, %f or %Q), or a trailing %, returns 400 INVALID_PARAMETER naming the directive, with the supported list in details.supported. Use %% for a literal percent sign.

%Z prints the IANA zone name (Europe/London), not an abbreviation such as GMT or BST. For an offset target it prints a label such as UTC+02:00, and UTC when there is no target. %z prints +0100 and %:z prints +01:00.

/v1/time/diff and /v1/time/elapsed use their own duration placeholders instead (see their reference pages).

Bulk mode

/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"

Rules:

  • At most 10 values per request. More returns 400 INVALID_PARAMETER ("Bulk selector 'tz' accepts at most 10 values.").
  • Any comma turns the request into a bulk request, even a trailing one: tz=Europe/Paris, returns a one-element array, not an object. Empty items are dropped.
  • lat/lon are never bulk: lat=48.85,35.6&lon=2.35,139.6 returns 400 INVALID_PARAMETER ("Invalid coordinates.").
  • A bulk selector cannot be combined with another target selector, including utc=true (400 AMBIGUOUS_TARGET).

Partial failures. A bulk call returns HTTP 200 even when some items fail. A failed item takes the place of its payload as an object with the input value, the error and the request ID:

[
  { "unix": 1711300000, "timezone": "Europe/Paris", "...": "..." },
  {
    "item": "Not/AZone",
    "error": { "code": "INVALID_PARAMETER", "message": "Invalid timezone.", "details": { "tz": "Not/AZone" } },
    "request_id": "3534e3fe-f916-4d44-a50b-8f92a74074c4"
  }
]

Check each element for an error key. Item errors have no timestamp field.

Single-target routes. All other routes take one target. A comma-separated value there is read as one name and fails as such (for example 400 INVALID_PARAMETER "Invalid timezone." on add, dst, calendar or timezone); /v1/time/clock answers "Bulk selectors are not supported on /v1/time/clock."

Signed responses

Set sign=true (or 1 / yes, in any letter case) 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. The WorldTimeAPI-compatible routes accept sign=true as well, on both JSON and .txt responses, with the body left byte-identical.

sign=false, any other value (for example sign=maybe), a bare ?sign, or repeated sign values do not request a signature, and no error is returned.

Error responses are signed too: a 400 such as tz=Not/AZone&sign=true carries the same signature headers, and so does a bulk response.

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

HeaderMeaning
X-TimeLogic-Key-IdJWKS kid for the public key that verifies this response. On unsigned responses the same header carries the ID of your API key instead (see Errors & rate limits).
X-TimeLogic-Signature-AlgSignature algorithm: Ed25519.
X-TimeLogic-Signature-TimestampUnix seconds used in the envelope.
X-TimeLogic-Content-SHA256Standard-base64 SHA-256 of the exact response body bytes.
X-TimeLogic-Signature-InputBase64URL encoding of the exact UTF-8 v1 envelope that was signed.
X-TimeLogic-SignatureStandard-base64 Ed25519 signature over the decoded Signature-Input bytes.

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. The gateway writes this path in its own normalized, percent-encoded form, so it may not match the bytes you sent (tz=Europe/London becomes tz=Europe%2FLondon). An api_key query parameter is removed from the signed path. Compare the path semantically if you need to; verify the decoded header bytes exactly as received.

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

This route needs no API key. Add ?kid=<kid> to fetch a single key; an unknown kid returns 404 NOT_FOUND. 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.

→
Try it now: Open the signed-response verifier - verify any signed response in your browser, plus browse the full key registry.

Diff & business days

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, such as from=unix=1711300000, from=iso=2026-04-16T09:00:00, or from=now.

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"

This returns "business_days": 83.

Add business_days=true to include a business_days count in the response. Pair it with holiday_country to subtract public holidays: any of the 249 countries with holiday calendars (862 calendars including subdivisions), as an ISO 3166-1 alpha-2 code in any letter case. Add holiday_subdivision for a regional calendar, for example holiday_country=GB&holiday_subdivision=ENG (England) or holiday_country=CH&holiday_subdivision=ZH (Zürich). holiday_country also accepts the combined ISO 3166-2 form, such as holiday_country=CH-ZH or holiday_country=US-CA; both forms select the same calendar.

How business days are counted

  • Days are counted by calendar date: the start date is included and the end date is excluded ([from, to)). A partial day counts as a whole day, so Monday 18:00Z to Tuesday 08:00Z is 1 business day.
  • The count is unsigned: swapping from and to gives the same number.
  • Weekends follow the calendar's country: Saturday and Sunday in 221 countries, Friday and Saturday in 18 (for example SA, EG, IL), Sunday only in 8, Friday only in IR, and Friday and Sunday in BN; a subdivision uses its country's weekend. Without holiday_country, weekends are Saturday and Sunday. Public holidays of the chosen calendar are not counted. The current weekend applies to every year, so historical weekend changes are not modelled (see Holiday calendars).
  • Which calendar date: when a timezone is known for an endpoint, its date is taken in that zone. On diff that is from_tz / to_tz (or the other from_* / to_* hints) for an iso endpoint, or the zone of a tz=, ip= or offset= specifier. On elapsed it is source_tz (or another source_* hint) for the reference and compare_source_* for the compared instant. With no zone, the UTC date is used. Example: from=iso=2026-01-12T08:00:00&from_tz=Asia/Tokyo&to=iso=2026-01-13T08:00:00&to_tz=Asia/Tokyo counts Monday Jan 12 in Tokyo and returns 1.

Supported holiday calendars

Holiday calendars cover 249 countries: 862 calendars in all, 249 national and 613 subdivision calendars in 35 countries. Holiday data covers the years 1900 to 2100.

  • Subdivision codes are the ISO 3166-2 suffixes used by python-holidays: 1 to 3 letters or digits, any letter case. Digits and leading zeros are part of the code: AT-9, FI-01, FR-971, FR-6AE (FI-1 is not FI-01).
  • Subdivisions exist for AD AM AR AT AU BA BO BQ BR BT CA CH CL CV DE ES FI FM FR GB GQ IN IT MO MY NI NO NZ PT SB SH ST SV TV US. For example: US has the 50 states, DC and 6 territories (USPS codes such as CA, NY, TX); IT has 107 provinces (RM Rome, MI Milan); IN has 36 states and union territories (MH Maharashtra); NZ has 17 regional anniversary calendars (AUK, CAN, WGN, ...); FR has 14 (6AE Alsace, 57 Moselle, the overseas regions and collectivities such as 971 Guadeloupe). IE has a national calendar only.
  • Every country, its weekend and all subdivision codes: Holiday calendars.

More results for the example range above (January 2 to April 30, 2026):

Calendarbusiness_days
holiday_country=FR83
holiday_country=FR-6AE (Alsace: Good Friday is a holiday)82
holiday_country=CH&holiday_subdivision=ZH82
holiday_country=IN-MH76
holiday_country=SA (Friday–Saturday weekend)79

Errors

  • A country with no holiday calendar returns 400 INVALID_PARAMETER ("Unsupported holiday calendar."), for example LK or ZZ, with holiday_country (and holiday_subdivision, when given) in details.
  • An unknown subdivision for a supported country returns 400 INVALID_PARAMETER, for example "Unknown holiday_subdivision 'XX' for country DE.", with holiday_country and holiday_subdivision in details. Codes must match exactly, so holiday_country=FI-1 returns "Unknown holiday_subdivision '1' for country FI." (the code is FI-01).
  • A malformed code returns 400 INVALID_PARAMETER ("Invalid holiday_country parameter." when the country part is not two letters, "Invalid holiday_subdivision parameter." when holiday_subdivision has characters other than letters, digits and hyphens).
  • holiday_country=US-CA together with a different holiday_subdivision returns 400 INVALID_PARAMETER ("holiday_subdivision conflicts with the subdivision in holiday_country.").
  • holiday_subdivision without holiday_country returns "holiday_subdivision requires holiday_country.", and either holiday parameter without business_days turned on returns "holiday_country and holiday_subdivision require business_days=true." (both 400 INVALID_PARAMETER).
  • A business-day count with a holiday calendar whose dates fall outside the covered years returns 400 INVALID_PARAMETER ("Holiday calendar coverage is only available for years 1900-2100.").
  • business_days is turned on by true, 1 or yes; any other value leaves it off and no business_days field is returned.

Holiday calendars

862 holiday calendars in 249 countries: 249 national calendars and 613 subdivision calendars in 35 countries. Holiday data covers the years 1900 to 2100 (python-holidays 0.107). Use a calendar with business_days=true on diff and elapsed.

Codes

  • holiday_country is the ISO 3166-1 alpha-2 code from the table, in any letter case.
  • A subdivision is selected with holiday_subdivision, or with the combined ISO 3166-2 form in holiday_country: holiday_country=CH-ZH and holiday_country=CH&holiday_subdivision=ZH are the same calendar.
  • Subdivision codes are the ISO 3166-2 suffixes used by python-holidays: 1 to 3 letters or digits, any letter case. Digits and leading zeros are part of the code and must match exactly: AT-9, FI-01, AD-02, FR-971, FR-6AE. FI-1 is not FI-01 and returns the unknown-subdivision error.
  • A subdivision calendar includes its country's national holidays and uses the country's weekend.

Weekends

Each calendar uses its country's current working week:

  • Saturday + Sunday: 221 countries (every country not listed below).
  • Friday + Saturday (18): AF BD BH DJ DZ EG IL IQ JO KW MR MV OM QA SA SD SY YE
  • Sunday (8): AI CD HK KN NE PY TK VE
  • Friday + Sunday (1): BN
  • Friday (1): IR

Coverage caveats

  • Historical weekends are not modelled. The current weekend is applied to every year from 1900 to 2100. For example, AE uses Saturday + Sunday for all years although its weekend was Friday + Saturday before 2022, and SA uses Friday + Saturday for all years although its weekend was Thursday + Friday before 2013.
  • Islamic-calendar holidays (Eid and others) are tabulated only through 2077. About 50 countries (for example SA, AE, EG, TR, ID, MY, PK, BD, MA, NG) count fewer holidays from about 2078 to 2100.
  • Hindu-calendar festivals: IN and its subdivisions have them only for 2001 to about 2035; NP and MU drop them after about 2035 to 2038.
  • Ukraine (UA) has no public holidays from 2023 on, following the martial-law rule in the holiday data.
  • BV, HM and IO (uninhabited territories) have no holidays; only weekends are excluded.
  • Years before a country's data starts count weekends only (for example before 1991 for several post-Soviet states, before 2023 for GW).
  • Bridge and transfer days decreed by governments (for example RU, BY, KZ, CN) are included only for years already announced.
  • JP has no holidays in 2100.
  • Not available: LK (holiday data ends in 2026) and named local calendars that have no ISO code (AU "NSW Western", BR "São Paulo Capital", CH "Stadt Zurich", DE "Augsburg", ES "Barcelona", IT "Andria", "Barletta", "Cesena", "Forli", "Pesaro", "Trani", "Urbino", NZ "South Canterbury"). They return "Unsupported holiday calendar." or the unknown-subdivision error.

All calendars

The same list is available as JSON at /content/holiday-calendars.json (weekdays numbered 0 = Sunday to 6 = Saturday).

CodeCountryWeekendSubdivisions
ADAndorraSat–Sun7
AEUnited Arab EmiratesSat–Sun—
AFAfghanistanFri–Sat—
AGAntigua and BarbudaSat–Sun—
AIAnguillaSun—
ALAlbaniaSat–Sun—
AMArmeniaSat–Sun11
AOAngolaSat–Sun—
AQAntarcticaSat–Sun—
ARArgentinaSat–Sun24
ASAmerican SamoaSat–Sun—
ATAustriaSat–Sun9
AUAustraliaSat–Sun8
AWArubaSat–Sun—
AXÅland IslandsSat–Sun—
AZAzerbaijanSat–Sun—
BABosnia and HerzegovinaSat–Sun3
BBBarbadosSat–Sun—
BDBangladeshFri–Sat—
BEBelgiumSat–Sun—
BFBurkina FasoSat–Sun—
BGBulgariaSat–Sun—
BHBahrainFri–Sat—
BIBurundiSat–Sun—
BJBeninSat–Sun—
BLSaint BarthélemySat–Sun—
BMBermudaSat–Sun—
BNBrunei DarussalamFri + Sun—
BOBoliviaSat–Sun9
BQBonaire, Sint Eustatius and SabaSat–Sun3
BRBrazilSat–Sun27
BSBahamasSat–Sun—
BTBhutanSat–Sun20
BVBouvet IslandSat–Sun—
BWBotswanaSat–Sun—
BYBelarusSat–Sun—
BZBelizeSat–Sun—
CACanadaSat–Sun13
CCCocos (Keeling) IslandsSat–Sun—
CDDemocratic Republic of the CongoSun—
CFCentral African RepublicSat–Sun—
CGRepublic of the CongoSat–Sun—
CHSwitzerlandSat–Sun26
CICôte d'IvoireSat–Sun—
CKCook IslandsSat–Sun—
CLChileSat–Sun16
CMCameroonSat–Sun—
CNChinaSat–Sun—
COColombiaSat–Sun—
CRCosta RicaSat–Sun—
CUCubaSat–Sun—
CVCabo VerdeSat–Sun22
CWCuraçaoSat–Sun—
CXChristmas IslandSat–Sun—
CYCyprusSat–Sun—
CZCzechiaSat–Sun—
DEGermanySat–Sun16
DJDjiboutiFri–Sat—
DKDenmarkSat–Sun—
DMDominicaSat–Sun—
DODominican RepublicSat–Sun—
DZAlgeriaFri–Sat—
ECEcuadorSat–Sun—
EEEstoniaSat–Sun—
EGEgyptFri–Sat—
EHWestern SaharaSat–Sun—
EREritreaSat–Sun—
ESSpainSat–Sun19
ETEthiopiaSat–Sun—
FIFinlandSat–Sun19
FJFijiSat–Sun—
FKFalkland IslandsSat–Sun—
FMMicronesiaSat–Sun4
FOFaroe IslandsSat–Sun—
FRFranceSat–Sun14
GAGabonSat–Sun—
GBUnited KingdomSat–Sun4
GDGrenadaSat–Sun—
GEGeorgiaSat–Sun—
GFFrench GuianaSat–Sun—
GGGuernseySat–Sun—
GHGhanaSat–Sun—
GIGibraltarSat–Sun—
GLGreenlandSat–Sun—
GMGambiaSat–Sun—
GNGuineaSat–Sun—
GPGuadeloupeSat–Sun—
GQEquatorial GuineaSat–Sun8
GRGreeceSat–Sun—
GSSouth Georgia and the South Sandwich IslandsSat–Sun—
GTGuatemalaSat–Sun—
GUGuamSat–Sun—
GWGuinea-BissauSat–Sun—
GYGuyanaSat–Sun—
HKHong KongSun—
HMHeard Island and McDonald IslandsSat–Sun—
HNHondurasSat–Sun—
HRCroatiaSat–Sun—
HTHaitiSat–Sun—
HUHungarySat–Sun—
IDIndonesiaSat–Sun—
IEIrelandSat–Sun—
ILIsraelFri–Sat—
IMIsle of ManSat–Sun—
INIndiaSat–Sun36
IOBritish Indian Ocean TerritorySat–Sun—
IQIraqFri–Sat—
IRIranFri—
ISIcelandSat–Sun—
ITItalySat–Sun107
JEJerseySat–Sun—
JMJamaicaSat–Sun—
JOJordanFri–Sat—
JPJapanSat–Sun—
KEKenyaSat–Sun—
KGKyrgyzstanSat–Sun—
KHCambodiaSat–Sun—
KIKiribatiSat–Sun—
KMComorosSat–Sun—
KNSaint Kitts and NevisSun—
KPNorth KoreaSat–Sun—
KRSouth KoreaSat–Sun—
KWKuwaitFri–Sat—
KYCayman IslandsSat–Sun—
KZKazakhstanSat–Sun—
LALaosSat–Sun—
LBLebanonSat–Sun—
LCSaint LuciaSat–Sun—
LILiechtensteinSat–Sun—
LRLiberiaSat–Sun—
LSLesothoSat–Sun—
LTLithuaniaSat–Sun—
LULuxembourgSat–Sun—
LVLatviaSat–Sun—
LYLibyaSat–Sun—
MAMoroccoSat–Sun—
MCMonacoSat–Sun—
MDMoldovaSat–Sun—
MEMontenegroSat–Sun—
MFSaint MartinSat–Sun—
MGMadagascarSat–Sun—
MHMarshall IslandsSat–Sun—
MKNorth MacedoniaSat–Sun—
MLMaliSat–Sun—
MMMyanmarSat–Sun—
MNMongoliaSat–Sun—
MOMacaoSat–Sun2
MPNorthern Mariana IslandsSat–Sun—
MQMartiniqueSat–Sun—
MRMauritaniaFri–Sat—
MSMontserratSat–Sun—
MTMaltaSat–Sun—
MUMauritiusSat–Sun—
MVMaldivesFri–Sat—
MWMalawiSat–Sun—
MXMexicoSat–Sun—
MYMalaysiaSat–Sun16
MZMozambiqueSat–Sun—
NANamibiaSat–Sun—
NCNew CaledoniaSat–Sun—
NENigerSun—
NFNorfolk IslandSat–Sun—
NGNigeriaSat–Sun—
NINicaraguaSat–Sun17
NLNetherlandsSat–Sun—
NONorwaySat–Sun17
NPNepalSat–Sun—
NRNauruSat–Sun—
NUNiueSat–Sun—
NZNew ZealandSat–Sun17
OMOmanFri–Sat—
PAPanamaSat–Sun—
PEPeruSat–Sun—
PFFrench PolynesiaSat–Sun—
PGPapua New GuineaSat–Sun—
PHPhilippinesSat–Sun—
PKPakistanSat–Sun—
PLPolandSat–Sun—
PMSaint Pierre and MiquelonSat–Sun—
PNPitcairnSat–Sun—
PRPuerto RicoSat–Sun—
PSPalestineSat–Sun—
PTPortugalSat–Sun20
PWPalauSat–Sun—
PYParaguaySun—
QAQatarFri–Sat—
RERéunionSat–Sun—
RORomaniaSat–Sun—
RSSerbiaSat–Sun—
RURussian FederationSat–Sun—
RWRwandaSat–Sun—
SASaudi ArabiaFri–Sat—
SBSolomon IslandsSat–Sun10
SCSeychellesSat–Sun—
SDSudanFri–Sat—
SESwedenSat–Sun—
SGSingaporeSat–Sun—
SHSaint Helena, Ascension and Tristan da CunhaSat–Sun3
SISloveniaSat–Sun—
SJSvalbard and Jan MayenSat–Sun—
SKSlovakiaSat–Sun—
SLSierra LeoneSat–Sun—
SMSan MarinoSat–Sun—
SNSenegalSat–Sun—
SOSomaliaSat–Sun—
SRSurinameSat–Sun—
SSSouth SudanSat–Sun—
STSao Tome and PrincipeSat–Sun7
SVEl SalvadorSat–Sun14
SXSint MaartenSat–Sun—
SYSyriaFri–Sat—
SZEswatiniSat–Sun—
TCTurks and Caicos IslandsSat–Sun—
TDChadSat–Sun—
TFFrench Southern TerritoriesSat–Sun—
TGTogoSat–Sun—
THThailandSat–Sun—
TJTajikistanSat–Sun—
TKTokelauSun—
TLTimor-LesteSat–Sun—
TMTurkmenistanSat–Sun—
TNTunisiaSat–Sun—
TOTongaSat–Sun—
TRTürkiyeSat–Sun—
TTTrinidad and TobagoSat–Sun—
TVTuvaluSat–Sun8
TWTaiwanSat–Sun—
TZTanzaniaSat–Sun—
UAUkraineSat–Sun—
UGUgandaSat–Sun—
UMUnited States Minor Outlying IslandsSat–Sun—
USUnited StatesSat–Sun57
UYUruguaySat–Sun—
UZUzbekistanSat–Sun—
VAVatican CitySat–Sun—
VCSaint Vincent and the GrenadinesSat–Sun—
VEVenezuelaSun—
VGBritish Virgin IslandsSat–Sun—
VIU.S. Virgin IslandsSat–Sun—
VNVietnamSat–Sun—
VUVanuatuSat–Sun—
WFWallis and FutunaSat–Sun—
WSSamoaSat–Sun—
XKKosovoSat–Sun—
YEYemenFri–Sat—
YTMayotteSat–Sun—
ZASouth AfricaSat–Sun—
ZMZambiaSat–Sun—
ZWZimbabweSat–Sun—

Subdivision codes

Use these with holiday_subdivision (or as holiday_country=XX-SUB). 35 countries have subdivision calendars:

  • AD Andorra (7): 02 Canillo · 03 Encamp · 04 La Massana · 05 Ordino · 06 Sant Julià de Lòria · 07 Andorra la Vella · 08 Escaldes-Engordany
  • AM Armenia (11): AG Aragac̣otn · AR Ararat · AV Armavir · ER Erevan · GR Geġark'unik' · KT Kotayk' · LO Loṙi · SH Širak · SU Syunik' · TV Tavuš · VD Vayoć Jor
  • AR Argentina (24): A Salta · B Buenos Aires · C Ciudad Autónoma de Buenos Aires · D San Luis · E Entre Ríos · F La Rioja · G Santiago del Estero · H Chaco · J San Juan · K Catamarca · L La Pampa · M Mendoza · N Misiones · P Formosa · Q Neuquén · R Río Negro · S Santa Fe · T Tucumán · U Chubut · V Tierra del Fuego · W Corrientes · X Córdoba · Y Jujuy · Z Santa Cruz
  • AT Austria (9): 1 Burgenland · 2 Kärnten · 3 Niederösterreich · 4 Oberösterreich · 5 Salzburg · 6 Steiermark · 7 Tirol · 8 Vorarlberg · 9 Wien
  • AU Australia (8): ACT Australian Capital Territory · NSW New South Wales · NT Northern Territory · QLD Queensland · SA South Australia · TAS Tasmania · VIC Victoria · WA Western Australia
  • BA Bosnia and Herzegovina (3): BIH Federacija Bosne i Hercegovine · BRC Brčko distrikt · SRP Republika Srpska
  • BO Bolivia (9): B El Beni · C Cochabamba · H Chuquisaca · L La Paz · N Pando · O Oruro · P Potosí · S Santa Cruz · T Tarija
  • BQ Bonaire, Sint Eustatius and Saba (3): BON Bonaire · SAB Saba · STA Sint Eustatius
  • BR Brazil (27): AC Acre · AL Alagoas · AM Amazonas · AP Amapá · BA Bahia · CE Ceará · DF Distrito Federal · ES Espírito Santo · GO Goiás · MA Maranhão · MG Minas Gerais · MS Mato Grosso do Sul · MT Mato Grosso · PA Pará · PB Paraíba · PE Pernambuco · PI Piauí · PR Paraná · RJ Rio de Janeiro · RN Rio Grande do Norte · RO Rondônia · RR Roraima · RS Rio Grande do Sul · SC Santa Catarina · SE Sergipe · SP São Paulo · TO Tocantins
  • BT Bhutan (20): 11 Paro · 12 Chhukha · 13 Haa · 14 Samtse · 15 Thimphu · 21 Tsirang · 22 Dagana · 23 Punakha · 24 Wangdue Phodrang · 31 Sarpang · 32 Trongsa · 33 Bumthang · 34 Zhemgang · 41 Trashigang · 42 Monggar · 43 Pema Gatshel · 44 Lhuentse · 45 Samdrup Jongkhar · GA Gasa · TY Trashi Yangtse
  • CA Canada (13): AB Alberta · BC British Columbia · MB Manitoba · NB New Brunswick · NL Newfoundland and Labrador · NS Nova Scotia · NT Northwest Territories · NU Nunavut · ON Ontario · PE Prince Edward Island · QC Quebec · SK Saskatchewan · YT Yukon
  • CH Switzerland (26): AG Aargau · AI Appenzell Innerrhoden · AR Appenzell Ausserrhoden · BE Bern · BL Basel-Landschaft · BS Basel-Stadt · FR Freiburg · GE Genève · GL Glarus · GR Graubünden · JU Jura · LU Luzern · NE Neuchâtel · NW Nidwalden · OW Obwalden · SG Sankt Gallen · SH Schaffhausen · SO Solothurn · SZ Schwyz · TG Thurgau · TI Ticino · UR Uri · VD Vaud · VS Valais · ZG Zug · ZH Zürich
  • CL Chile (16): AI Aisén del General Carlos Ibañez del Campo · AN Antofagasta · AP Arica y Parinacota · AR La Araucanía · AT Atacama · BI Biobío · CO Coquimbo · LI Libertador General Bernardo O'Higgins · LL Los Lagos · LR Los Ríos · MA Magallanes · ML Maule · NB Ñuble · RM Región Metropolitana de Santiago · TA Tarapacá · VS Valparaíso
  • CV Cabo Verde (22): BR Brava · BV Boa Vista · CA Santa Catarina · CF Santa Catarina do Fogo · CR Santa Cruz · MA Maio · MO Mosteiros · PA Paul · PN Porto Novo · PR Praia · RB Ribeira Brava · RG Ribeira Grande · RS Ribeira Grande de Santiago · SD São Domingos · SF São Filipe · SL Sal · SM São Miguel · SO São Lourenço dos Órgãos · SS São Salvador do Mundo · SV São Vicente · TA Tarrafal · TS Tarrafal de São Nicolau
  • DE Germany (16): BB Brandenburg · BE Berlin · BW Baden-Württemberg · BY Bayern · HB Bremen · HE Hessen · HH Hamburg · MV Mecklenburg-Vorpommern · NI Niedersachsen · NW Nordrhein-Westfalen · RP Rheinland-Pfalz · SH Schleswig-Holstein · SL Saarland · SN Sachsen · ST Sachsen-Anhalt · TH Thüringen
  • ES Spain (19): AN Andalucía · AR Aragón · AS Asturias · CB Cantabria · CE Ceuta · CL Castilla y León · CM Castilla-La Mancha · CN Canarias · CT Cataluña · EX Extremadura · GA Galicia · IB Islas Baleares · MC Murcia · MD Madrid · ML Melilla · NC Navarra · PV País Vasco · RI La Rioja · VC Valenciana
  • FI Finland (19): 01 Ahvenanmaan maakunta · 02 Etelä-Karjala · 03 Etelä-Pohjanmaa · 04 Etelä-Savo · 05 Kainuu · 06 Kanta-Häme · 07 Keski-Pohjanmaa · 08 Keski-Suomi · 09 Kymenlaakso · 10 Lappi · 11 Pirkanmaa · 12 Pohjanmaa · 13 Pohjois-Karjala · 14 Pohjois-Pohjanmaa · 15 Pohjois-Savo · 16 Päijät-Häme · 17 Satakunta · 18 Uusimaa · 19 Varsinais-Suomi
  • FM Micronesia (4): KSA Kosrae · PNI Pohnpei · TRK Chuuk · YAP Yap
  • FR France (14): 57 Moselle · 6AE Alsace · 971 Guadeloupe · 972 Martinique · 973 Guyane (French Guiana) · 974 La Réunion · 976 Mayotte · BL Saint-Barthélemy · MF Saint-Martin · NC Nouvelle-Calédonie · PF Polynésie Française · PM Saint-Pierre-et-Miquelon · TF Terres australes françaises · WF Wallis-et-Futuna
  • GB United Kingdom (4): ENG England · NIR Northern Ireland · SCT Scotland · WLS Wales
  • GQ Equatorial Guinea (8): AN Annobón · BN Bioko Norte · BS Bioko Sur · CS Centro Sur · DJ Djibloho · KN Kié-Ntem · LI Litoral · WN Wele-Nzas
  • IN India (36): AN Andaman and Nicobar Islands · AP Andhra Pradesh · AR Arunachal Pradesh · AS Assam · BR Bihar · CG Chhattisgarh · CH Chandigarh · DH Dadra and Nagar Haveli and Daman and Diu · DL Delhi · GA Goa · GJ Gujarat · HP Himachal Pradesh · HR Haryana · JH Jharkhand · JK Jammu and Kashmir · KA Karnataka · KL Kerala · LA Ladakh · LD Lakshadweep · MH Maharashtra · ML Meghalaya · MN Manipur · MP Madhya Pradesh · MZ Mizoram · NL Nagaland · OD Odisha · PB Punjab · PY Puducherry · RJ Rajasthan · SK Sikkim · TN Tamil Nadu · TR Tripura · TS Telangana · UK Uttarakhand · UP Uttar Pradesh · WB West Bengal
  • IT Italy (107): AG Agrigento · AL Alessandria · AN Ancona · AO Aosta · AP Ascoli Piceno · AQ L'Aquila · AR Arezzo · AT Asti · AV Avellino · BA Bari · BG Bergamo · BI Biella · BL Belluno · BN Benevento · BO Bologna · BR Brindisi · BS Brescia · BT Barletta-Andria-Trani · BZ Bolzano · CA Cagliari · CB Campobasso · CE Caserta · CH Chieti · CL Caltanissetta · CN Cuneo · CO Como · CR Cremona · CS Cosenza · CT Catania · CZ Catanzaro · EN Enna · FC Forli-Cesena · FE Ferrara · FG Foggia · FI Firenze · FM Fermo · FR Frosinone · GE Genova · GO Gorizia · GR Grosseto · IM Imperia · IS Isernia · KR Crotone · LC Lecco · LE Lecce · LI Livorno · LO Lodi · LT Latina · LU Lucca · MB Monza e Brianza · MC Macerata · ME Messina · MI Milano · MN Mantova · MO Modena · MS Massa-Carrara · MT Matera · NA Napoli · NO Novara · NU Nuoro · OR Oristano · PA Palermo · PC Piacenza · PD Padova · PE Pescara · PG Perugia · PI Pisa · PN Pordenone · PO Prato · PR Parma · PT Pistoia · PU Pesaro e Urbino · PV Pavia · PZ Potenza · RA Ravenna · RC Reggio Calabria · RE Reggio Emilia · RG Ragusa · RI Rieti · RM Roma · RN Rimini · RO Rovigo · SA Salerno · SI Siena · SO Sondrio · SP La Spezia · SR Siracusa · SS Sassari · SU Sud Sardegna · SV Savona · TA Taranto · TE Teramo · TN Trento · TO Torino · TP Trapani · TR Terni · TS Trieste · TV Treviso · UD Udine · VA Varese · VB Verbano-Cusio-Ossola · VC Vercelli · VE Venezia · VI Vicenza · VR Verona · VT Viterbo · VV Vibo Valentia
  • MO Macao (2): I Concelho das Ilhas · M Concelho de Macau
  • MY Malaysia (16): 01 Johor · 02 Kedah · 03 Kelantan · 04 Melaka · 05 Negeri Sembilan · 06 Pahang · 07 Pulau Pinang · 08 Perak · 09 Perlis · 10 Selangor · 11 Terengganu · 12 Sabah · 13 Sarawak · 14 Wilayah Persekutuan Kuala Lumpur · 15 Wilayah Persekutuan Labuan · 16 Wilayah Persekutuan Putrajaya
  • NI Nicaragua (17): AN Costa Caribe Norte · AS Costa Caribe Sur · BO Boaco · CA Carazo · CI Chinandega · CO Chontales · ES Estelí · GR Granada · JI Jinotega · LE León · MD Madriz · MN Managua · MS Masaya · MT Matagalpa · NS Nueva Segovia · RI Rivas · SJ Río San Juan
  • NO Norway (17): 03 Oslo · 11 Rogaland · 15 Møre og Romsdal · 18 Nordland · 21 Svalbard · 22 Jan Mayen · 31 Østfold · 32 Akershus · 33 Buskerud · 34 Innlandet · 39 Vestfold · 40 Telemark · 42 Agder · 46 Vestland · 50 Trööndelage · 55 Romssa · 56 Finmarkun
  • NZ New Zealand (17): AUK Auckland · BOP Bay of Plenty · CAN Canterbury · CIT Chatham Islands Territory · GIS Gisborne · HKB Hawke's Bay · MBH Marlborough · MWT Manawatū Whanganui · NSN Nelson · NTL Northland · OTA Otago · STL Southland · TAS Tasman · TKI Taranaki · WGN Greater Wellington · WKO Waikato · WTC West Coast
  • PT Portugal (20): 01 Aveiro · 02 Beja · 03 Braga · 04 Bragança · 05 Castelo Branco · 06 Coimbra · 07 Évora · 08 Faro · 09 Guarda · 10 Leiria · 11 Lisboa · 12 Portalegre · 13 Porto · 14 Santarém · 15 Setúbal · 16 Viana do Castelo · 17 Vila Real · 18 Viseu · 20 Região Autónoma dos Açores · 30 Região Autónoma da Madeira
  • SB Solomon Islands (10): CE Central · CH Choiseul · CT Capital Territory · GU Guadalcanal · IS Isabel · MK Makira-Ulawa · ML Malaita · RB Rennell and Bellona · TE Temotu · WE Western
  • SH Saint Helena, Ascension and Tristan da Cunha (3): AC Ascension · HL Saint Helena · TA Tristan da Cunha
  • ST Sao Tome and Principe (7): 01 Água Grande · 02 Cantagalo · 03 Caué · 04 Lembá · 05 Lobata · 06 Mé-Zóchi · P Príncipe
  • SV El Salvador (14): AH Ahuachapán · CA Cabañas · CH Chalatenango · CU Cuscatlán · LI La Libertad · MO Morazán · PA La Paz · SA Santa Ana · SM San Miguel · SO Sonsonate · SS San Salvador · SV San Vicente · UN La Unión · US Usulután
  • TV Tuvalu (8): FUN Funafuti · NIT Niutao · NKF Nukufetau · NKL Nukulaelae · NMA Nanumea · NMG Nanumaga · NUI Nui · VAI Vaitupu
  • US United States (57): AK Alaska · AL Alabama · AR Arkansas · AS American Samoa · AZ Arizona · CA California · CO Colorado · CT Connecticut · DC District of Columbia · DE Delaware · FL Florida · GA Georgia · GU Guam · HI Hawaii · IA Iowa · ID Idaho · IL Illinois · IN Indiana · KS Kansas · KY Kentucky · LA Louisiana · MA Massachusetts · MD Maryland · ME Maine · MI Michigan · MN Minnesota · MO Missouri · MP Northern Mariana Islands · MS Mississippi · MT Montana · NC North Carolina · ND North Dakota · NE Nebraska · NH New Hampshire · NJ New Jersey · NM New Mexico · NV Nevada · NY New York · OH Ohio · OK Oklahoma · OR Oregon · PA Pennsylvania · PR Puerto Rico · RI Rhode Island · SC South Carolina · SD South Dakota · TN Tennessee · TX Texas · UM United States Minor Outlying Islands · UT Utah · VA Virginia · VI Virgin Islands, U.S. · VT Vermont · WA Washington · WI Wisconsin · WV West Virginia · WY Wyoming

Embeddable clocks

/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 (Cache-Control: no-store) so each fetch reflects the current request.

The clock syncs once from the snippet and then ticks locally. Periodic network refresh is off by default (it would need your API key in the page), so a page left open across a daylight-saving change keeps its old UTC offset until the snippet is fetched again. Fetch the snippet from your server on each page load, and reload it periodically on pages that stay open for days. To opt in to refresh, set refresh.enabled = true in the config and point refresh.path at a same-origin proxy that adds your key. See the clock reference for details.

WorldTimeAPI-compatible routes

TimeLogic serves the worldtimeapi.org API under the same paths on https://api.timelogicapi.com. Swap the host, add your API key, and existing WorldTimeAPI clients keep parsing the same JSON and plain-text responses. These routes sit beside /v1 and do not use the /v1 prefix.

WorldTimeAPITimeLogic
worldtimeapi.org/api/timezone/Europe/Londonapi.timelogicapi.com/api/timezone/Europe/London
worldtimeapi.org/api/ip.txtapi.timelogicapi.com/api/ip.txt

Everything after the domain is identical. The one addition is the API key.

Routes

Method and pathReturns
GET /api/timezoneJSON array of every time zone name (tzdata zones and links), sorted.
GET /api/timezone/{area}JSON array of the names under one area, for example Europe, America or Etc. A one-word zone such as UTC, EST or CET returns its time object instead.
GET /api/timezone/{area}/{location}Time object for the zone, for example Europe/London.
GET /api/timezone/{area}/{location}/{region}Time object for a three-part zone, for example America/Argentina/Salta.
GET /api/ipTime object for the zone of the calling IP address.
GET /api/ip/{ip}Time object for the zone of the given IPv4 or IPv6 address.

Add .txt to any of these paths for text/plain: /api/timezone.txt, /api/timezone/Europe.txt, /api/timezone/Europe/London.txt, /api/ip.txt, /api/ip/8.8.8.8.txt. Lists come back one name per line; time objects come back as key: value lines. Neither ends with a trailing newline.

Zone names match in any letter case (europe/london works), as they did on WorldTimeAPI. The timezone field uses the tzdata spelling of the name you asked for.

Authentication

A TimeLogic API key is required on every /api/* request. Send it any of the three ways /v1 accepts:

MethodExample
Authorization headerAuthorization: Bearer $TIMELOGIC_API_KEY
X-API-Key headerX-API-Key: $TIMELOGIC_API_KEY
api_key query parameter/api/timezone/Europe/London?api_key=YOUR_KEY

The query parameter exists for clients that cannot set headers (spreadsheets, BI tools, small devices). Prefer a header wherever you can, and keep keys server-side.

The compat routes share your plan's monthly quota and are metered like /v1: a missing or invalid key returns TimeLogic's 401 JSON error, an exhausted quota returns 429, and an inactive subscription returns 403, exactly as on /v1 (see Errors & rate limits). The Free plan includes 10,000 requests per month.

Examples

curl "https://api.timelogicapi.com/api/timezone/Europe/London?api_key=YOUR_KEY"
curl "https://api.timelogicapi.com/api/timezone/America/New_York.txt" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"
curl "https://api.timelogicapi.com/api/ip/8.8.8.8" \
  -H "X-API-Key: $TIMELOGIC_API_KEY"
const res = await fetch("https://api.timelogicapi.com/api/timezone/Asia/Tokyo", {
  headers: { Authorization: `Bearer ${process.env.TIMELOGIC_API_KEY}` },
});
const { datetime, utc_offset, dst } = await res.json();
import os, requests

r = requests.get(
    "https://api.timelogicapi.com/api/timezone/Europe/Berlin",
    headers={"X-API-Key": os.environ["TIMELOGIC_API_KEY"]},
)
print(r.json()["datetime"])

The time object

A time object has the same 15 fields as WorldTimeAPI, with the same names, types and formats. JSON keys come in the order WorldTimeAPI used from August 2024 until it went offline:

{
  "utc_offset": "+00:00",
  "timezone": "Europe/London",
  "day_of_week": 1,
  "day_of_year": 6,
  "datetime": "2025-01-06T18:39:05.049000+00:00",
  "utc_datetime": "2025-01-06T18:39:05.049000+00:00",
  "unixtime": 1736188745,
  "raw_offset": 0,
  "week_number": 2,
  "dst": false,
  "abbreviation": "GMT",
  "dst_offset": 0,
  "dst_from": null,
  "dst_until": null,
  "client_ip": "203.0.113.7"
}
FieldTypeMeaning
abbreviationstringtzdata abbreviation: GMT, BST, EST, or a numeric one such as -03 where tzdata has no letters.
client_ipstringThe IP address the request came from (also on /api/ip/{ip}, where it is still the caller's address).
datetimestringLocal time, ISO 8601 with six fractional digits and the offset, e.g. 2025-08-13T11:13:46.612000+01:00.
day_of_weekinteger0 = Sunday … 6 = Saturday.
day_of_yearintegerStarts at 1 on January 1.
dstbooleanWhether daylight saving time is in effect.
dst_fromstring or nullUTC start of the current DST period, e.g. 2025-03-30T01:00:00+00:00; null when dst is false.
dst_offsetintegerSeconds added by DST right now (3600 during BST, 0 otherwise).
dst_untilstring or nullUTC end of the current DST period; null when dst is false.
raw_offsetintegerStandard offset from UTC in seconds, excluding DST.
timezonestringThe zone name, e.g. Europe/London.
unixtimeintegerUnix seconds.
utc_datetimestringThe same instant in UTC, ending in +00:00.
utc_offsetstringCurrent offset as ±HH:MM.
week_numberintegerISO 8601 week number (2024-12-31 is week 1).

The .txt form carries the same fields as key: value lines in alphabetical order. A null is written as the key, a colon and a space with nothing after it:

abbreviation: GMT
client_ip: 203.0.113.7
datetime: 2025-11-30T20:23:23.016000+00:00
day_of_week: 0
day_of_year: 334
dst: false
dst_from: 
dst_offset: 0
dst_until: 
raw_offset: 0
timezone: Europe/London
unixtime: 1764534203
utc_datetime: 2025-11-30T20:23:23.016000+00:00
utc_offset: +00:00
week_number: 48

Zones where tzdata uses negative DST, such as Europe/Dublin, are reported the way WorldTimeAPI reported them: dst: false, dst_offset: 0, and raw_offset equal to the current UTC offset.

Errors

Errors use WorldTimeAPI's bodies and status codes:

SituationStatusJSON body.txt body
Unknown zone or area404{"error":"unknown location"}Error: unknown location
Malformed IP address404{"error":"malformed ip"}Error: malformed ip
Path that is not an endpoint404{"error":"not found"}Error: not found

WorldTimeAPI-style 404 responses are not counted against your quota. Authentication, quota and subscription errors use TimeLogic's normal JSON error body described above.

Headers and CORS

  • JSON: Content-Type: application/json; charset=utf-8. Text: Content-Type: text/plain; charset=utf-8.
  • Cache-Control: max-age=0, private, must-revalidate.
  • CORS is open: Access-Control-Allow-Origin: *.

Optional signed responses

Add sign=true to any compat route to get the same detached Ed25519 signature that /v1 returns. The body stays byte-for-byte identical to the unsigned response, so WorldTimeAPI parsers see no difference; the signature arrives in six response headers:

  • X-TimeLogic-Signature
  • X-TimeLogic-Signature-Alg
  • X-TimeLogic-Signature-Input
  • X-TimeLogic-Signature-Timestamp
  • X-TimeLogic-Key-Id
  • X-TimeLogic-Content-SHA256

Signing works on JSON and on .txt responses. The signed path in X-TimeLogic-Signature-Input includes the .txt suffix, which tells a verifier which representation was signed. Verify exactly as described in Signed responses, or paste a response into the verifier.

curl -i "https://api.timelogicapi.com/api/timezone/Europe/London.txt?sign=true&api_key=YOUR_KEY"

Differences from worldtimeapi.org

  • API key required. This is the intended difference; auth failures return TimeLogic's JSON error, not a WorldTimeAPI-style body.
  • Microseconds. datetime and utc_datetime keep six fractional digits, but the last three are always 000 (millisecond clock).
  • .txt line order is alphabetical. That is the fixed order WorldTimeAPI served from 2019 to July 2024; after that its line order changed from request to request.
  • Newer data. Time zone and IP data are TimeLogic's current datasets, newer than WorldTimeAPI's last release. The zone list is WorldTimeAPI's final 596 names plus America/Coyhaique (597 in all), and a few IP addresses may resolve differently.
  • Quota instead of WorldTimeAPI's rate limiting. Limits follow your plan's monthly quota; there are no x-ratelimit-* headers.

Troubleshooting

SymptomCauseFix
Connection reset by peer, ERR_EMPTY_RESPONSE or timeouts from worldtimeapi.orgThe old service is offlinePoint the same path at https://api.timelogicapi.com and send a key
410 Gone "WorldTimeAPI has been sunset"worldtimeapi.org was shut down in 2026Same fix; 410 is permanent, retries do not help
401 UNAUTHORIZED after switchingNo key, an invalid key, or two different keys in one requestSend exactly one of Authorization: Bearer, X-API-Key or api_key
404 {"error":"unknown location"}Zone name not in the listCheck the spelling against /api/timezone; letter case does not matter
404 {"error":"malformed ip"}The IP in /api/ip/{ip} is not a valid IPv4 or IPv6 addressSend a valid public address
429 QUOTA_EXCEEDEDThe plan's monthly quota is used upUpgrade the plan or wait for the next period
A CORS error in the browser for worldtimeapi.orgA failing server sends no CORS headersThe compat routes send Access-Control-Allow-Origin: *; call them from your backend so the key stays private

Code for ten languages, a field-by-field table and longer answers are in the migration guide.

OpenAPI

The full contract for these routes is published as openapi-worldtimeapi.yaml, and you can try every route with your key in the interactive WorldTimeAPI-compatible reference. For a step-by-step migration with code for common languages, read the WorldTimeAPI alternative guide.

Best practices

  • JSON responses are not marked cacheable (they carry no Cache-Control header). If you cache "now" values on your side, keep the lifetime short (a second or so), and compute elapsed time locally from unix_ms instead of re-requesting.
  • Use bulk mode to fold up to 10 city lookups into a single request, and check each array element for an error key.
  • Store and compare instants as unix_ms or utc; use iso_local and human only for display.
  • Always render the timezone the API returns: aliases resolve to their canonical zone.
  • Send local iso values with a source_* hint (or an explicit offset). Without one they are read as UTC.
  • Verify signed responses on the server, not the client.
  • Keep the API key on your server. Browser code should go through your own proxy.
  • Retry 5xx with exponential backoff. A 429 QUOTA_EXCEEDED means the monthly quota is used up: it clears at the start of the next UTC month or when you upgrade, so do not retry it in a loop.
  • Pin your client to API version v1 in the URL.

Errors & rate limits

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"
}

details is optional and varies by error. Error responses do not include a timestamp field, at the top level or inside bulk items.

Error codes

HTTPcodeWhen
400INVALID_PARAMETERA value is not valid: unknown timezone, bad offset format, unsupported strftime directive in format, a holiday_country outside the supported calendars or an unknown holiday_subdivision, a business-day range outside 1900–2100 with a holiday calendar, missing clock style, too many bulk values, or an add result outside the supported range.
400INVALID_TIMESTAMPA timestamp input is missing, malformed, not a real calendar date (for example 2027-02-29), a nonexistent local time in a spring-forward gap, or outside the supported range (0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
400MISSING_TARGETNo target selector where one is required (/v1/time/convert with none of tz/ip/lat+lon/offset/auto_tz/utc=true, or /v1/timezone with no selector; most other routes default to UTC instead).
400AMBIGUOUS_TARGETMore than one selector family or input form, a bulk selector combined with another target (including utc=true), or compare_* timestamps combined with a compare target selector on elapsed.
401UNAUTHORIZEDMissing API key credentials., Invalid API key credentials., or Conflicting API key credentials. (see Authentication).
403SUBSCRIPTION_INACTIVEThe key belongs to an inactive or revoked subscription.
404NOT_FOUNDUnknown route (including a trailing slash such as /v1/time/current/), an IP address with no timezone mapping (private, reserved, or loopback addresses such as 10.0.0.1 or ::1 never resolve), or an unknown signing key kid.
405METHOD_NOT_ALLOWEDAny method other than GET or HEAD (for example POST): Only GET and HEAD are supported. The response carries Allow: GET, HEAD.
429QUOTA_EXCEEDEDThe plan's monthly quota is used up: Monthly quota exceeded.
500INTERNAL_ERRORAn unexpected server error. Retry with backoff and quote the request ID if it persists.
501 / 502 / 503DEPENDENCY_NOT_READY, SIGNING_NOT_READY, INTERNAL_ERRORA dependent service is temporarily unavailable. Retry with backoff.

The OpenAPI specs also list INVALID_AUTH in the error-code enum; the direct API currently reports all credential problems as 401 UNAUTHORIZED.

Bulk requests

A bulk request (a comma-separated selector on /v1/time/current or /v1/time/convert) returns HTTP 200 with an array even when some items fail. Each failed item is an object with item, error and request_id in place of the normal payload, so check every element. Errors that apply to the whole request (more than 10 values, an invalid input timestamp, missing credentials) still return a single 4xx error. See Bulk mode.

Response headers

Every response includes an X-Request-Id header; quote it in support tickets. Authenticated responses on the direct API also include:

HeaderMeaning
X-Auth-ModeHow the request was authenticated (api_key).
X-TimeLogic-Customer-IDYour customer ID.
X-TimeLogic-Key-IdThe ID of the API key used (on unsigned responses). On signed responses this header carries the signing key kid instead; see Signed responses.
X-TimeLogic-PlanYour plan, for example free.
X-TimeLogic-Quota-LimitRequests included per month, or unlimited.
X-TimeLogic-Quota-Stateactive, or exceeded once the monthly quota is used up.

These headers are exposed to browsers through CORS. There is currently no header for remaining requests or for the reset time; your usage is shown in your account.

Quotas and rate limits

Plans are metered by a monthly request quota (see Pricing). The quota period is the calendar month in UTC: it resets at 00:00 UTC on the 1st. Every successful (200) request counts against the quota, including HEAD requests, which are answered like GET without a body. When the quota is used up, requests return 429 QUOTA_EXCEEDED until the next period starts or the plan is upgraded. A 429 does not carry a Retry-After header, because the wait is until the next month rather than seconds.

The API does not publish a per-second or per-minute rate limit beyond the monthly quota. Keep bursts reasonable, and contact us before sending sustained high-volume traffic; Enterprise plans can arrange dedicated capacity.

Retry 5xx responses with exponential backoff. Do not retry 4xx responses unchanged: fix the request first.