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 fromfrom_tztimezone-converttoto_tztimezone-converttimezonetztimezone-infoSending
from_tz=/to_tz=/tz=to the HTTP API yields422— 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_Yorkin a raw query string works with most servers but breaks with some proxies;--data-urlencodeandURLSearchParamshandle it for you.%2Fis always safe. offset_diff_hoursis 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-lookupgiveslatitude/longitude; feed them intotimezone-by-coordsfor the precise zone. IP-derived city is accurate but its timezone field can be coarser. - Prefer
timezone-by-coordsover 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-infois a clock read, so it is not cacheable. If you render local times for many rows, calltimezone-by-coords/timezone-infoonce per distinct zone and compute offsets locally, or usetimezone-convertwith 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_hourssaves a parse. It is the decimal-hours twin ofutc_offset, handy when you need arithmetic rather than a display string.- Kolkata is the half-hour test case.
Asia/Kolkatareturns+05:30; anything that assumes whole-hour offsets will fail there first.
Related¶
- Timezone by Coordinates — coordinate lookup details
- IP Intelligence — get lat/lon for an IP first
- Geographic Math — distance, bearing, and midpoint helpers
- Country & Currency Data — per-country reference data including phone prefixes