openapi: 3.0.1
info:
  title: World Time Geo Timezone API
  version: '2025-10-01'
  description: API to get the current local time details for a given timezone or IP address
servers:
- url: https://public.timeapi.world/api/
tags:
- name: Timezone
paths:
  /timezone:
    get:
      summary: a listing of all timezones.
      responses:
        default:
          $ref: '#/components/responses/SuccessfulListJsonResponse'
      tags:
      - Timezone
  /timezone/{area}:
    get:
      summary: a listing of all timezones available for that area.
      parameters:
      - name: area
        in: path
        required: true
        schema:
          type: string
        example: Africa
      responses:
        '200':
          description: the list of available timezones in JSON format for the specified area
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJsonResponse'
              example:
              - Africa/Abidjan
              - Africa/Accra
              - Africa/Addis_Ababa
              - Africa/Algiers
              - Africa/Asmara
        default:
          $ref: '#/components/responses/ErrorJsonResponse'
      tags:
      - Timezone
  /timezone/{area}.txt:
    get:
      summary: a listing of all timezones available for that area.
      parameters:
      - name: area
        in: path
        required: true
        schema:
          type: string
        example: Africa
      responses:
        '200':
          description: the list of available timezones in plain text for the specified area
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ListTextResponse'
              example: 'Africa/Abidjan

                Africa/Accra

                Africa/Addis_Ababa

                Africa/Algiers

                Africa/Asmara

                '
        default:
          $ref: '#/components/responses/ErrorTextResponse'
      tags:
      - Timezone
  /timezone/{area}/{location}:
    get:
      summary: request the current time for a timezone.
      parameters:
      - name: area
        in: path
        required: true
        schema:
          type: string
        example: Africa
      - name: location
        in: path
        required: true
        schema:
          type: string
        example: Abidjan
      responses:
        '200':
          description: the current time for the timezone requested in JSON format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DateTimeJsonResponse'
              example:
                abbreviation: GMT
                datetime: '2025-09-12T12:18:29.438+00:00'
                day_of_week: 5
                day_of_year: 255
                dst: false
                dst_from: null
                dst_offset: 0
                dst_until: null
                raw_offset: 0
                timezone: Africa/Abidjan
                unixtime: 1757679509
                utc_datetime: '2025-09-12T12:18:29.438+00:00'
                utc_offset: +00:00
                week_number: 37
                client_ip: 127.0.0.1
        default:
          $ref: '#/components/responses/ErrorJsonResponse'
      tags:
      - Timezone
  /timezone/{area}/{location}.txt:
    get:
      summary: request the current time for a timezone.
      parameters:
      - name: area
        in: path
        required: true
        schema:
          type: string
        example: Africa
      - name: location
        in: path
        required: true
        schema:
          type: string
        example: Abidjan
      responses:
        '200':
          description: the current time for the timezone requested in plain text
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DateTimeTextResponse'
              example: 'abbreviation: GMT

                datetime: 2025-09-12T12:18:29.438+00:00

                day_of_week: 5

                day_of_year: 255

                dst: false

                dst_from:

                dst_offset: 0

                dst_until:

                raw_offset: 0

                timezone: Africa/Abidjan

                unixtime: 1757679509

                utc_datetime: 2025-09-12T12:18:29.438+00:00

                utc_offset: +00:00

                week_number: 37

                client_ip: 127.0.0.1

                '
        default:
          $ref: '#/components/responses/ErrorTextResponse'
      tags:
      - Timezone
  /timezone/{area}/{location}/{region}:
    get:
      summary: request the current time for a timezone.
      parameters:
      - name: area
        in: path
        required: true
        schema:
          type: string
        example: America
      - name: location
        in: path
        required: true
        schema:
          type: string
        example: Argentina
      - name: region
        in: path
        required: true
        schema:
          type: string
        example: Buenos_Aires
      responses:
        '200':
          description: the current time for the timezone requested in JSON format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DateTimeJsonResponse'
              example:
                abbreviation: '-03'
                datetime: '2025-09-12T09:30:07.347-03:00'
                day_of_week: 5
                day_of_year: 255
                dst: false
                dst_from: null
                dst_offset: 0
                dst_until: null
                raw_offset: -10800
                timezone: America/Argentina/Buenos_Aires
                unixtime: 1757680207
                utc_datetime: '2025-09-12T12:30:07.347+00:00'
                utc_offset: -03:00
                week_number: 37
                client_ip: 127.0.0.1
        default:
          $ref: '#/components/responses/ErrorJsonResponse'
      tags:
      - Timezone
  /timezone/{area}/{location}/{region}.txt:
    get:
      summary: request the current time for a timezone.
      parameters:
      - name: area
        in: path
        required: true
        schema:
          type: string
        example: America
      - name: location
        in: path
        required: true
        schema:
          type: string
        example: Argentina
      - name: region
        in: path
        required: true
        schema:
          type: string
        example: Buenos_Aires
      responses:
        '200':
          description: the current time for the timezone requested in plain text
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/DateTimeTextResponse'
              example: 'abbreviation: -03

                datetime: 2025-09-12T09:30:07.347-03:00

                day_of_week: 5

                day_of_year: 255

                dst: false

                dst_from:

                dst_offset: 0

                dst_until:

                raw_offset: -10800

                timezone: America/Argentina/Buenos_Aires

                unixtime: 1757680207

                utc_datetime: 2025-09-12T12:30:07.347+00:00

                utc_offset: -03:00

                week_number: 37

                client_ip: 127.0.0.1

                '
        default:
          $ref: '#/components/responses/ErrorTextResponse'
      tags:
      - Timezone
