openapi: 3.0.3
info:
  title: Numbers Batch 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: Batch
  description: Multiple facts returned in a single request as a JSON map.
paths:
  /{numberRange}/batch:
    get:
      operationId: getBatchFacts
      summary: Numbers API Get Batch Facts
      description: Return facts for multiple numbers in a single response. The `numberRange` path segment is a comma-separated list of integers and `min..max` ranges (e.g. `1..3,10`). Responses are always a JSON map from number to fact, of at most 100 numbers. Although the underlying URL pattern is `/{numberRange}` (or `/{numberRange}/{type}`), this operation models the batch case explicitly for tooling clarity.
      tags:
      - Batch
      parameters:
      - name: numberRange
        in: path
        required: true
        description: Comma-separated list of integers and inclusive `min..max` ranges.
        schema:
          type: string
        example: 1..3,10
      - name: type
        in: query
        required: false
        description: Fact type to apply to all numbers in the batch.
        schema:
          type: string
          enum:
          - trivia
          - math
          - year
        example: trivia
      - $ref: '#/components/parameters/Json'
      - $ref: '#/components/parameters/Fragment'
      - $ref: '#/components/parameters/Notfound'
      - $ref: '#/components/parameters/Default'
      responses:
        '200':
          description: JSON map keyed by number. When `json` is set, each value is a `Fact` object; otherwise each value is the plain-text fact string.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFacts'
              examples:
                GetBatchFacts200Example:
                  summary: Default getBatchFacts 200 response
                  x-microcks-default: true
                  value:
                    '1': 1 is the number of dimensions of a line.
                    '2': 2 is the number of polynucleotide strands in a DNA double helix.
                    '3': 3 is the number of sets needed to be won to win the whole match in volleyball.
                    '10': 10 is the highest score possible in Olympics gymnastics competitions.
      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'
    BatchFacts:
      type: object
      description: JSON map of number-keyed facts returned by a batch request. Each value is either a plain-text fact (default) or a `Fact` object (when `json` is set).
      additionalProperties:
        oneOf:
        - type: string
        - $ref: '#/components/schemas/Fact'
      example:
        '1': 1 is the number of dimensions of a line.
        '2': 2 is the number of polynucleotide strands in a DNA double helix.
        '3': 3 is the number of sets needed to be won to win the whole match in volleyball.
        '10': 10 is the highest score possible in Olympics gymnastics competitions.
  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.
    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
    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