Timezone API guide
Resolve IANA timezones from timezone names, IP addresses, coordinates, and UTC offsets.
How does a timezone lookup API work?
The /v1/timezone endpoint resolves a target into a canonical IANA timezone and returns the current offset and daylight-saving flag. It works as a time zone API for known IANA names, an IP to timezone API for network-based defaults, and a timezone API by coordinates when you have latitude and longitude. IP geolocation time lookups are useful for an IP address timezone lookup, while city and country inputs can be resolved by your application into an explicit IANA zone or coordinate pair.
curl "https://api.timelogicapi.com/v1/time/timezone?ip=8.8.8.8" \
-H "Authorization: Bearer $TIMELOGIC_API_KEY"
Selector choices
| Input | Use it when | Notes |
|---|---|---|
tz | The application already has an IANA name | Returns the same canonical zone with current context. |
ip | You need a network-based default | IP resolution uses GeoLite2; let the user override the result when precision matters. |
lat + lon | You have an explicit place | Send the pair together. |
offset | A rules-based zone is not required | URL-encode a plus sign as %2B. |
Use one selector family per request. An invalid IANA name or malformed offset returns INVALID_PARAMETER; combining families returns AMBIGUOUS_TARGET.
Read the result
The response includes the resolved timezone, local and UTC representations, Unix timestamps, offset in minutes, and a dst flag. Store the IANA name when you need to perform later conversions; an offset alone cannot describe daylight-saving rules or historical changes.
City, country, and historical inputs
The endpoint accepts timezone, IP, coordinate, and fixed-offset selectors. If an upstream form starts with a city or country, resolve that value to a coordinate or an IANA name before calling this endpoint. Historical results should use /v1/time/convert with an explicit timestamp, because /v1/timezone reports the current context for the resolved target.
Choosing IP versus coordinates
IP-based location is convenient for onboarding and approximate defaults. Coordinates are a clearer customer choice when a user has selected a place or when a device may be behind a proxy. In both cases, show the resolved zone and allow a correction rather than silently treating an IP result as a verified address.
See the selectors documentation and timezone endpoint reference for the complete contract.