My Geocode

Guides

Convert a UTC timestamp to local time for your users

· 3 min read · My Geocode · #timezone#utc#localization

Storing timestamps in UTC is the right call for a database. Showing UTC to a user in a support ticket, an order confirmation, or an activity log is not, and it is one of the more common small frustrations in a product's interface.

The conversion in two steps

First, know where the timestamp should be interpreted from, either the coordinates of an address on file or coordinates from an IP lookup. Second, pass those coordinates and the UTC timestamp itself to /v1/timezone using the time parameter, so the offset returned matches the moment in question rather than the current moment.

GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000
{
  "status": "ok",
  "timezone": "America/New_York",
  "utc_offset": "-05:00",
  "abbreviation": "EST"
}

Apply the utc_offset to your stored UTC timestamp, or pass the timezone identifier into your own date formatting code, and display the result instead of the raw UTC value.

A second example, months apart

The same coordinates return a different offset depending on the timestamp you pass in, which is the whole reason the time parameter exists.

GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000
{
  "status": "ok",
  "timezone": "America/New_York",
  "utc_offset": "-04:00",
  "abbreviation": "EDT"
}

Notice the offset moved from minus five hours to minus four hours between the two calls for the exact same location, purely because one timestamp falls in daylight saving and the other does not. A display that ignored this and applied a single fixed offset to both would be an hour off on one of them.

Why the time parameter matters

An offset changes across the year in most places that observe daylight saving. If you only ever call the endpoint without a time parameter, you get today's offset, which will be wrong for a timestamp from six months ago. Always pass the timestamp you are converting, not the current time, when the two might fall on opposite sides of a daylight saving change.

Caching the time zone, not the offset

The time zone identifier for a given set of coordinates rarely changes, so it is safe to cache the timezone string itself against a location. The utc_offset and abbreviation values are not safe to cache for long, since they shift with daylight saving, so recompute those at display time rather than storing them.

An edge case worth knowing

Not every location observes daylight saving at all. A location that stays on a fixed offset year round will return the same utc_offset regardless of which timestamp you pass, which is expected behavior rather than a sign that the time parameter was ignored. Do not assume a fixed result across two different timestamps means something is broken.

Request cost

One conversion is one request. A dashboard that converts times for many stored records at once should batch the underlying coordinates through a bulk POST rather than looping one timestamp at a time, keeping the same one request per item cost but in a single call.

Getting local time right matters more than most teams expect until a support ticket shows the wrong hour. Details on the request and response fields are in the timezone lookup docs.

More in Guides