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_offsetandis_dstfields 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)
Related Endpoints¶
/v1/geo/timezone-convert— convert a timestamp between timezones/v1/geo/timezone-info— get UTC offset and DST details for a named timezone/v1/geo/ip-lookup— get lat/lon from an IP address, then pass here for the timezone
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/GMTsigns are inverted relative to common sense in the IANA database (Etc/GMT+5is UTC−5). You get this for free from the endpoint, but it bites when you format offsets yourself.- Treat
404as data, not failure. Log it and fall back to a continental default; don't retry — the coordinate will never resolve. - Prefer this over
ip-lookupfor a device's zone. IP geolocation is city-level at best and wrong for VPN users; a GPS or browser-geolocation coordinate is exact.
Related¶
- Timezone conversion & info —
timezone-convert,timezone-info, DST transitions over time - Geographic math — distances, bounding boxes, centroids for map clustering
- IP intelligence — IP-derived location when you have no coordinates