Name: Time Zone API: UTC Offset, DST and Time Conversion
Brand: leadharbor
SKU: api-leadharbor-time-zone
Availability: InStock
Author: API Market

Mohammed Samaan

# Time Zone API

## Overview

The Time Zone API answers time zone questions from the IANA tz database. It has one endpoint, `/v1/market/timezone`, with three operations chosen by the `op` parameter. `op=info` takes an IANA zone name such as `America/New_York` and returns the current local time, UTC offset, abbreviation, whether daylight saving time is in effect, the next DST transition with the offsets before and after it, and the countries that use the zone. `op=convert` converts a local wall time from one zone to another and returns both local times with their offsets and the UTC instant. `op=country` lists every zone of a country with its current offset and local time.

It is built for developers of scheduling, booking and calendar tools, teams that send notifications at local times, and anyone who needs to turn "3 pm in Muscat" into the right time in New York without shipping their own tz data. Responses are flat JSON: ISO 8601 date-times with offsets (for example `2026-10-20T07:00:00-04:00`), offsets as `+HH:MM` strings and, in `op=info`, also as `utc_offset_minutes`. DST edge cases are handled explicitly: a local time that does not exist because clocks jumped forward is refused, and a local time that happens twice when clocks go back is flagged `ambiguous` and resolved to its first occurrence. Every response also carries a `meta` object that you can ignore.

## Features

*   **1 endpoint, 3 operations**: `op=info` for a zone's current state, `op=convert` to convert a local time between zones, and `op=country` to list a country's zones.
*   **Simple inputs**: IANA zone names (`zone`, `from`, `to`), a local time as `YYYY-MM-DDTHH:MM`, and an ISO country code such as `US`.
*   **Next DST transition**: `op=info` names the instant of the next change and the offset before and after it.
*   **DST edge cases**: Times inside a DST gap are rejected with `400`, and repeated times are flagged `ambiguous` and resolved to the first occurrence.
*   **Country zones**: `op=country` returns every zone of a country, each with its current offset and local time.
*   **Data source**: Zone rules come from the IANA tz database, and country lists come from its `zone.tab` file.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Meeting scheduling**: Convert a proposed slot from the organiser's zone into each attendee's zone.
*   **Local-time notifications**: Work out the UTC instant for "9:00 local" before queueing an email or push message.
*   **DST warnings**: Show users when the next clock change happens in their zone and how the offset will move.
*   **Zone pickers**: Fill a time zone dropdown with the zones of the user's country.
*   **Booking systems**: Store bookings as UTC and display them in the venue's local time with the correct offset.
*   **Data cleaning**: Normalise timestamps recorded in local time to UTC before analysis.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/leadharbor/time-zone
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

All three operations use the same endpoint and the same parameters. The `op` parameter selects the operation, and each example below shows one operation.

#### 1. Time zone lookups and conversion

Returns the current state of a zone (`op=info`), a local time converted between two zones (`op=convert`), or the zones of a country (`op=country`).

**Method:** `GET`

**Endpoint:** `/v1/market/timezone`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `op` | query | Operation: `info`, `convert` or `country`. | string | No | `info` | - |
| `zone` | query | `op=info`: IANA zone name, for example `America/New_York`. | string | No | - | - |
| `time` | query | `op=convert`: local wall time in the source zone, as `YYYY-MM-DDTHH:MM`. | string | No | - | - |
| `from` | query | `op=convert`: source IANA zone, for example `Asia/Muscat`. | string | No | - | - |
| `to` | query | `op=convert`: target IANA zone, for example `America/New_York`. | string | No | - | - |
| `country` | query | `op=country`: ISO country code, for example `US`. | string | No | - | - |

Each operation needs its own fields: `zone` for `info`; `time`, `from` and `to` for `convert`; `country` for `country`. A missing field returns `400` with a message that names it.

