location-timezone

Get UTC offset at datetime for coordinates

Return the timezone and UTC offset for the provided coordinates and instant.

  • Resolves an IANA timezone from the coordinates
  • Applies the timezone's historical/DST rules at the given instant
  • Returns offset in seconds/hours, a formatted string, and a DST flag
post/timezone/offset

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/timezone/offset
  • Auth: HTTP bearer

Headers

authorizationstring nullable
X-API-Keystring nullable
X-OpenEphemeris-API-Keystring nullable
apikeystring nullable

Request body

datetime_localstring

Naive local wall-clock datetime (YYYY-MM-DDTHH:MM:SS, no zone suffix) to resolve at the coordinate. Mutually exclusive with datetime_utc — exactly one of the two is required. The zone is resolved from the coordinates, the historical-correction overlay is consulted for pre-1970 dates, and the response reports the resolved offset plus tz_confidence.

datetime_utcstring date-time

Instant as a strict RFC 3339 datetime, e.g. '2025-07-01T12:00:00Z'. Must carry a zone ('Z' or ±HH:MM); a zone-less value is rejected.

fold_preference'earlier' | 'later'

Only meaningful with datetime_local: which occurrence of a repeated (fall-back) hour to use. See TimezoneInput.fold_preference.

latnumber

Latitude in decimal degrees. Canonical spelling; alias of 'latitude'.

latitudenumber

Latitude in decimal degrees. Accepted alias of 'lat'; ignored when 'lat' is present.

lonnumber

Longitude in decimal degrees. Canonical spelling; alias of 'longitude'.

longitudenumber

Longitude in decimal degrees. Accepted alias of 'lon'; ignored when 'lon' is present.

time_standard'auto' | 'standard' | 'daylight'

Only meaningful with datetime_local: force interpretation as standard or daylight time instead of the automatic overlay/tzdata resolution. See TimezoneInput.time_standard.

Example request

{
  "datetime_utc": "2025-07-01T12:00:00Z",
  "lat": 37.7749,
  "lon": -122.4194
}

Response

Successful Response

datetime_status'unambiguous' | 'ambiguous_fold' | 'nonexistent_gap'

For datetime_local requests: whether the wall time named exactly one instant, fell in a fall-back fold (genuinely ambiguous ±1h — resolved to the first occurrence unless fold_preference=later), or never appeared on the clock (spring-forward gap — shifted forward). Clients should surface non-unambiguous statuses to the user.

fallbackboolean

True when a generic/UTC fallback was used

is_dstboolean required

Whether DST is in effect at the instant

offset_hoursnumber required

UTC offset in fractional hours at the given instant

offset_secondsinteger required

UTC offset in seconds at the given instant

offset_stringstring required

UTC offset formatted as ±HH:MM

resolved_utcstring

For datetime_local requests: the UTC instant the local wall time resolved to (RFC 3339).

timezonestring required

Resolved IANA timezone (or generic Etc/GMT±N)

tz_confidence'authoritative' | 'historical_estimate' | 'client_override'

Confidence of the offset resolution: 'authoritative' (1970+, IANA tzdata is definitive), 'historical_estimate' (pre-1970 — historical-correction overlay where covered, otherwise tzdata reference-city best effort), 'client_override' (a time_standard forcing determined the offset).

tz_overlay_hashstring

Content hash of the historical-correction overlay dataset that produced this answer. Present only when tz_rule_source starts with 'overlay:'. Moves on any byte change to the dataset, so unlike the integer it cannot be forgotten. Pair with tz_overlay_version to decide whether a stored-chart remediation sweep is needed.

tz_overlay_versioninteger

Monotonic version of the historical-correction overlay dataset that produced this answer. Present only when tz_rule_source starts with 'overlay:' — a pure-tzdata resolution does not depend on the dataset. NOTE: tracks overlay DATA only; a resolution-logic change can move an answer without moving this number, so poll calculation_metadata.server_version as well.

tz_precision'statutory' | 'documented' | 'inferred'

Sourcing grade of the overlay row that produced this answer: 'statutory' (operative text of a session law or statute verified), 'documented' (contemporary reporting), or 'inferred' (deduced from legal context; verify before relying on it near the row's edges). Present only when tz_rule_source starts with 'overlay:' — a pure-tzdata answer has no row to grade.

tz_rule_sourcestring

What determined the offset: 'tzdata', an overlay row id (e.g. 'overlay:us-mn-statewide-1959-1966'), or 'time_standard:<mode>'.

Example response

{
  "calculation_metadata": {
    "technique_id": "natal",
    "technique_label": "Composite (Davison)",
    "technique_method": "davidson",
    "technique_version": "v1"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.