openapi: 3.0.3
info:
  title: Numbers Batch Year 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: Year
  description: Historical facts associated with a year.
paths:
  /random/year:
    get:
      operationId: getRandomYearFact
      summary: Numbers API Get Random Year Fact
      description: Return a random year fact (a fact tied to a calendar year). The response includes the year as `number` and, when applicable, an associated `date` string.
      tags:
      - Year
      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 year fact.
          content:
            text/plain:
              schema:
                type: string
                example: 2012 is the year that the century's second and last solar transit of Venus occurs on June 6.
            application/json:
              schema:
                $ref: '#/components/schemas/Fact'
              examples:
                GetRandomYearFact200Example:
                  summary: Default getRandomYearFact 200 response
                  x-microcks-default: true
                  value:
                    text: 2012 is the year that the century's second and last solar transit of Venus occurs on June 6.
                    found: true
                    number: 2012
                    type: year
                    date: June 6
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{year}/year:
    get:
      operationId: getYearFact
      summary: Numbers API Get Year Fact
      description: Return a historical fact about a specific calendar year. Negative integers represent BC years. The keyword `random` may be used in place of `year` to get a random year fact, in which case the URL is `/random/year`.
      tags:
      - Year
      parameters:
      - name: year
        in: path
        required: true
        description: Year number; negative integers represent BC.
        schema:
          type: integer
        example: 1969
      - $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: Year fact.
          content:
            text/plain:
              schema:
                type: string
                example: 1969 is the year that an estimated 500 million people worldwide watch Neil Armstrong take his historic first steps on the Moon.
            application/json:
              schema:
                $ref: '#/components/schemas/Fact'
              examples:
                GetYearFact200Example:
                  summary: Default getYearFact 200 response
                  x-microcks-default: true
                  value:
                    text: 1969 is the year that an estimated 500 million people worldwide watch Neil Armstrong take his historic first steps on the Moon.
                    found: true
                    number: 1969
                    type: year
        '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