Time zone API

One request. You already have an Unmap key, and you have a coordinate. This returns the IANA timezone and the UTC offset at an instant.

Every request needs an API key; see Authentication. A successful lookup is one normal API call. There is no separate plan to turn on.

curl "https://api.unmap.dev/timezone?lat=51.0447&lon=-114.0719&key=um_live_..."

const timezone = await unmap.timezone.lookup([-114.0719, 51.0447]);

The SDK coordinate is [longitude, latitude]. The HTTP parameters are lat and lon separately.

GET /timezone

{
  "timezone": "America/Edmonton",
  "offset": "-06:00",
  "offsetSeconds": -21600,
  "dst": true
}

That body is Calgary at 2026-07-01T18:00:00Z, still on daylight time. After 2026-11-01, America/Edmonton stays on UTC−6 and dst is false.

timezone is an IANA identifier. offset is the UTC offset at at, ±HH:MM. offsetSeconds is seconds east of UTC. dst is whether that instant is in daylight saving time.

at changes the offset. It does not change which zone the coordinate falls in: the boundary dataset is current, and a historical timestamp still uses today's zone for that point. Offsets before a zone was split can differ from the clock people kept at the time.

curl "https://api.unmap.dev/timezone?lat=51.0447&lon=-114.0719&at=2025-12-15T18:00:00Z&key=um_live_..."

const timezone = await unmap.timezone.lookup([-114.0719, 51.0447], {
  at: new Date("2025-12-15T18:00:00Z"),
});

Out-of-range coordinates are rejected. They are not clamped.

{ "error": "lat must be between -90 and 90", "code": "invalid_coordinate" }

A missing lat or lon is the same code. An at that is not an ISO 8601 instant is 400 with invalid_timestamp. A 400 is not billed.

Ocean

Ocean polygons in the boundary dataset are IANA Etc/GMT zones. Etc/GMT+7 is seven hours west of UTC: the sign is the POSIX convention, reversed from the offset field.

A point that misses every polygon gets the 15° nautical zone for its longitude, also an Etc/GMT zone. The lookup does not borrow the nearest country's timezone.

The lookup is global. A coordinate within about half of 1/125° of a boundary, roughly 500 m, can come back as the neighboring zone. Rules come from the IANA Time Zone Database. Boundaries come from timezone-boundary-builder, which is derived from OpenStreetMap. The two are versioned separately: a new IANA release does not wait on a new boundary file.

GET /timezone/meta

{ "tzdb": "2026d", "boundaries": "2026d", "generatedAt": "2026-09-21T00:00:00Z" }

/timezone/meta is authenticated and rate-limited, and it is not billed. generatedAt is when the active pair was promoted. A day with no upstream change does not move it.

Both releases are checked daily. A changed release is compiled, checked against a global fixture set, and published as a new immutable object. The previous object stays, so a rollback is a manifest change. Credits for the datasets are on the attribution page.