Timezones

3 endpoints for timezone conversion, coordinate-based lookup, and current offset/DST metadata.

Endpoint Purpose
GET /v1/geo/timezone-convert Convert a timestamp from one IANA timezone to another
GET /v1/geo/timezone-by-coords Resolve the IANA timezone name for a lat/lon pair
GET /v1/geo/timezone-info Current UTC offset, DST status, and local time for a timezone

Base URL: https://geo.toolkitapi.io Auth: X-API-Key header on every call.

⚠️ Query-parameter aliases. FastAPI registers these endpoints with aliases, so the wire-name and the internal name differ:

Wire (what you send) Internal name Endpoint
from from_tz timezone-convert
to to_tz timezone-convert
timezone tz timezone-info

Sending from_tz= / to_tz= / tz= to the HTTP API yields 422 — only the alias is accepted on the wire. The Python SDK (geo.timezone_convert(..., from_tz=..., to_tz=...)) uses the internal names because it calls the function directly. Watch out if you copy SDK snippets into raw HTTP requests.

Convert between timezones

GET /v1/geo/timezone-convert

Parameters

Parameter Alias on wire Type Required Description
timestamp timestamp string ✅ ISO 8601 timestamp. Naive (no offset) is interpreted as local time in from; offset-aware is converted from that offset. A trailing Z is treated as +00:00.
from_tz from string ✅ Source IANA timezone, e.g. America/New_York.
to_tz to string ✅ Target IANA timezone, e.g. Europe/London.

Example

curl --get "https://geo.toolkitapi.io/v1/geo/timezone-convert" \
  --data-urlencode "timestamp=2026-06-01T09:00:00" \
  --data-urlencode "from=America/New_York" \
  --data-urlencode "to=Europe/London" \
  -H "X-API-Key: YOUR_KEY"
const params = new URLSearchParams({
  timestamp: "2026-06-01T09:00:00",
  from: "America/New_York",   // alias — NOT from_tz
  to: "Europe/London",        // alias — NOT to_tz
});
const resp = await fetch(`https://geo.toolkitapi.io/v1/geo/timezone-convert?${params}`, {
  headers: { "X-API-Key": "YOUR_KEY" },
});
const data = await resp.json();
console.log(`${data.from_time} → ${data.to_time} (${data.offset_diff_hours}h)`);
import os
import httpx

resp = httpx.get(
    "https://geo.toolkitapi.io/v1/geo/timezone-convert",
    params={
        "timestamp": "2026-06-01T09:00:00",
        "from": "America/New_York",
        "to": "Europe/London",
    },
    headers={"X-API-Key": os.environ["TOOLKIT_API_KEY"]},
    timeout=15,
)
resp.raise_for_status()
r = resp.json()
print(r["to_time"], r["offset_diff_hours"])
Response
{
  "from_timezone": "America/New_York",
  "to_timezone": "Europe/London",
  "from_time": "2026-06-01T09:00:00-04:00",
  "to_time": "2026-06-01T14:00:00+01:00",
  "offset_diff_hours": 5.0
}

from_time is the input re-stamped with the source offset (EDT, -04:00); to_time is the same instant in the target zone (BST, +01:00). The gap is 5h because both zones are on summer time — in January the same conversion yields offset_diff_hours: 5.0 as well, but from -05:00 to +00:00. Never assume the difference is constant across the year without accounting for DST.

Naive vs offset-aware input

You send Interpretation
2026-06-01T09:00:00 09:00 local in from
2026-06-01T09:00:00Z 09:00 UTC, then rendered in from (05:00-04:00)
2026-06-01T09:00:00+02:00 09:00 at +02:00, then rendered in from (03:00-04:00)

If you already have a UTC instant, prefer the Z form and set from=UTC to avoid a double conversion surprising you.

Resolve timezone from coordinates

GET /v1/geo/timezone-by-coords

Parameters

Parameter Type Required Constraints Description
lat float ✅ −90 … 90 Latitude in decimal degrees.
lon float ✅ −180 … 180 Longitude in decimal degrees.

lat/lon have no aliases — send them by name.

curl "https://geo.toolkitapi.io/v1/geo/timezone-by-coords?lat=51.5074&lon=-0.1278" \
  -H "X-API-Key: YOUR_KEY"
