swagger: '2.0'
info:
  version: 1.0.0
  title: Search Services
  description: |
    API for Internet Archive's Search-related services
schemes:
  - https
host: api.archive.org
basePath: /
produces:
  - application/json
  - application/javascript
paths:
  /search/v1/scrape:
    get:
      description: >
        Scrape search results from Internet Archive, allowing a scrolling cursor
      responses:
        '200':
          description: Scaping API
          schema:
            $ref: '#/definitions/ScrapeResult'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - $ref: '#/parameters/query'
        - $ref: '#/parameters/field'
        - $ref: '#/parameters/sort'
        - $ref: '#/parameters/size'
        - $ref: '#/parameters/cursor'
        - $ref: '#/parameters/total_only'
        - $ref: '#/parameters/callback'
  /search/v1/organic:
    get:
      description: >
        Return relevance-based results from search queries
      responses:
        '200':
          description: Organic Search API. Returns results in descending relevance order
          schema:
            $ref: '#/definitions/OrganicResult'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      parameters:
        - $ref: '#/parameters/query'
        - $ref: '#/parameters/field'
        - $ref: '#/parameters/size'
        - $ref: '#/parameters/total_only'
        - $ref: '#/parameters/callback'
  /search/v1/fields:
    get:
      description: Fields that can be requested
      parameters:
        - $ref: '#/parameters/callback'
      responses:
        '200':
          description: Fields that can be requested
          schema:
            type: array
            items:
              $ref: '#/definitions/Field'
parameters:
    query:
      name: q
      in: query
      description: Lucene-type search query
      type: string
    field:
      name: field
      in: query
      description: 'Metadata field'
      type: string
      default: identifier
      required: false
      minLength: 1
      maxLength: 250
      collectionFormat: multi
    sort:
      name: sort
      in: query
      description: 'sort collations'
      type: string
      required: false
      minLength: 5
      maxLength: 250
      collectionFormat: multi
    size:
      name: size
      in: query
      description: Number of query results to return
      type: integer
      minimum: 10
      maximum: 10000
      default: 1000
      required: false
    cursor:
      name: cursor
      in: query
      description: Cursor for scrolling (used for subsequent calls)
      type: string
      required: false
    total_only:
      name: total_only
      in: query
      description: Request total only; do not return hits
      type: boolean
      default: false
      required: false
    callback:
      name: callback
      description: Specifies a JavaScript function func, for a JSON-P response. When provided, results are wrapped as `callback(data)`, and the returned MIME type is application/javascript. This causes the caller to automatically run the func with the JSON results as its argument.
      in: query
      type: string
      required: false
definitions:
  Cursor:
    type: string
    description: A scroll handle
  Field:
    type: string
    description: The name of a field
  Hit:
    type: object
    description: One item returned (object of fields and values)
  ScrapeResult:
    type: object
    description: The result of a scrape request
    properties:
      cursor:
        $ref: '#/definitions/Cursor'
      previous:
        $ref: '#/definitions/Cursor'
      count:
        description: Number of results returned
        type: integer
        minimum: 0
        maximum: 10000
      total:
        description: Total number of results from this cursor point
        type: integer
        minimum: 0
      items:
        type: array
        items:
          $ref: '#/definitions/Hit'
  OrganicResult:
    type: object
    description: The result of a organic search request
    properties:
      count:
        description: Number of results returned
        type: integer
        minimum: 0
        maximum: 10000
      total:
        description: Approximate number of results meeting query
        type: integer
        minimum: 0
      items:
        type: array
        items:
          $ref: '#/definitions/Hit'
  Error:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string