openapi: 3.0.1
servers:
  - url: http://worldtimeapi.org/api/
info:
  description: A simple API to get the current time based on a request with a timezone.
  title: World Time API
  version: "20210108"
  x-apisguru-categories:
    - location
  x-origin:
    - format: openapi
      url: http://worldtimeapi.org/api
      version: "3.0"
  x-providerName: worldtimeapi.org
paths:
  /ip:
    get:
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
      summary: 'request the current time based on the ip of the request. note: this is a "best guess" obtained from open-source data.'
  /ip.txt:
    get:
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"
      summary: 'request the current time based on the ip of the request. note: this is a "best guess" obtained from open-source data.'
  "/ip/{ipv4}":
    get:
      parameters:
        - in: path
          name: ipv4
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
      summary: 'request the current time based on the ip of the request. note: this is a "best guess" obtained from open-source data.'
  "/ip/{ipv4}.txt":
    get:
      parameters:
        - in: path
          name: ipv4
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"
      summary: 'request the current time based on the ip of the request. note: this is a "best guess" obtained from open-source data.'
  /timezone:
    get:
      responses:
        default:
          $ref: "#/components/responses/SuccessfulListJsonResponse"
      summary: a listing of all timezones.
  /timezone.txt:
    get:
      responses:
        default:
          $ref: "#/components/responses/SuccessfulListTextResponse"
      summary: a listing of all timezones.
  "/timezone/{area}":
    get:
      parameters:
        - in: path
          name: area
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulListJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
      summary: a listing of all timezones available for that area.
  "/timezone/{area}.txt":
    get:
      parameters:
        - in: path
          name: area
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulListTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"
      summary: a listing of all timezones available for that area.
  "/timezone/{area}/{location}":
    get:
      parameters:
        - in: path
          name: area
          required: true
          schema:
            type: string
        - in: path
          name: location
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
      summary: request the current time for a timezone.
  "/timezone/{area}/{location}.txt":
    get:
      parameters:
        - in: path
          name: area
          required: true
          schema:
            type: string
        - in: path
          name: location
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"
      summary: request the current time for a timezone.
  "/timezone/{area}/{location}/{region}":
    get:
      parameters:
        - in: path
          name: area
          required: true
          schema:
            type: string
        - in: path
          name: location
          required: true
          schema:
            type: string
        - in: path
          name: region
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeJsonResponse"
        default:
          $ref: "#/components/responses/ErrorJsonResponse"
      summary: request the current time for a timezone.
  "/timezone/{area}/{location}/{region}.txt":
    get:
      parameters:
        - in: path
          name: area
          required: true
          schema:
            type: string
        - in: path
          name: location
          required: true
          schema:
            type: string
        - in: path
          name: region
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/SuccessfulDateTimeTextResponse"
        default:
          $ref: "#/components/responses/ErrorTextResponse"
      summary: request the current time for a timezone.
components:
  responses:
    ErrorJsonResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorJsonResponse"
      description: an error response in JSON format
    ErrorTextResponse:
      content:
        text/plain:
          schema:
            $ref: "#/components/schemas/ErrorTextResponse"
      description: an error response in plain text
    SuccessfulDateTimeJsonResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DateTimeJsonResponse"
      description: the current time for the timezone requested in JSON format
    SuccessfulDateTimeTextResponse:
      content:
        text/plain:
          schema:
            $ref: "#/components/schemas/DateTimeTextResponse"
      description: the current time for the timezone requested in plain text
    SuccessfulListJsonResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListJsonResponse"
      description: the list of available timezones in JSON format
    SuccessfulListTextResponse:
      content:
        text/plain:
          schema:
            $ref: "#/components/schemas/ListTextResponse"
      description: the list of available timezones in plain text
  schemas:
    DateTimeJsonResponse:
      properties:
        abbreviation:
          description: the abbreviated name of the timezone
          type: string
        client_ip:
          description: the IP of the client making the request
          type: string
        datetime:
          description: an ISO8601-valid string representing the current, local date/time
          type: string
        day_of_week:
          description: current day number of the week, where sunday is 0
          type: integer
        day_of_year:
          description: ordinal date of the current year
          type: integer
        dst:
          description: flag indicating whether the local time is in daylight savings
          type: boolean
        dst_from:
          description: an ISO8601-valid string representing the datetime when daylight savings started for this timezone
          type: string
        dst_offset:
          description: the difference in seconds between the current local time and daylight saving time for the location
          type: integer
        dst_until:
          description: an ISO8601-valid string representing the datetime when daylight savings will end for this timezone
          type: string
        raw_offset:
          description: the difference in seconds between the current local time and the time in UTC, excluding any daylight saving difference (see dst_offset)
          type: integer
        timezone:
          description: timezone in `Area/Location` or `Area/Location/Region` format
          type: string
        unixtime:
          description: number of seconds since the Epoch
          type: integer
        utc_datetime:
          description: an ISO8601-valid string representing the current date/time in UTC
          type: string
        utc_offset:
          description: an ISO8601-valid string representing the offset from UTC
          type: string
        week_number:
          description: the current week number
          type: integer
      required:
        - abbreviation
        - client_ip
        - datetime
        - day_of_week
        - day_of_year
        - dst
        - dst_offset
        - timezone
        - unixtime
        - utc_datetime
        - utc_offset
        - week_number
    DateTimeTextResponse:
      description: "time zone details, as per the DateTimeJsonResponse response, in the format `key: value`, one item per line"
      type: string
    ErrorJsonResponse:
      properties:
        error:
          description: details about the error encountered
          type: string
      required:
        - error
    ErrorTextResponse:
      description: details about the error encountered in plain text
      type: string
    ListJsonResponse:
      description: a list of available timezones
      items:
        type: string
      type: array
    ListTextResponse:
      description: a list of available timezones, one per line
      type: string