const resp = await fetch(
  "https://geo.toolkitapi.io/v1/geo/timezone-by-coords?lat=51.5074&lon=-0.1278",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const { timezone, utc_offset, is_dst } = await resp.json();
console.log(`${timezone} (UTC${utc_offset}, DST: ${is_dst})`);
Response
{
  "latitude": 51.5074,
  "longitude": -0.1278,
  "timezone": "Europe/London",
  "utc_offset": "+01:00",
  "is_dst": true
}

For points over water — including large parts of the ocean — there is no timezone polygon and the endpoint returns 404:

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

Handle that explicitly; a 404 here is a normal geographical answer, not a bug. Cities with offshore addresses (harbours, oil platforms, island resorts) hit this surprisingly often.

Get timezone metadata

GET /v1/geo/timezone-info

Parameters

Parameter Alias on wire Type Required Description
tz timezone string ✅ IANA timezone name.
curl --get "https://geo.toolkitapi.io/v1/geo/timezone-info" \
  --data-urlencode "timezone=America/New_York" \
  -H "X-API-Key: YOUR_KEY"
const resp = await fetch(
  "https://geo.toolkitapi.io/v1/geo/timezone-info?timezone=Asia%2FKolkata",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const info = await resp.json();
console.log(`${info.timezone}: UTC${info.utc_offset} — ${info.current_time}`);
Response
{
  "timezone": "America/New_York",
  "utc_offset": "-04:00",
  "utc_offset_hours": -4.0,
  "is_dst": true,
  "dst_name": "EDT",
  "standard_name": null,
  "current_time": "2026-10-31T00:12:44.123456-04:00"
}

dst_name and standard_name are mutually exclusive: whichever name is not currently in effect comes back null. So outside DST you get "dst_name": null, "standard_name": "EST". The abbreviation is whatever the platform's tz database reports for the current instant (%Z), so it reflects the active offset rather than a fixed pair.

current_time includes microseconds — trim it if you are displaying it.

Response field reference

timezone-convert

Field Type Description
from_timezone string Echo of the source zone
to_timezone string Echo of the target zone
from_time string Input instant rendered in the source zone (ISO 8601 with offset)
to_time string The same instant in the target zone
offset_diff_hours float to_offset − from_offset, rounded to 2 dp. Negative when the target is behind the source.

timezone-by-coords

Field Type Description
latitude / longitude float Echo of the input
timezone string IANA name, e.g. Europe/Paris
utc_offset string Offset now, e.g. +02:00
is_dst bool DST currently active in that zone

timezone-info

Field Type Description
timezone string IANA name (echo)
utc_offset string Offset now, e.g. -04:00
utc_offset_hours float Same value as decimal hours, e.g. -4.0
is_dst bool DST currently active
dst_name string | null Abbreviation in effect if on DST (e.g. EDT), else null
standard_name string | null Abbreviation in effect if off DST (e.g. EST), else null
current_time string Server's current local time in that zone (ISO 8601, microsecond precision)

Error cases

Status Endpoint When detail
400 convert Unknown zone in from or to Unknown timezone: EST
400 convert Unparseable timestamp Invalid timestamp: Invalid isoformat string: '2026-13-01'
400 info Unknown zone Unknown timezone: Mars/Olympus
404 by-coords Point falls outside all timezone polygons No timezone found for coordinates (0.0, -30.0). This may be in international waters.
422 convert Used from_tz/to_tz instead of from/to Pydantic missing for from, to
422 by-coords lat outside −90…90 or lon outside −180…180 {"type":"less_than_equal","loc":["query","lat"], ...}
422 any Required parameter absent, or lat=abc {"type":"float_parsing", ...}
401 any Missing/invalid X-API-Key Invalid or missing API key
503 by-coords Polygon dataset unavailable on the server timezonefinder library not installed

Timezone abbreviations (EST, BST, CET) are always rejected — they are ambiguous (CST alone covers six different offsets). Use full IANA names.

Tips

  • URL-encode the slash. America/New_York in a raw query string works with most servers but breaks with some proxies; --data-urlencode and URLSearchParams handle it for you. %2F is always safe.
  • offset_diff_hours is a snapshot, not a constant. It is computed at the instant you pass in, so it already reflects whatever DST rules apply to that date. Schedule a January and a July meeting and the same zone pair can differ.
  • Chain IP → timezone in two calls. GET /v1/geo/ip-lookup gives latitude/longitude; feed them into timezone-by-coords for the precise zone. IP-derived city is accurate but its timezone field can be coarser.
  • Prefer timezone-by-coords over a static lat/lon→zone table. Border regions and DST carve-outs (e.g. US/Arizona, Spanish enclaves in Morocco) are wrong in hand-rolled approximations.
  • timezone-info is a clock read, so it is not cacheable. If you render local times for many rows, call timezone-by-coords/timezone-info once per distinct zone and compute offsets locally, or use timezone-convert with a fixed timestamp.
  • Store UTC, convert on display. Use these endpoints at the presentation edge; keeping a converted string in your database loses the DST context.
  • utc_offset_hours saves a parse. It is the decimal-hours twin of utc_offset, handy when you need arithmetic rather than a display string.
  • Kolkata is the half-hour test case. Asia/Kolkata returns +05:30; anything that assumes whole-hour offsets will fail there first.