**Example Request (op=info):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/time-zone/v1/market/timezone?op=info&zone=America%2FNew_York" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "op": "info",
  "zone": "America/New_York",
  "local_time": "2026-10-20T11:45:06-04:00",
  "utc_offset": "-04:00",
  "utc_offset_minutes": -240,
  "abbreviation": "EDT",
  "is_dst": true,
  "next_transition": {
    "at": "2026-11-01T06:00:00.000Z",
    "offset_before": "-04:00",
    "offset_after": "-05:00"
  },
  "countries": [
    "US"
  ],
  "meta": {
    "user": null
  }
}
```

`next_transition.at` is a UTC instant. Here New York leaves daylight saving time on 1 November 2026, moving from `-04:00` to `-05:00`. The `meta` object is metadata you can ignore.

**Example Request (op=convert):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/time-zone/v1/market/timezone?op=convert&time=2026-10-20T15:00&from=Asia%2FMuscat&to=America%2FNew_York" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "op": "convert",
  "from_zone": "Asia/Muscat",
  "to_zone": "America/New_York",
  "from_time": "2026-10-20T15:00:00+04:00",
  "to_time": "2026-10-20T07:00:00-04:00",
  "utc": "2026-10-20T11:00:00.000Z",
  "ambiguous": false,
  "meta": {
    "user": null
  }
}
```

`from_time` and `to_time` are the same instant shown in each zone, and `utc` is that instant in UTC. `ambiguous` is `true` when the local time occurs twice because clocks went back; the API then uses the first occurrence.

**Example Request (op=country):**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/time-zone/v1/market/timezone?op=country&country=US" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "op": "country",
  "country": "US",
  "zones": [
    {
      "zone": "America/New_York",
      "utc_offset": "-04:00",
      "local_time": "2026-10-20T11:45:10-04:00"
    },
    {
      "zone": "America/Chicago",
      "utc_offset": "-05:00",
      "local_time": "2026-10-20T10:45:10-05:00"
    },
    {
      "zone": "America/Denver",
      "utc_offset": "-06:00",
      "local_time": "2026-10-20T09:45:10-06:00"
    },
    {
      "zone": "America/Los_Angeles",
      "utc_offset": "-07:00",
      "local_time": "2026-10-20T08:45:10-07:00"
    }
  ],
  "meta": {
    "user": null
  }
}
```

The full response for `US` lists 29 zones.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded. |
| 400 | Bad Request | A field is invalid or missing, and the message names the field. This includes an unknown zone name, a badly formatted `time`, and a local time that falls inside a DST gap. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The request path is wrong. Check that it is `/v1/market/timezone` under the base URL. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

The Free trial, Starter and PAYG plans each allow 10 requests per second. The 7-day Free trial includes 500 calls, Starter includes 10,000 calls with extra calls at $0.001 each, and PAYG charges $0.001 per call with no subscription. Every call counts as one call whichever `op` you use. Requests above the per-second limit, or after the Free trial's calls are used up, return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header, which says how many seconds to wait. In our tests each operation answered in about 0.6 seconds.

## FAQ

**What zone names does the API accept?**

IANA zone names in `Area/City` form, such as `Asia/Muscat`, `Europe/London` or `America/Indiana/Indianapolis`. Send the full IANA name. The short `abbreviation` field, such as `EDT`, is returned for display.

**What happens if I convert a time that does not exist?**

When clocks jump forward, an hour of local time is skipped. A `time` inside that gap returns `400` instead of a guessed answer, so you can ask the user to pick a valid time.

**What does `ambiguous: true` mean in a conversion?**

When clocks go back, an hour of local time happens twice. The API flags that with `ambiguous: true` and converts using the first occurrence.

**Can I look up a time zone from latitude and longitude?**

No. The API works with IANA zone names and country codes only. Coordinate lookups are not supported.

**Which zone should I use for a country with several zones?**

`op=country` lists every zone of a country from the tz database `zone.tab` file, but it cannot tell which zone a particular person or address is in. Ask the user or use their city to pick the right zone.

**Is the next DST transition in local time or UTC?**

`next_transition.at` is a UTC instant (it ends in `Z`). Use `offset_before` and `offset_after` to show the local time on each side of the change.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Time zone API that returns UTC offset, DST status and the next DST change for any IANA zone, converts local times and lists a country's zones.

Time Zone API: UTC Offset, DST and Time Conversion

PAYG