> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /timezone

> Get timezone details by IANA timezone ID or geographic coordinates.

## Endpoint

```
POST https://api.bunny.build/api/v1/timezone
```

Also available:

```
GET https://api.bunny.build/api/v1/timezone/list
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Retrieve current timezone details by providing an IANA timezone identifier or a pair of geographic coordinates. The response includes the UTC offset, DST status, and the current local time at that location. Use `GET /timezone/list` to retrieve all supported IANA timezone IDs.

## Use cases

* Display localized timestamps in scheduling and calendar applications
* Normalize log timestamps from distributed systems to a single reference zone
* Determine the local time at a destination for travel applications
* Localize time-sensitive UI elements such as countdowns and business hours

## Request body

Provide either `timezone` (IANA ID) or both `lat` and `lon` (coordinates).

| Field      | Type   | Required | Description                                           |
| ---------- | ------ | -------- | ----------------------------------------------------- |
| `timezone` | string | No       | IANA timezone identifier (e.g. `"America/Sao_Paulo"`) |
| `lat`      | number | No       | Latitude for coordinate-based lookup                  |
| `lon`      | number | No       | Longitude for coordinate-based lookup                 |

### Example — by IANA ID

```json theme={null}
{
  "timezone": "America/Sao_Paulo"
}
```

### Example — by coordinates

```json theme={null}
{
  "lat": -23.55,
  "lon": -46.63
}
```

## Response

### 200 OK

| Field                | Type    | Description                                                  |
| -------------------- | ------- | ------------------------------------------------------------ |
| `timezone`           | string  | IANA timezone identifier                                     |
| `abbreviation`       | string  | Timezone abbreviation (e.g. `"BRT"`)                         |
| `utc_offset`         | string  | UTC offset string (e.g. `"-03:00"`)                          |
| `utc_offset_minutes` | integer | UTC offset in minutes                                        |
| `current_local_time` | string  | Current local time in ISO 8601 format                        |
| `observes_dst`       | boolean | Whether the timezone currently observes daylight saving time |

**Example**

```json theme={null}
{
  "timezone": "America/Sao_Paulo",
  "abbreviation": "BRT",
  "utc_offset": "-03:00",
  "utc_offset_minutes": -180,
  "current_local_time": "2025-06-21T10:30:00-03:00",
  "observes_dst": false
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Provide either 'timezone' or both 'lat' and 'lon'."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/timezone \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/Sao_Paulo"}'
```