{"uid":"cap_BCWOq10jr4lOGJOhQM6NV","slug":"geoprimitives-timezone-lookup-e869399e","name":"Geoprimitives Timezone Lookup","description":"Give it a longitude and latitude and it answers with the IANA timezone identifier (America/New_York), the UTC offset in force there right now, whether daylight saving is currently in effect and by how much, the local wall-clock time, and the zone's standard offset. Pass an optional ISO 8601 `at` instant to ask about any moment between 1900 and 2100 instead of now, which is what you want when scheduling something months out across a DST boundary. Parameters go in the query string: this is a GET, there is no body. Two halves, with different vintages, and the difference matters. The offset and the DST rules come from the runtime's own timezone database and are current: a rule change reaches this endpoint when Cloudflare updates ICU, with no redeploy here. The *boundaries* come from tz_world (efele.net), CC0 1.0 and derived from VMAP0, a public-domain US government product. That map was frozen at tzdb 2016d in May 2016, and this catalog sells public-domain and permissively-licensed data only, which is why it is used rather than the current OpenStreetMap-derived alternative. What the vintage costs, measured against IANA's own coordinates for all 312 zones in zone1970.tab rather than estimated: 293 agree. Of the 19 that do not, 7 are Antarctic research stations, which this map does not cover at all and which fall back to the open-water rule; 7 more return a different identifier for the identical offset and DST all year (Australia/Brisbane for Australia/Lindeman, America/Regina for America/Swift_Current, and five like them), so the time is right and only the name is old. That leaves four regions where the answer is up to one hour wrong because the zone was split after 2016: Chilean Magallanes and Aysen (answered as America/Santiago rather than America/Punta_Arenas or America/Coyhaique), the Mexican border municipalities around Ciudad Juarez, Saratov Oblast in Russia, and the weeks each spring when Asia/Hebron and Asia/Jerusalem change on different dates. If you query inside one of those, do not trust this endpoint. Boundary precision is a separate question from vintage. The map is indexed as compacted H3 cells at resolution 6, whose half-width is about 1.6 km, chosen to match VMAP0's own stated positional accuracy of roughly 2 km rather than to flatter the index. So a point within a couple of kilometres of a zone border may be attributed to the neighbour, and no amount of the source's precision would fix that because the source does not have it. Away from a border the answer is exact. Every answer says where it came from under `source`. `boundary` means the point is inside a mapped timezone polygon and is the answer you are paying for. `coastal` means it is over water or on land this map does not cover, and the identifier is the nearest zone within about 60 km -- correct for a harbour or a coastal city whose coordinate falls just offshore, and not a boundary result. `nautical` means open water more than about 60 km from mapped land, answered with the tz database's own rule for international waters, meridians 15 degrees apart; it is not the time kept aboard any vessel and it ignores territorial waters. Longitude and latitude are checked against EPSG:4326 bounds before anything else touches them, because H3 silently normalises an out-of-range latitude into a real but wrong cell rather than refusing it. Reproject with POST /v1/transform first if you are not already in WGS 84. The DST flag is decided on offsets rather than on the tz database's own isdst bit, so Europe/Dublin reads as daylight saving in summer like everywhere else, and it is measured over a window either side of the instant so that a zone which changes its standard offset mid-year -- Asia/Almaty in 2024 -- is not mistaken for one on daylight saving.","url":"https://api.geoprimitives.dev/v1/timezone?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":["lat","lon"],"properties":{"at":{"type":"string","format":"date-time","description":"Optional ISO 8601 instant to answer for, e.g. 2026-07-04T16:00:00Z. Defaults to now. Must fall between 1900 and 2100."},"lat":{"type":"number","maximum":90,"minimum":-90,"description":"Latitude in decimal degrees, EPSG:4326. Refused outside -90..90 rather than normalised."},"lon":{"type":"number","maximum":180,"minimum":-180,"description":"Longitude in decimal degrees, EPSG:4326. Refused outside -180..180."}},"additionalProperties":false}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object"}}}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.005","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.005/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Wfz9SipMucpY-4TYMnF_G","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.005","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the IANA timezone identifier, UTC offset, DST status, and local wall-clock time for any latitude/longitude coordinate, optionally at a specified historical or future instant.","exampleAgentPrompt":"What IANA timezone and current UTC offset apply to coordinates 35.6762° N, 139.6503° E, and will daylight saving time be in effect there on 2026-03-15T09:00:00Z?","exampleUseCases":[{"title":"Scheduling across DST boundary","prompt":"I'm scheduling a recurring video call with someone in Denver for every first Monday at 9 AM their local time. Can you tell me what the UTC offset will be at coordinates 39.7392, -104.9903 on 2026-03-09T15:00:00Z so I can set the calendar invite correctly across the spring DST change?"},{"title":"Local time display for field device","prompt":"My IoT sensor just reported GPS coordinates 51.5074, -0.1278 — what's the IANA timezone there and what's the current local wall-clock time, so I can timestamp its readings correctly?"},{"title":"Event planning in remote location","prompt":"I'm organizing an outdoor event at a site at latitude -33.8688, longitude 151.2093 in Sydney. What timezone identifier does that location use, and will daylight saving time be active on 2026-11-01T08:00:00Z when the event starts?"}],"resultDescription":"A JSON object containing the IANA timezone identifier (e.g. America/New_York), the UTC offset currently or at the specified instant, a boolean indicating whether DST is in effect, the DST offset amount, the local wall-clock time, and the zone's standard (non-DST) offset.","failureModes":["Latitude outside -90..90 or longitude outside -180..180 returns a 400 error — values are refused, not normalised","The `at` instant outside the 1900–2100 range returns an error","Coordinates in ocean areas or uncovered territory may not resolve to a timezone polygon (tz_world gap)","Timezone boundary data frozen at tzdb 2016d may be stale for post-2016 political boundary changes — DST rules are current but geographic polygon assignments may be wrong for recently redrawn zones","Network or Cloudflare Worker availability issues can cause 5xx responses"],"whenToPreferThis":"Choose this endpoint when you need a machine-readable IANA timezone identifier and current or future UTC offset from raw geographic coordinates, especially when scheduling across DST boundaries months in advance. Prefer it over IP-based geolocation timezone lookups when you have precise lat/lon. Note that timezone boundary polygons are from tz_world (frozen 2016) so for regions with post-2016 boundary changes, verify independently.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T06:33:52.866Z","isFirstParty":false,"canonicalSlug":"geoprimitives-timezone-lookup-e869399e"}