Skip to content
Endpoint guide

Resolve timezone

GET /v1/timezoneOpenAPI YAML

Canonical IANA timezone for a timezone name, IP, coordinate or offset, with current offset and DST flag.

What do I need to send?

Required / choose this first

Provide one selector: tz, ip, lat + lon, or offset.

Optional

sign is optional.

Rule: offset returns matching zones; ip and coordinates resolve to a canonical IANA timezone.

NameNeeded?Use it for
tzChoose one targetIANA timezone to resolve directly.
ipChoose one targetIPv4 or IPv6 (resolved via GeoLite2).
latPair parameterLatitude. Pair with lon.
lonPair parameterLongitude.
offsetChoose one targetFixed UTC offset (URL-encode + as %2B). Returns timezone null and the geographic zones currently at that offset in matching_zones.
auto_tzChoose one targetSet true to resolve the request IP's timezone.
signOptionalSet true for a signed response.

Code samples

Copy a request in your preferred language and replace YOUR_TIMELOGIC_API_KEY with your direct API key.

curl "https://api.timelogicapi.com/v1/timezone?ip=8.8.8.8" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

Example response

{
  "unix": 1778093027,
  "unix_ms": 1778093027712,
  "utc": "2026-05-06T18:43:47Z",
  "iso_local": "2026-05-06T20:43:47+02:00",
  "rfc2822": "Wed, 06 May 2026 20:43:47 +0200",
  "human": "May 6, 2026, 8:43 PM Europe/Paris",
  "day_number": 4,
  "day_short": "Wed",
  "day_full": "Wednesday",
  "timezone": "Europe/Paris",
  "offset": 120,
  "dst": true
}
Additional endpoint notes

offset is the current UTC offset in minutes. timezone is the canonical IANA name. A selector is required: with none, the endpoint returns 400 MISSING_TARGET (unlike the time routes, which default to UTC).

https://api.timelogicapi.com/v1/timezone?ip=8.8.8.8
https://api.timelogicapi.com/v1/timezone?lat=48.8566&lon=2.3522
https://api.timelogicapi.com/v1/timezone?tz=Europe/Stockholm
https://api.timelogicapi.com/v1/timezone?offset=%2B05:30

Canonical names. tz is resolved to its canonical tzdata zone, so the name you get back can differ from the one you sent: Europe/Stockholm returns Europe/Berlin, Asia/Calcutta returns Asia/Kolkata, US/Eastern returns America/New_York, and UTC returns Etc/UTC. Names are matched case-insensitively.

Offset lookups. offset= returns "timezone": null and a matching_zones list of the zones whose current offset equals the one requested:

{
  "timezone": null,
  "offset": 330,
  "dst": false,
  "matching_zones": [
    { "timezone": "Asia/Colombo", "offset": 330, "dst": false },
    { "timezone": "Asia/Kolkata", "offset": 330, "dst": false }
  ]
}

Matches use today's offsets, so offset=-03:30 returns an empty list while St. John's is on −02:30. The list contains geographic zones only: UTC and Etc/* zones are intentionally excluded, so offset=%2B00:00 lists places such as Europe/London, Europe/Lisbon and Africa/Abidjan but not UTC. Use tz=UTC (or tz=Etc/UTC) when you want UTC itself.

Coordinates and IPs. Coordinates at sea return nautical zones such as Etc/GMT+8 (UTC−08:00; the sign is inverted by POSIX convention), and lat=0&lon=0 returns Africa/Abidjan. IP resolution uses MaxMind GeoLite2; private, reserved and loopback addresses (10.0.0.1, ::1) have no mapping and return 404 NOT_FOUND ("No timezone mapping found for the supplied IP address.").

DST flag. dst follows tzdata, including Ireland's negative DST: Europe/Dublin reports dst: true in winter at +00:00.

Common errors

  • 400 MISSING_TARGET — no selector.
  • 400 AMBIGUOUS_TARGET — more than one selector family.
  • 400 INVALID_PARAMETER — unknown timezone, malformed offset, or invalid coordinates. A comma-separated list is not supported here.
  • 404 NOT_FOUND — an IP address with no timezone mapping.

When to use this endpoint

Use Resolve timezone when you need to turn an IP address or latitude/longitude pair into a canonical IANA timezone. It is useful for onboarding, personalization, analytics enrichment, and timezone-aware defaults.

Request model

Provide exactly one of tz, ip, the lat + lon pair, offset, or auto_tz=true. The endpoint returns the resolved IANA name, current local time, UTC offset in minutes, and a DST flag for the resolved zone.

Accuracy guidance

Coordinate resolution is usually the most explicit option. IP-based resolution is convenient for defaults, but users should be able to override it when precision matters. For JavaScript and Python examples of every selector, see the time zone API guide.

Frequently asked questions

How do I find the time zone of an IP address?

Call GET /v1/timezone?ip=8.8.8.8. The response gives the canonical IANA zone name, the current offset in minutes and whether DST is active.

How do I get the time zone from latitude and longitude?

Call GET /v1/timezone?lat=48.8566&lon=2.3522. Coordinates at sea return nautical zones such as Etc/GMT+8.

Why does the API return a different zone name than the one I sent?

tz is resolved to its canonical tzdata zone, so aliases map to their canonical name: Asia/Calcutta returns Asia/Kolkata and US/Eastern returns America/New_York. Names are matched case-insensitively.

Which zones have a given UTC offset?

Send offset=, for example offset=%2B05:30. The response lists matching_zones whose current offset equals the requested one.