openapi: 3.0.3
info:
  title: TimezoneDB Conversion 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: Conversion
  description: Operations for converting time between timezones
paths:
  /convert-time-zone:
    get:
      operationId: convertTimeZone
      summary: Convert Time Zone
      description: 'Convert a Unix timestamp (or current time) from one timezone to another. Provide the source and destination timezones by name or abbreviation, and optionally specify a Unix timestamp to convert. Returns both source and destination timestamps along with timezone metadata.

        '
      tags:
      - Conversion
      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: from
        in: query
        required: true
        description: 'A valid timezone name or abbreviation to convert from. Example: "America/Los_Angeles" or "PDT".

          '
        schema:
          type: string
          example: America/Los_Angeles
      - name: to
        in: query
        required: true
        description: 'A valid timezone name or abbreviation to convert to. Example: "Australia/Sydney" or "AEST".

          '
        schema:
          type: string
          example: Australia/Sydney
      - name: time
        in: query
        required: false
        description: 'Unix timestamp of the origin timezone to convert. Defaults to current UTC time.

          '
        schema:
          type: integer
          format: int64
          example: 1464793200
      responses:
        '200':
          description: Successful response with converted timezone information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertTimeZoneResponse'
              examples:
                laToSydney:
                  $ref: '#/components/examples/ConvertTimeZoneLAToSydney'
        '400':
          description: Bad request — missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    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.
    ConvertTimeZoneResponse:
      type: object
      description: Response from the convert-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: ''
        fromZoneName:
          type: string
          description: IANA timezone name of the origin timezone.
          example: America/Los_Angeles
        fromAbbreviation:
          type: string
          description: Timezone abbreviation of the origin timezone.
          example: PDT
        fromTimestamp:
          type: integer
          format: int64
          description: Unix timestamp of the origin time.
          example: 1464793200
        toZoneName:
          type: string
          description: IANA timezone name of the destination timezone.
          example: Australia/Sydney
        toAbbreviation:
          type: string
          description: Timezone abbreviation of the destination timezone.
          example: AEST
        toTimestamp:
          type: integer
          format: int64
          description: Unix timestamp of the equivalent time in the destination timezone.
          example: 1464854400
        offset:
          type: integer
          description: Difference in seconds between origin and destination timezone.
          example: 61200
  examples:
    ConvertTimeZoneLAToSydney:
      summary: Convert from Los Angeles to Sydney
      value:
        status: OK
        message: ''
        fromZoneName: America/Los_Angeles
        fromAbbreviation: PDT
        fromTimestamp: 1464793200
        toZoneName: Australia/Sydney
        toAbbreviation: AEST
        toTimestamp: 1464854400
        offset: 61200
  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