openapi: "3.0.1"
info:
  title: "World Time API"
  version: "20201203"
  description: >-
    A simple API to get the current time based on
    a request with a timezone.

servers:
  - url: http://worldtimeapi.org/api/

paths:
  /timezone:
    get:
      summary: a listing of all timezones.
      responses:
        default:
          $ref: "#/components/responses/SuccessfulListJsonResponse"
  /timezone.txt:
    get:
      summary: a listing of all timezones.
      responses:
        default:
          $ref: "#/components/responses/SuccessfulListTextResponse"

  /timezone/{area}:
    get:
      summary: a listing of all timezones available for that area.
      parameters:
        - name: area
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulListJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
  /timezone/{area}.txt:
    get:
      summary: a listing of all timezones available for that area.
      parameters:
        - name: area
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulListTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"

  /timezone/{area}/{location}:
    get:
      summary: request the current time for a timezone.
      parameters:
        - name: area
          in: path
          required: true
          schema:
            type: string
        - name: location
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
  /timezone/{area}/{location}.txt:
    get:
      summary: request the current time for a timezone.
      parameters:
        - name: area
          in: path
          required: true
          schema:
            type: string
        - name: location
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"

  /timezone/{area}/{location}/{region}:
    get:
      summary: request the current time for a timezone.
      parameters:
        - name: area
          in: path
          required: true
          schema:
            type: string
        - name: location
          in: path
          required: true
          schema:
            type: string
        - name: region
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
  /timezone/{area}/{location}/{region}.txt:
    get:
      summary: request the current time for a timezone.
      parameters:
        - name: area
          in: path
          required: true
          schema:
            type: string
        - name: location
          in: path
          required: true
          schema:
            type: string
        - name: region
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"

  /ip:
    get:
      summary: >-
        request the current time based on the ip of the request.
        note: this is a "best guess" obtained from open-source data.
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
  /ip.txt:
    get:
      summary: >-
        request the current time based on the ip of the request.
        note: this is a "best guess" obtained from open-source data.
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"

  /ip/{ipv4}:
    get:
      summary: >-
        request the current time based on the ip of the request.
        note: this is a "best guess" obtained from open-source data.
      parameters:
        - name: ipv4
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
  /ip/{ipv4}.txt:
    get:
      summary: >-
        request the current time based on the ip of the request.
        note: this is a "best guess" obtained from open-source data.
      parameters:
        - name: ipv4
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"

components:
  responses:
    SuccessfulListJsonResponse:
      description: >-
        the list of available timezones in JSON format
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListJsonResponse"
    SuccessfulListTextResponse:
      description: >-
        the list of available timezones in plain text
      content:
        text/plain:
          schema:
            $ref: "#/components/schemas/ListTextResponse"

    SuccessfulDateTimeJsonResponse:
      description: >-
        the current time for the timezone requested in JSON format
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DateTimeJsonResponse"
    SuccessfulDateTimeTextResponse:
      description: >-
        the current time for the timezone requested in plain text
      content:
        text/plain:
          schema:
            $ref: "#/components/schemas/DateTimeTextResponse"

    ErrorJsonResponse:
      description: >-
        an error response in JSON format
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorJsonResponse"
    ErrorTextResponse:
      description: >-
        an error response in plain text
      content:
        text/plain:
          schema:
            $ref: "#/components/schemas/ErrorTextResponse"

  schemas:
    ListJsonResponse:
      type: array
      description: >-
        a list of available timezones
      items:
        type: string

    ListTextResponse:
      type: string
      description: >-
        a list of available timezones, one per line

    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
          description: >-
            an ISO8601-valid string representing
            the datetime when daylight savings
            started for this timezone
        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
          description: >-
            an ISO8601-valid string representing
            the datetime when daylight savings
            will end for this timezone
        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

    DateTimeTextResponse:
      type: string
      description: >-
        time zone details, as per the DateTimeJsonResponse
        response, in the format `key: value`, one item per line

    ErrorJsonResponse:
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            details about the error encountered

    ErrorTextResponse:
      type: string
      description: >-
        details about the error encountered in plain text