RapidAPI documentation

1. Open the RapidAPI compatibility guide and subscribe to the TimeLogic API listing.
2. Copy your RapidAPI key and keep it server-side as RAPIDAPI_KEY.
3. Make your first request:

curl "https://timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com/v1/time/current?tz=Europe/Paris" -H "X-RapidAPI-Key: $RAPIDAPI_KEY" -H "X-RapidAPI-Host: timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com"

RapidAPI supplies the marketplace subscription, authentication headers, and usage dashboard for this transport.

RapidAPI requests use the marketplace key and host headers. Keep both values server-side; never embed them in browser code or commit them to source control.

X-RapidAPI-Key: YOUR_RAPIDAPI_KEY
X-RapidAPI-Host: timelogic-api-world-time-timezones-time-calculations.p.rapidapi.com

Use the RapidAPI compatibility guide for marketplace billing and subscription details.

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

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

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:

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.

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):

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.

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

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

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

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

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:

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.