openapi: 3.0.3
info:
  title: Numbers Batch Date API
  version: 1.0.0
  description: Numbers API by David Hu and Mack Duan — a free, community-contributed HTTP API for interesting facts about numbers. Returns trivia, math, date, and year facts as plain text or JSON. Supports random numbers, batches/ranges, JSONP callbacks, document.write embedding, sentence-fragment responses, and configurable not-found behavior.
  contact:
    name: Numbers API
    email: numbersapi@gmail.com
    url: http://numbersapi.com/
  license:
    name: Free for any use (community API)
    url: http://numbersapi.com/
servers:
- url: http://numbersapi.com
  description: Numbers API production endpoint.
tags:
- name: Date
  description: Historical facts associated with a day of the year.
paths:
  /random/date:
    get:
      operationId: getRandomDateFact
      summary: Numbers API Get Random Date Fact
      description: Return a random date fact (a fact tied to a day of year, returned with the corresponding `month/day`).
      tags:
      - Date
      parameters:
      - $ref: '#/components/parameters/Json'
      - $ref: '#/components/parameters/Fragment'
      - $ref: '#/components/parameters/Notfound'
      - $ref: '#/components/parameters/Default'
      - $ref: '#/components/parameters/Callback'
      - $ref: '#/components/parameters/Write'
      responses:
        '200':
          description: Random date fact.
          content:
            text/plain:
              schema:
                type: string
                example: April 1 is the day in 1976 that Apple Computer Company is founded by Steve Jobs, Steve Wozniak, and Ronald Wayne.
            application/json:
              schema:
                $ref: '#/components/schemas/Fact'
              examples:
                GetRandomDateFact200Example:
                  summary: Default getRandomDateFact 200 response
                  x-microcks-default: true
                  value:
                    text: April 1 is the day in 1976 that Apple Computer Company is founded by Steve Jobs, Steve Wozniak, and Ronald Wayne.
                    found: true
                    number: 92
                    type: date
                    year: '1976'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{month}/{day}/date:
    get:
      operationId: getDateFact
      summary: Numbers API Get Date Fact
      description: Return a historical fact about a specific day of the year, supplied as a `month/day` path (e.g. `2/29`, `04/1`). The keyword `random` may be used in place of `month/day` to get a random date fact, in which case the URL is `/random/date`.
      tags:
      - Date
      parameters:
      - name: month
        in: path
        required: true
        description: Month number, 1-12 (zero padding is accepted, e.g. `04`).
        schema:
          type: integer
          minimum: 1
          maximum: 12
        example: 2
      - name: day
        in: path
        required: true
        description: Day-of-month number, 1-31 (zero padding is accepted, e.g. `09`).
        schema:
          type: integer
          minimum: 1
          maximum: 31
        example: 29
      - $ref: '#/components/parameters/Json'
      - $ref: '#/components/parameters/Fragment'
      - $ref: '#/components/parameters/Notfound'
      - $ref: '#/components/parameters/Default'
      - $ref: '#/components/parameters/Callback'
      - $ref: '#/components/parameters/Write'
      responses:
        '200':
          description: Date fact for the supplied month/day.
          content:
            text/plain:
              schema:
                type: string
                example: February 29 is the day in 1504 that Christopher Columbus uses his knowledge of a lunar eclipse to convince Native Americans to provide him with supplies.
            application/json:
              schema:
                $ref: '#/components/schemas/Fact'
              examples:
                GetDateFact200Example:
                  summary: Default getDateFact 200 response
                  x-microcks-default: true
                  value:
                    text: February 29 is the day in 1504 that Christopher Columbus uses his knowledge of a lunar eclipse to convince Native Americans to provide him with supplies.
                    found: true
                    number: 60
                    type: date
                    year: '1504'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Fact:
      type: object
      description: A single Numbers API fact returned in JSON form.
      required:
      - text
      - number
      - found
      - type
      properties:
        text:
          type: string
          description: Plain-text fact about the number.
          example: 42 is the result given by Google and Bing for the query "the answer to life the universe and everything".
        number:
          type: number
          description: Floating-point number the fact pertains to. For date facts, this is the 1-indexed day of a leap year (e.g. 61 is March 1).
          example: 42
        found:
          type: boolean
          description: Whether a real fact was found for the requested number.
          example: true
        type:
          type: string
          description: Category of the returned fact.
          enum:
          - trivia
          - math
          - date
          - year
          example: trivia
        date:
          type: string
          description: Day of year associated with year facts, as a string (e.g. `June 6`).
          example: June 6
        year:
          type: string
          description: Year associated with date facts, as a string (e.g. `1969`).
          example: '1969'
  parameters:
    Default:
      name: default
      in: query
      required: false
      description: Custom message to return when no fact exists for the requested number.
      schema:
        type: string
      example: Boring number is boring.
    Write:
      name: write
      in: query
      required: false
      description: Wrap the response in `document.write("<fact>")` so a single `<script src="...">` tag can render the fact inline. Equivalent to `callback=document.write`.
      schema:
        type: boolean
      example: true
    Notfound:
      name: notfound
      in: query
      required: false
      description: Behavior when no fact exists for the requested number. `default` returns a generic message (overridable with `default`), `floor` rounds down to the nearest number with a fact, and `ceil` rounds up.
      schema:
        type: string
        enum:
        - default
        - floor
        - ceil
        default: default
      example: floor
    Callback:
      name: callback
      in: query
      required: false
      description: JSONP callback function name. The response is wrapped as `<callback>("<fact>")`.
      schema:
        type: string
      example: showNumber
    Fragment:
      name: fragment
      in: query
      required: false
      description: Return the fact as a sentence fragment (lowercase, no terminal punctuation) suitable for embedding in a larger sentence.
      schema:
        type: boolean
      example: true
    Json:
      name: json
      in: query
      required: false
      description: 'Return the fact as a JSON object (`{ text, found, number, type, date?, year? }`) instead of plain text. Equivalent to setting the request `Content-Type: application/json` header.'
      schema:
        type: boolean
      example: true
  responses:
    NotFound:
      description: No fact was found for the requested number. The body still contains a plain-text or JSON message; the HTTP status reflects the lookup outcome only when `notfound` is left at its default.
      content:
        text/plain:
          schema:
            type: string
            example: 314159265358979 is a boring number.
        application/json:
          schema:
            $ref: '#/components/schemas/Fact'
          examples:
            NotFoundExample:
              summary: Default 404 response
              x-microcks-default: true
              value:
                text: 314159265358979 is a boring number.
                found: false
                number: 314159265358979
                type: trivia