Timezone transitions

Returns every offset or abbreviation change, such as a daylight saving start or end, for the timezone(s) covering a coordinate between from and to. Use it to schedule across a DST boundary or to know exactly when a zone's clocks change. For the current offset and the next change only, use the timezone endpoint. Endpoint: GET /v1/timezone/transitions.

How it worksCopy Anchor Link

1. A PostGIS point-in-polygon lookup (ST_Covers) against the timezone-boundary-builder polygons (release 2026f) finds the IANA zone(s) at lat/lon.

2. For each zone, the gateway scans the range one day at a time using the Node ICU tzdata, which is pinned to the same tzdb release. When the offset or abbreviation differs across a day, it bisects down to the exact second.

No routing or geocoding Engine is involved, and no external service is called. The response reports the tzdb release that ICU actually loaded as tzdb_version.

Quick startCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/timezone/transitions?lat=43.65&lon=-79.38&from=2027-01-01T00:00:00Z&to=2028-01-01T00:00:00Z&apiKey=$GRAPHITE_API_KEY"

{
  "lat": 43.65,
  "lon": -79.38,
  "from": "2027-01-01T00:00:00Z",
  "to": "2028-01-01T00:00:00Z",
  "tzdb_version": "2026f",
  "timezones": [
    {
      "name": "America/Toronto",
      "transitions": [
        {
          "at": "2027-03-14T07:00:00Z",
          "before": { "type": "standard", "utc_offset": "-05:00", "offset_seconds": -18000, "abbreviation": "EST" },
          "after": { "type": "daylightSaving", "utc_offset": "-04:00", "offset_seconds": -14400, "abbreviation": "EDT" },
          "offset_change_seconds": 3600,
          "kind": "daylight-start"
        },
        {
          "at": "2027-11-07T06:00:00Z",
          "before": { "type": "daylightSaving", "utc_offset": "-04:00", "offset_seconds": -14400, "abbreviation": "EDT" },
          "after": { "type": "standard", "utc_offset": "-05:00", "offset_seconds": -18000, "abbreviation": "EST" },
          "offset_change_seconds": -3600,
          "kind": "daylight-end"
        }
      ]
    }
  ]
}

ParametersCopy Anchor Link

Full parameter reference

ResponseCopy Anchor Link

type is standard when the offset equals the smaller of the zone's January and July offsets that year, daylightSaving when larger, and other when smaller. The abbreviation may be a GMT offset such as GMT-5 where tzdb has no abbreviation.

No place_id, datasource or rank is returned by this endpoint.

Differences from GeoapifyCopy Anchor Link

• approximated: the interval is (from, to]. A transition exactly at from is not listed; one exactly at to is. Geoapify uses [from, to).

• approximated: the maximum span is 50 years, and any date is accepted. Geoapify limits the span to 366 days within 2025-01-01 to 2032-01-01.

• extra: timezones can hold zero or several zones (overlapping polygons), and at is rendered without fractional seconds. Offsets are computed for each zone name directly.

Nothing from Geoapify's parameter list is dropped.

US and Canada notesCopy Anchor Link

Zones come from the full timezone-boundary-builder release, not from a US/Canada extract, so the lookup is not limited to the two countries. Both examples on this page are in the two countries: Toronto observes DST, and Indianapolis (America/Indiana/Indianapolis) is a distinct IANA zone that has the same 2027 transitions as the Eastern zone.

More examplesCopy Anchor Link

Indianapolis, calendar year 2027. Shows the Indiana zone name and the same DST pair of changes.

curl -s "https://api.data.graphitelab.ai/v1/timezone/transitions?lat=39.77&lon=-86.16&from=2027-01-01T00:00:00Z&to=2028-01-01T00:00:00Z&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

Limits: from and to must be RFC 3339 date-times, and to - from must not exceed 50 x 366 days.