Timezone by Coordinates

Pass latitude and longitude coordinates and get the exact IANA timezone name (e.g. America/New_York), current UTC offset, and daylight saving time status. Uses the timezonefinder library under the hood.

Endpoint

GET /v1/geo/timezone-by-coords

Base URL: https://geo.toolkitapi.io

Parameters

Parameter Type Required Default Description
lat float Yes — Latitude (-90 to 90).
lon float Yes — Longitude (-180 to 180).

Response Fields

Field Type Description
latitude float Echoes the input latitude.
longitude float Echoes the input longitude.
timezone string IANA timezone name (e.g. America/New_York).
utc_offset string Current UTC offset (e.g. -05:00 or +05:30).
is_dst boolean Whether daylight saving time is currently active.

Examples

San Francisco, USA

curl -G "https://geo.toolkitapi.io/v1/geo/timezone-by-coords" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "lat=37.7749" \
  --data-urlencode "lon=-122.4194"
from toolkitapi import Geo

with Geo(api_key="YOUR_KEY") as geo:
    result = geo.timezone_by_coords(lat=37.7749, lon=-122.4194)
    print(f"Timezone: {result['timezone']}")
    print(f"UTC Offset: {result['utc_offset']}")
    print(f"DST active: {result['is_dst']}")
const params = new URLSearchParams({ lat: "37.7749", lon: "-122.4194" });
const resp = await fetch(
  `https://geo.toolkitapi.io/v1/geo/timezone-by-coords?${params}`,
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await resp.json();
console.log(data.timezone, data.utc_offset);
Response
{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": "America/Los_Angeles",
  "utc_offset": "-07:00",
  "is_dst": true
}

London, UK

curl -G "https://geo.toolkitapi.io/v1/geo/timezone-by-coords" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "lat=51.5074" \
  --data-urlencode "lon=-0.1278"
from toolkitapi import Geo

with Geo(api_key="YOUR_KEY") as geo:
    result = geo.timezone_by_coords(lat=51.5074, lon=-0.1278)
    print(result)
Response
{
  "latitude": 51.5074,
  "longitude": -0.1278,
  "timezone": "Europe/London",
  "utc_offset": "+01:00",
  "is_dst": true
}

Tokyo, Japan

curl -G "https://geo.toolkitapi.io/v1/geo/timezone-by-coords" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "lat=35.6762" \
  --data-urlencode "lon=139.6503"
const params = new URLSearchParams({ lat: "35.6762", lon: "139.6503" });
const resp = await fetch(
  `https://geo.toolkitapi.io/v1/geo/timezone-by-coords?${params}`,
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const data = await resp.json();
console.log(data);
Response
{
  "latitude": 35.6762,
  "longitude": 139.6503,
  "timezone": "Asia/Tokyo",
  "utc_offset": "+09:00",
  "is_dst": false
}

Error Handling

Coordinates in international waters (no timezone):

{
  "detail": "No timezone found for coordinates (0, 0). This may be in international waters."
}

This returns HTTP 404. Coordinates over oceans or unclaimed land may not map to any timezone.

Invalid coordinate range:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["query", "lat"],
      "msg": "ensure this value is greater than or equal to -90",
      "ctx": {"ge": -90}
    }
  ]
}

Returns HTTP 422. Latitude must be between -90 and 90, longitude between -180 and 180.

Tips

  • Time-sensitive: The utc_offset and is_dst fields reflect the current time at the server, which changes with daylight saving transitions.
  • Accuracy: The lookup is based on a high-resolution polygon map. Results are accurate to within a few hundred metres on land.
  • Common use cases:
  • Displaying local times for users in events or scheduling
  • Converting stored UTC timestamps to the correct local timezone
  • Geocoding from IP address → lat/lon → timezone (pair with /v1/geo/ip-lookup)

How the timezone is resolved

timezone-by-coords bundles the timezonefinder dataset, a polygon mesh of every IANA timezone boundary. The lookup is a point-in-polygon test against that mesh — no network call, no geocoding, no reverse-geocoding provider involved.

