# Timezones API — GeoSearch

> The GeoSearch Timezones API: 2 endpoints with parameters, quota costs, response bodies and code samples in six languages.

Base URL: https://geosearch.dev · Auth: X-API-Key header on every request.
HTML version: https://geosearch.dev/docs/api/timezones

IANA timezone data

## List timezones

`GET /v1/timezones` · Quota cost: 1 unit

Returns a paginated list of timezones with optional filtering by country.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| country | string | optional | Filter by ISO alpha-2 country code |
| cursor | string | optional | Pagination cursor from a previous response |
| limit | integer | optional | Number of results per page (1-100, default 25) |
| fields | string | optional | Comma-separated list of fields to include in the response |
| sort | string | optional | Sort field. Allowed: timezone_id, gmt_offset, country_code. |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/timezones?country=US"
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
timezones, _, err := client.TimezonesAPI.ListTimezones(ctx).Country("US").Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    timezones = geosearch.TimezonesApi(client).list_timezones(country="US").data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, TimezonesApi } from "@geosearch/client";

const api = new TimezonesApi(new Configuration({ apiKey: "YOUR_KEY" }));
const timezones = (await api.listTimezones({ country: "US" })).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
timezones = GeoSearch::TimezonesApi.new.list_timezones(country: "US").data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$timezones = (new GeoSearch\Api\TimezonesApi(null, $cfg))->listTimezones(null, "US");
// lang, country shown — the remaining 4 parameters are positional and optional
```

### Response

```json
{
  "data": [
    {
      "id": 424,
      "country_code": "US",
      "timezone_id": "America/New_York",
      "gmt_offset": -5,
      "dst_offset": -4,
      "raw_offset": -5
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "prev_cursor": "eyJpZCI6MX0",
    "has_next": true,
    "has_prev": false,
    "count": 25
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |

## Get timezone by IANA ID

`GET /v1/timezones/{tzId}` · Quota cost: 1 unit

Returns a single timezone by its IANA identifier.
Note: IANA timezone IDs contain slashes (e.g., America/New_York),
so the path uses a wildcard match.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| tzId | string | required | IANA timezone ID (e.g., America/New_York) |
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| fields | string | optional | Comma-separated list of fields to include in the response |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" https://geosearch.dev/v1/timezones/America/New_York
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
tz, _, err := client.TimezonesAPI.GetTimezone(ctx, "America/New_York").Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    tz = geosearch.TimezonesApi(client).get_timezone("America/New_York").data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, TimezonesApi } from "@geosearch/client";

const api = new TimezonesApi(new Configuration({ apiKey: "YOUR_KEY" }));
const tz = (await api.getTimezone({ tzId: "America/New_York" })).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
tz = GeoSearch::TimezonesApi.new.get_timezone("America/New_York").data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$tz = (new GeoSearch\Api\TimezonesApi(null, $cfg))->getTimezone("America/New_York")->getData();
```

### Response

```json
{
  "data": {
    "id": 424,
    "country_code": "US",
    "timezone_id": "America/New_York",
    "gmt_offset": -5,
    "dst_offset": -4,
    "raw_offset": -5
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 400 | validation_error | Invalid request parameters |
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 404 | not_found | Resource not found |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |