Use cases

Showing the right local time in a multi-region support queue

A support agent in one office looking at a ticket filed at "3:47 AM" has no idea if that is late for the customer or the middle of their workday. Time stamps without a time zone attached are close to useless when a company's customers span several continents, and a software company with support desks in three regions ran into this constantly. Agents were opening tickets, checking a customer's billing country, then manually looking up whether that country was ahead or behind, and getting it wrong often enough that "sorry to bother you this early" became a running joke in the office.

The company replaced the guesswork with two calls made when a ticket comes in. First, /v1/ip reads the visitor's IP address and returns country, region, city and coordinates, along with a time zone field directly on the same response. For most tickets that field alone was enough. For the smaller number of cases where more precision mattered, such as scheduling a callback, the coordinates from that lookup were passed to /v1/timezone, which returns the IANA time zone name and the current UTC offset for that exact point, optionally calculated for a specific moment rather than right now.

The IANA name matters more than it sounds like it should. A raw UTC offset changes with daylight saving rules that differ by country and sometimes by region within a country, so storing "UTC+2" against a customer record quietly becomes wrong twice a year. Storing "Europe/Warsaw" instead means the offset is always calculated correctly for whatever date a ticket or callback is scheduled, because the time zone database that drives it tracks those rule changes as they happen.

The visible change was a small line at the top of every ticket: the customer's local time, right now, next to their name. Agents stopped asking "is it late where you are" and started opening messages with an accurate "good afternoon" instead. Ticket routing improved too, once the queue could sort by which customers were currently inside working hours in their own region rather than by which support desk happened to be staffed.

None of this needed a database of country-to-timezone mappings maintained by hand, which is the approach the company had cobbled together before and which broke every time a customer's IP resolved to a large country spanning multiple zones. Reading the time zone directly from the coordinates removed that whole category of error.

Volume was light, one lookup per new ticket, well inside the 2,500 free requests a day included with the company's key. The support tool alone never came close to needing prepaid credit, though the same key covered other parts of the product that did.

Time zone handling is one of those details that customers only notice when it is wrong. Getting it right, quietly, in the background of every ticket, is a small fix with an outsized effect on how a support team comes across. Documentation for both endpoints is at /docs/ipv4-lookup/ and /docs/timezone-lookup/.