My Geocode

Guides

Add a local-time clock widget to a support dashboard

· 3 min read · My Geocode · #timezone#support#dashboard

A support agent deciding whether to call a customer right now benefits from knowing what time it actually is where that customer sits, not what time it is at the office.

Getting the customer's time zone

If you already have a shipping or billing address on file, geocode it once to get coordinates, then pass those coordinates to /v1/timezone. If all you have is the IP address from their last visit, the /v1/ip endpoint returns a timezone field directly, without a separate lookup.

GET /v1/timezone?lat=35.6762&lon=139.6503
{
  "status": "ok",
  "timezone": "Asia/Tokyo",
  "utc_offset": "+09:00",
  "abbreviation": "JST"
}

When neither an address nor an IP is on file

For a lead or a ticket with no address and no recorded IP, there is no reliable coordinate to look up a time zone from, and guessing based on a phone country code or a language setting is not something this endpoint can do for you. Ask for a time zone or a rough location directly in that case, rather than displaying a clock built from a guess that has a real chance of being wrong by several hours.

Rendering the clock

Store the timezone identifier against the customer record, then compute the current local time from it whenever the dashboard renders, rather than storing a fixed offset that will drift out of date around daylight saving changes. Since the site has no client-side JavaScript, render the current local time server-side at page load and refresh it on each page request rather than ticking it live in the browser.

One lookup per customer, not per page view

The time zone identifier for a customer's location does not change day to day, so look it up once when the address or IP is first recorded and store the identifier, rather than calling the API every time the dashboard loads. That keeps this feature to a handful of requests total rather than one per page view, which matters if the dashboard is opened many times a day by a support team.

A mistake worth avoiding

Recomputing an offset for a past support interaction using today's timezone lookup, rather than the timestamp of the interaction itself, can show the wrong hour around a daylight saving change. If a dashboard needs to show what local time it was for the customer at the moment a past ticket was filed, pass that ticket's own timestamp through the time parameter rather than relying on the current offset.

What it costs

Even without caching the identifier, each lookup is a single request, so a support team of any reasonable size fits comfortably inside the 2,500 free requests a day included with every key, or the same allowance from a single address without one.

Keeping it current

If a customer's address on file changes, refresh the stored timezone identifier at the same time, rather than leaving a stale one attached to the record indefinitely. A relocated customer with an old timezone identifier will show the wrong local time until the record is updated, quietly, since nothing about the old lookup fails or errors out on its own.

A local-time clock next to a ticket is a small addition that saves a support agent from doing time zone arithmetic in their head before every call. The timezone lookup docs cover the request in full.

More in Guides