TimezoneDB

TimezoneDB Timezones API

Operations for listing and retrieving timezone information

Documentation GitHub OpenAPI

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/timezonedb-timezones-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.0.3
info:
  title: TimezoneDB Conversion Timezones API
  description: 'TimezoneDB is a REST API providing timezone information for cities and coordinates worldwide. It supports looking up local time, GMT offset, and daylight saving time (DST) status by timezone name, geographic coordinates (latitude/longitude), city name, or IP address. The service also supports converting times between timezones and listing all 400+ supported timezones across 240+ countries. Responses are available in JSON or XML formats.

    '
  version: '2.1'
  contact:
    name: TimezoneDB Support
    url: https://timezonedb.com/contact
  termsOfService: https://timezonedb.com/terms-and-conditions
  license:
    name: Commercial
    url: https://timezonedb.com/premium
servers:
- url: https://api.timezonedb.com/v2.1
  description: TimezoneDB API v2.1
security:
- apiKey: []
tags:
- name: Timezones
  description: Operations for listing and retrieving timezone information
paths:
  /list-time-zone:
    get:
      operationId: listTimeZone
      summary: List Time Zones
      description: 'List out all available time zones supported by TimezoneDB. Optionally filter by country code or timezone name pattern. Supports field selection to customize the response payload.

        '
      tags:
      - Timezones
      parameters:
      - name: key
        in: query
        required: true
        description: Your unique API key obtained after registering an account.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: Response format. Defaults to xml.
        schema:
          type: string
          enum:
          - xml
          - json
          default: xml
      - name: callback
        in: query
        required: false
        description: JavaScript JSONP callback function name.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: 'Comma-separated list of field names to include in the response. Available fields: countryCode, countryName, zoneName, gmtOffset, dst, timestamp. Defaults to: countryCode, countryName, zoneName, gmtOffset, timestamp.

          '
        schema:
          type: string
          example: countryCode,countryName,zoneName,gmtOffset,timestamp
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-2 country code to filter results by nation.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          example: US
      - name: zone
        in: query
        required: false
        description: 'Timezone name to filter results. Supports asterisk (*) wildcard. Example: "America/*" returns all American timezones.

          '
        schema:
          type: string
          example: America/*
      responses:
        '200':
          description: Successful response with list of timezones.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTimeZoneResponse'
              examples:
                allZones:
                  $ref: '#/components/examples/ListTimeZoneAllZones'
                filteredByCountry:
                  $ref: '#/components/examples/ListTimeZoneFilteredByCountry'
        '400':
          description: Bad request — missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /get-time-zone:
    get:
      operationId: getTimeZone
      summary: Get Time Zone
      description: 'Retrieve local time, GMT offset, and DST information for a location. Lookup can be performed by timezone name or abbreviation, geographic coordinates (lat/lng), city name (with country), or IP address.

        '
      tags:
      - Timezones
      parameters:
      - name: key
        in: query
        required: true
        description: Your unique API key obtained after registering an account.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: Response format. Defaults to xml.
        schema:
          type: string
          enum:
          - xml
          - json
          default: xml
      - name: callback
        in: query
        required: false
        description: JavaScript JSONP callback function name.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of field names to include in the response.
        schema:
          type: string
      - name: by
        in: query
        required: true
        description: 'The lookup method to use. One of: - zone: Look up by timezone name or abbreviation - position: Look up by latitude/longitude coordinates - city: Look up by city name and country code - ip: Look up by IP address

          '
        schema:
          type: string
          enum:
          - zone
          - position
          - city
          - ip
      - name: zone
        in: query
        required: false
        description: 'Time zone name or abbreviation. Required when by=zone. Example: "America/Chicago" or "CDT".

          '
        schema:
          type: string
          example: America/Chicago
      - name: lat
        in: query
        required: false
        description: 'Latitude coordinate in decimal degrees. Required when by=position. Range: -90 to 90.

          '
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
          example: 40.7128
      - name: lng
        in: query
        required: false
        description: 'Longitude coordinate in decimal degrees. Required when by=position. Range: -180 to 180.

          '
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
          example: -74.006
      - name: country
        in: query
        required: false
        description: 'ISO 3166-1 alpha-2 country code. Required when by=city.

          '
        schema:
          type: string
          minLength: 2
          maxLength: 2
          example: US
      - name: region
        in: query
        required: false
        description: 'US region/state code for additional filtering when by=city.

          '
        schema:
          type: string
          example: NY
      - name: city
        in: query
        required: false
        description: 'City name. Required when by=city. Supports wildcard (*) pattern matching.

          '
        schema:
          type: string
          example: New York
      - name: page
        in: query
        required: false
        description: Page number for paginated results when multiple cities match.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: time
        in: query
        required: false
        description: 'Unix timestamp in UTC to retrieve timezone information for a specific point in time. Defaults to current UTC time.

          '
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful response with timezone information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTimeZoneResponse'
              examples:
                byZone:
                  $ref: '#/components/examples/GetTimeZoneByZone'
        '400':
          description: Bad request — missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  examples:
    ListTimeZoneFilteredByCountry:
      summary: List timezones filtered by country (New Zealand)
      value:
        status: OK
        message: ''
        zones:
        - countryCode: NZ
          countryName: New Zealand
          zoneName: Pacific/Auckland
          gmtOffset: 43200
          timestamp: 1464537416
    GetTimeZoneByZone:
      summary: Get timezone info by zone name
      value:
        status: OK
        message: ''
        countryCode: US
        countryName: United States
        zoneName: America/Chicago
        abbreviation: CDT
        gmtOffset: -18000
        dst: '1'
        timestamp: 1781365987
        formatted: '2026-06-13 15:53:07'
    ListTimeZoneAllZones:
      summary: List all timezones
      value:
        status: OK
        message: ''
        zones:
        - countryCode: AD
          countryName: Andorra
          zoneName: Europe/Andorra
          gmtOffset: 7200
          timestamp: 1464453737
  schemas:
    TimeZoneEntry:
      type: object
      description: A single timezone entry with location and offset information.
      properties:
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code of the timezone.
          example: AD
        countryName:
          type: string
          description: Full country name of the timezone.
          example: Andorra
        zoneName:
          type: string
          description: IANA timezone name identifier.
          example: Europe/Andorra
        gmtOffset:
          type: integer
          description: The UTC offset in seconds.
          example: 7200
        dst:
          type: integer
          description: Daylight Saving Time flag. 0 = No DST, 1 = DST active.
          enum:
          - 0
          - 1
          example: 1
        timestamp:
          type: integer
          format: int64
          description: Current local time as a Unix timestamp.
          example: 1464453737
    ListTimeZoneResponse:
      type: object
      description: Response from the list-time-zone endpoint.
      properties:
        status:
          type: string
          description: Query result status.
          enum:
          - OK
          - FAILED
          example: OK
        message:
          type: string
          description: Error message; empty string if successful.
          example: ''
        zones:
          type: array
          description: Array of timezone entries.
          items:
            $ref: '#/components/schemas/TimeZoneEntry'
    ErrorResponse:
      type: object
      description: Error response returned when a query fails.
      properties:
        status:
          type: string
          description: Always "FAILED" for error responses.
          enum:
          - FAILED
          example: FAILED
        message:
          type: string
          description: Human-readable error message describing the failure.
          example: Invalid API key.
    GetTimeZoneResponse:
      type: object
      description: Response from the get-time-zone endpoint.
      properties:
        status:
          type: string
          description: Query result status.
          enum:
          - OK
          - FAILED
          example: OK
        message:
          type: string
          description: Error message; empty string if successful.
          example: ''
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code of the timezone.
          example: US
        countryName:
          type: string
          description: Full country name.
          example: United States
        regionName:
          type: string
          description: Region or state name (premium feature).
          example: Illinois
        cityName:
          type: string
          description: City or place name (premium feature).
          example: Chicago
        zoneName:
          type: string
          description: IANA timezone name identifier.
          example: America/Chicago
        abbreviation:
          type: string
          description: Timezone abbreviation.
          example: CDT
        gmtOffset:
          type: integer
          description: UTC offset in seconds.
          example: -18000
        dst:
          type: string
          description: Daylight Saving Time flag. "0" = No DST, "1" = DST active.
          enum:
          - '0'
          - '1'
          example: '1'
        zoneStart:
          type: integer
          format: int64
          description: Unix timestamp when the current timezone period started.
          example: 1710054000
        zoneEnd:
          type: integer
          format: int64
          description: Unix timestamp when the current timezone period ends.
          example: 1730613600
        nextAbbreviation:
          type: string
          description: Timezone abbreviation for the next period.
          example: CST
        timestamp:
          type: integer
          format: int64
          description: Current local time as a Unix timestamp.
          example: 1781365987
        formatted:
          type: string
          description: Human-readable local time in Y-m-d H:i:s format.
          example: '2026-06-13 15:53:07'
        totalPage:
          type: integer
          description: Total number of pages for paginated results.
          example: 1
        currentPage:
          type: integer
          description: Current page number in paginated results.
          example: 1
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: API key obtained from https://timezonedb.com/register
externalDocs:
  description: TimezoneDB API Documentation
  url: https://timezonedb.com/api

TimezoneDB Timezones API

Documentation

Specifications

Schemas & Data

Other Resources