Documentation navigation

Timezones API

IANA timezone data

Authentication: X-API-Key header on every request. Get a key.

List timezones

GET/v1/timezones

Quota cost: 1 unit Try it

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 Go Python TypeScript Ruby PHP

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

// 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()

# 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

// 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;

# 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

// 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

{
  "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

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

Get timezone by IANA ID

GET/v1/timezones/{tzId}