That has concrete consequences:

  • Coordinates are the only input. No country or address is derived, so a coastal coordinate can resolve to a maritime zone name rather than the inland country you expected.
  • The boundary is authoritative, not your map. Points a few hundred metres either side of a border (e.g. the Kazakhstan/China line, or a US state boundary that also splits a timezone) can return different zones. This is correct behaviour, not a bug.
  • Territorial waters count. Most ocean coordinates still return a zone (that's how marine timekeeping works). Only genuinely uncovered areas return 404.

Response timing and caching

The TimezoneFinder object is a single process-wide instance (@lru_cache(maxsize=1)) — the ~40 MB data file is loaded once per worker, not per request. The first call after a cold start pays a load penalty; every later call is sub-millisecond. Nothing about the response varies between calls except the offset, so it's safe to cache results client-side by coordinate.

What utc_offset and is_dst actually mean

Both fields describe the timezone's state right now (UTC at the moment of the request), not the state at some date you pass in.

Field Derived from Notes
utc_offset datetime.now(ZoneInfo(tz)).utcoffset() Format ±HH:MM. Changes across DST transitions.
is_dst bool(now.dst()) False during standard time and for zones that never observe DST.

This endpoint does not accept a date. If you need the offset for a past or future timestamp, use timezone-convert (pass the date as timestamp) or timezone-info for the current state of a named zone.

Warning

Don't persist utc_offset as a property of a location. It is time-dependent — America/New_York returns -05:00 in January and -04:00 in July. Store the IANA name and convert at render time.

Parameter edge cases

Input Result
lat=-90, lon=0 (South Pole) 200 — returns Antarctica/... zone
lat=0, lon=0 (Gulf of Guinea) 200 — ocean zones have IANA names (Etc/GMT) or a coastal zone
lat=90, lon=180 200 — Arctic zones exist
lat=37.7749 and no lon 422 — both are required
lat=91 422 — le=90 constraint (body.lat / query.lat in the error)
Numeric string lat="37.7749" 200 — coerced to float
lat=null / omitted 422
# 404 example — a coordinate with no timezone coverage
curl -s -G "https://geo.toolkitapi.io/v1/geo/timezone-by-coords" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "lat=-75.0" \
  --data-urlencode "lon=-150.0"
# {"detail":"No timezone found for coordinates (-75.0, -150.0). This may be in international waters."}

Error reference

Status Condition detail
401/403 Missing or invalid X-API-Key auth error
422 lat missing or outside −90…90 Pydantic range error
422 lon missing or outside −180…180 Pydantic range error
404 Coordinate falls in an uncovered region No timezone found for coordinates (<lat>, <lon>). This may be in international waters.
503 timezonefinder not installed in the deployment timezonefinder library not installed

503 is a deployment fault, not something you can trigger — but handle it, since a misconfigured instance surfaces it on every call.

JavaScript example: batch lookup with a bounded pool

Timezone lookups are cheap, but a UI that geolocates 200 markers at once shouldn't fire 200 parallel requests.

const API = "https://geo.toolkitapi.io/v1/geo/timezone-by-coords";

async function tzFor(lat, lon, signal) {
  const qs = new URLSearchParams({ lat: String(lat), lon: String(lon) });
  const res = await fetch(`${API}?${qs}`, {
    headers: { "X-API-Key": "YOUR_KEY" },
    signal,
  });
  if (res.status === 404) return { lat, lon, timezone: null, reason: "uncovered" };
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
  return { lat, lon, timezone: data.timezone, offset: data.utc_offset, dst: data.is_dst };
}

async function mapPool(items, limit, fn) {
  const out = new Array(items.length);
  let i = 0;
  const workers = Array.from({ length: limit }, async () => {
    while (i < items.length) {
      const idx = i++;
      out[idx] = await fn(items[idx], idx);
    }
  });
  await Promise.all(workers);
  return out;
}

const markers = [
  { lat: 37.7749, lon: -122.4194 },
  { lat: 51.5074, lon: -0.1278 },
  { lat: -33.8688, lon: 151.2093 },
];

const results = await mapPool(markers, 4, (m) => tzFor(m.lat, m.lon));
console.log(results.map((r) => `${r.lat},${r.lon} → ${r.timezone} ${r.offset}`));

Tips

  • Cache by rounded coordinate. Round to 3 decimals (~110 m) before using a coordinate as a cache key — that matches the resolution of any practical timezone boundary and collapses adjacent markers onto one lookup.
  • Never round-trip through a country lookup. Asking for a country then hard-coding "countries have one timezone each" breaks on the US, Russia, Australia, Canada, Brazil, Indonesia, and every country with a DST split.
  • Store the IANA name, derive the offset. IANA names are stable; offsets are not.
  • Etc/GMT signs are inverted relative to common sense in the IANA database (Etc/GMT+5 is UTC−5). You get this for free from the endpoint, but it bites when you format offsets yourself.
  • Treat 404 as data, not failure. Log it and fall back to a continental default; don't retry — the coordinate will never resolve.
  • Prefer this over ip-lookup for a device's zone. IP geolocation is city-level at best and wrong for VPN users; a GPS or browser-geolocation coordinate is exact.