---
title: "Get UTC offset at datetime for coordinates"
method: POST
path: "/timezone/offset"
tags: ["location-timezone"]
---

# Get UTC offset at datetime for coordinates

`POST /timezone/offset`

## Request

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

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

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- TimezoneOffsetRequest: Request to compute UTC offset for a coordinate at a specific instant. Coordinates may be supplied as either `lat`/`lon` (canonical) or `latitude`/`longitude` (accepted alias, matching `/timezone/lookup`). Exactly one complete pair is required; if both pairs are present the canonical `lat`/`lon` wins. A request with no complete coordinate pair is rejected with a 422 validation error — coordinates never default to 0,0. Exactly one of `datetime_utc` (an instant) or `datetime_local` (a naive local wall time resolved at the coordinate, honoring the historical-correction overlay) is required. Note: `datetime_utc` is a strict RFC 3339 instant and must carry a zone (`Z` or ±HH:MM). A zone-less value is rejected.
  - `datetime_local` string: 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_utc` string, 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.
  - `lat` number: Latitude in decimal degrees. Canonical spelling; alias of 'latitude'.
  - `latitude` number: Latitude in decimal degrees. Accepted alias of 'lat'; ignored when 'lat' is present.
  - `lon` number: Longitude in decimal degrees. Canonical spelling; alias of 'longitude'.
  - `longitude` number: 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.

## Response `200`

Successful Response

- TimezoneOffsetResponse: Offset details for a coordinate at a specific instant.
  - `calculation_metadata` CalculationMetadata: Metadata about chart calculations. Relaxed to allow minimal fields used by tests while remaining forward-compatible.
    - `ascendant_on_left` boolean, nullable: When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.
    - `ayanamsa` union: Sidereal ayanamsa selection
      - 'lahiri' | 'fagan_bradley' | 'krishnamurti' | 'raman' | 'yukteshwar': Supported sidereal ayanamsa options. All five are computed from the same IAU 2006 general-precession model, so each is epoch-dependent rather than a frozen constant; they differ by up to ~2.3 degrees, which is enough to move a body across a sign boundary. Defaults to lahiri when zodiac_type is sidereal and no system is named.
      - string
    - `calculation_time` number: Legacy calculation time in seconds
    - `calculation_time_ms` number: Processing time at the orchestrator layer in milliseconds
    - `calculation_time_utc` string, date-time: UTC timestamp when the calculation executed
    - `coordinate_reference_frame` string: Coordinate frame the positions are expressed in. The engine computes apparent places referred to the true equator/equinox of date and converts them to the true ecliptic of date, so this reads geocentric_true_ecliptic_of_date.
    - `coordinate_system` union: Coordinate system used (geocentric/topocentric)
      - 'geocentric' | 'topocentric' | 'heliocentric' | 'barycentric': Coordinate system used for calculations.
      - string
    - `delta_t_seconds` number: Delta T (TT - UT1) applied during calculation, in seconds
    - `delta_t_source` union: Source of Delta T values (computation engine, IERS, approximation)
      - 'nasa_jpl' | 'iers' | 'approximation_model': Source of ΔT values used in calculations.
      - string
    - `ephemeris_source` string: Primary ephemeris source (e.g., SuperNOVAS / Calceph)
    - `ephemeris_version` string: Version of the ephemeris data files
    - `fixed_star_catalog` union: Fixed star catalog or subset identifier
      - 'bright_mag3' | 'bright_mag5' | 'royal_stars' | 'parans_key': Fixed star catalog snapshots.
      - string
    - `house_system` union: House system actually used during calculation
      - 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems.
      - string
    - `include_fixed_stars` boolean: Whether fixed stars were included
    - `julian_day` number, double: Julian Day Number representing the calculation instant
    - `missing_objects` object: Objects that could not be calculated along with reasons
    - `node_source` union: Lunar node/apsides mode requested (true osculating, mean, apsides)
      - 'true_osculating' | 'mean' | 'mean_apsides': Node/apsides calculation modes (SE §2.2).
      - string
    - `object_set` union: Named object set or preset powering the calculation
      - 'traditional_7' | 'modern_10' | 'modern_plus_chiron' | 'asteroids_major' | 'full' | 'custom': Standardized celestial object bundles.
      - string
    - `orb_system_used` string: Aspect orb system applied
    - `precision_level` string: Legacy precision descriptor
    - `precision_summary` PrecisionSummary: Structured precision report for calculation metadata.
      - `max_position_error_arcseconds` number: Maximum validated positional error in arcseconds
      - `max_timing_error_seconds` number: Maximum validated timing error in seconds
      - `notes` string: Additional human-readable context for the precision summary
      - `reference_profile` string: Reference dataset or validation profile used for the comparison
    - `processing_time_ms` number: End-to-end processing time in milliseconds
    - `server_version` string: Build identifier of the engine that produced this response. Moves on every deploy, so it is the signal for resolution-LOGIC changes — the class of change that can move a historical offset without touching overlay data (and therefore without moving tz_overlay_version). Poll both.
    - `sidereal_time` number: Local sidereal time in hours
    - `technique_id` string: High-level technique identifier (e.g., natal, synastry, composite, overlay)
    - `technique_label` string: Human-readable technique label
    - `technique_method` string: Method name within a technique (e.g., davidson, midpoint)
    - `technique_version` string: Technique implementation version (for future-proofing)
    - `time_scale` union: Time scale used for internal calculations (UTC, TT, TDB)
      - 'UTC' | 'TT' | 'TDB': Time scale used for reporting results.
      - string
    - `tz_overlay_hash` string: Content hash of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied (tz_rule_source starts with 'overlay:').
    - `tz_overlay_version` integer: Monotonic version of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied. Tracks overlay DATA only — pair with server_version to also catch resolution-logic changes.
    - `tz_precision` 'statutory' | 'documented' | 'inferred': Sourcing grade of the overlay row that produced the offset: '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). Stamped only when an overlay row applied.
    - `tz_rule_citation` string: Primary-source citation for the overlay row that produced the offset — statute reference, ICC/agency order number, or documented press/almanac source. Stamped only when an overlay row applied.
    - `zodiac_type` union: Zodiac framework applied (tropical/sidereal)
      - 'tropical' | 'sidereal': Supported zodiac frameworks.
      - string
  - `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.
  - `fallback` boolean: True when a generic/UTC fallback was used
  - `is_dst` boolean, required: Whether DST is in effect at the instant
  - `offset_hours` number, required: UTC offset in fractional hours at the given instant
  - `offset_seconds` integer, required: UTC offset in seconds at the given instant
  - `offset_string` string, required: UTC offset formatted as ±HH:MM
  - `resolved_utc` string: For datetime_local requests: the UTC instant the local wall time resolved to (RFC 3339).
  - `timezone` string, 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_hash` string: 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_version` integer: 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_source` string: What determined the offset: 'tzdata', an overlay row id (e.g. 'overlay:us-mn-statewide-1959-1966'), or 'time_standard:<mode>'.

## Other responses

- `400`: Bad Request - Input validation failed
- `422`: Unprocessable Entity - Invalid input format
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)