June 16, 2026 · 7 min read · Use cases

Time zones are a first-order concern in itinerary APIs.

A traveller plans Tokyo to Singapore to Sydney. Three legs, three zones, offsets ranging from one to seven hours apart depending on the season. Generic LLMs do this arithmetic in their head and ship it wrong roughly a third of the time. The fix is structural, not prompt-based.

The four ways generic itinerary builders break

We've stress-tested itinerary chatbots from the major frontier labs against a fixed set of multi-leg international trips. The error modes cluster.

First: forgetting that the destination has a different offset at all. A 22:00 departure from Tokyo arrives in Singapore at "local time about nine hours later" — except Singapore is one hour behind, so the local arrival clock reads earlier than the elapsed flight time would suggest. Models guess.

Second: applying daylight savings to places that don't observe it. Tokyo, Singapore, Bangkok, Hong Kong, most of Australia's east coast in southern summer — the rules are not symmetric. A model that learned "summer means +1" trips on this constantly.

Third: half-hour and quarter-hour zones. Mumbai is UTC+5:30. Kathmandu is UTC+5:45. Adelaide is UTC+9:30 (or +10:30 in southern summer). Caracas used to be UTC-4:30. Models routinely round these to whole hours.

Fourth: historical offsets. A traveller looking at a 2019 booking confirmation in Cairo gets the wrong local time if the model applies today's rules retroactively. Egypt added DST back in 2023 after a long pause; the IANA database knows, the model usually doesn't.

The structural fix

Don't ask the model to compute time. Ask the model to plan the trip, and ask a time zone library to compute the time. The split is exactly what tool-use was designed for.

Our /v1/cities response returns lat/lon for every city. From a coordinate pair, your client can resolve a tz database identifier (Asia/Tokyo, Asia/Singapore, Australia/Sydney) using any of the standard libraries — timezonefinder in Python, tz-lookup in Node, GeoTimeZone in .NET. Then Python's zoneinfo, JavaScript's Intl.DateTimeFormat, or your platform's equivalent does the actual offset math, with the IANA tz database doing the historical and DST work for you.

A worked example

A traveller leaves Tokyo on 14 July 2026 at 22:30 local. Flight to Singapore is 7h20. Layover 5h. Flight to Sydney is 8h05. Question: when do they land in Sydney, in Sydney local time?

GET /v1/cities?names=tokyo,singapore,sydney
[
  {"name": "Tokyo",     "lat": 35.6762, "lon": 139.6503},
  {"name": "Singapore", "lat":  1.3521, "lon": 103.8198},
  {"name": "Sydney",    "lat": -33.8688, "lon": 151.2093}
]

Resolve each coordinate to a tz id. Then the leg math:

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

depart_tokyo = datetime(2026, 7, 14, 22, 30, tzinfo=ZoneInfo("Asia/Tokyo"))
arrive_sg    = depart_tokyo + timedelta(hours=7, minutes=20)
print(arrive_sg.astimezone(ZoneInfo("Asia/Singapore")))
# 2026-07-15 04:50:00+08:00

depart_sg = arrive_sg + timedelta(hours=5)
arrive_syd = depart_sg + timedelta(hours=8, minutes=5)
print(arrive_syd.astimezone(ZoneInfo("Australia/Sydney")))
# 2026-07-15 19:55:00+10:00

Zero ambiguity. The library knows that on 14 July 2026 Sydney is on AEST (UTC+10), not AEDT, because southern winter. It knows Singapore doesn't observe DST. It knows Tokyo's offset has been stable for decades. None of this had to live in the prompt.

Edge cases the library still gets right

Reykjavik: UTC+0 year-round, no DST, sits in the same offset as London half the year and an hour behind it the other half. Tehran: famously half-hour offset. Lord Howe Island: the only +10:30/+11 zone left in the world. Casablanca: tracks Ramadan-related DST adjustments. The IANA database tracks all of these. Don't reimplement it.

What the API does and doesn't do

/v1/cities returns coordinates. It does not return tz database identifiers directly — they're computed client-side from lat/lon using a free library, because the polygon dataset is large and changes independently of city data. We considered embedding them, decided against it: tz boundaries shift more often than city centroids, and keeping them client-side keeps your DST rules current without an API redeploy on our side.

The shape we want for itinerary builders: pull cities from us, pull offsets from your tz library, do leg math in datetime-aware code, and leave the LLM to write the prose around the numbers — not produce the numbers itself.