components:
  schemas:
    ListTextResponse:
      type: string
      description: a list of available timezones, one per line
    ErrorTextResponse:
      type: string
      description: details about the error encountered in plain text
    DateTimeJsonResponse:
      required:
      - abbreviation
      - client_ip
      - datetime
      - day_of_week
      - day_of_year
      - dst
      - dst_offset
      - timezone
      - unixtime
      - utc_datetime
      - utc_offset
      - week_number
      properties:
        abbreviation:
          type: string
          description: the abbreviated name of the timezone
        client_ip:
          type: string
          description: the IP of the client making the request
        datetime:
          type: string
          description: an ISO8601-valid string representing the current, local date/time
        day_of_week:
          type: integer
          description: current day number of the week, where sunday is 0
        day_of_year:
          type: integer
          description: ordinal date of the current year
        dst:
          type: boolean
          description: flag indicating whether the local time is in daylight savings
        dst_from:
          type: string
          nullable: true
          description: 'an ISO8601-valid string representing the datetime of a DST transition. When DST is active (dst=true): shows when the current DST period started. When DST is NOT active (dst=false): shows when the next DST period will begin (future date). Returns null if the timezone does not observe DST.'
        dst_offset:
          type: integer
          description: the difference in seconds between the current local time and daylight saving time for the location
        dst_until:
          type: string
          nullable: true
          description: 'an ISO8601-valid string representing the datetime of a DST transition. When DST is active (dst=true): shows when the current DST period will end (future date). When DST is NOT active (dst=false): shows when the last DST period ended (past date). Returns null if the timezone does not observe DST.'
        raw_offset:
          type: integer
          description: the difference in seconds between the current local time and the time in UTC, excluding any daylight saving difference (see dst_offset)
        timezone:
          type: string
          description: timezone in `Area/Location` or `Area/Location/Region` format
        unixtime:
          type: integer
          description: number of seconds since the Epoch
        utc_datetime:
          type: string
          description: an ISO8601-valid string representing the current date/time in UTC
        utc_offset:
          type: string
          description: an ISO8601-valid string representing the offset from UTC
        week_number:
          type: integer
          description: the current week number
    ErrorJsonResponse:
      required:
      - error
      properties:
        error:
          type: string
          description: details about the error encountered
    ListJsonResponse:
      type: array
      description: a list of available timezones
      items:
        type: string
    DateTimeTextResponse:
      type: string
      description: 'time zone details, as per the DateTimeJsonResponse response, in the format `key: value`, one item per line'
  responses:
    ErrorTextResponse:
      description: an error response in plain text
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorTextResponse'
    SuccessfulListJsonResponse:
      description: the list of available timezones in JSON format
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListJsonResponse'
          example:
          - Africa/Abidjan
          - Africa/Accra
          - Africa/Addis_Ababa
          - Africa/Algiers
          - Africa/Asmara
          - Africa/Asmera
          - Africa/Bamako
    ErrorJsonResponse:
      description: an error response in JSON format
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorJsonResponse'