openapi: 3.0.0
info:
  title: eBay Autocomplete API
  description: |
    The eBay Autocomplete API returns the suggestions eBay's search box shows while a query is being
    typed, in the order eBay shows them, on any of 16 eBay sites. Each answer holds up to 10 search
    suggestions and catalog products, the first suggestion usually with the categories eBay offers to
    search it in, and some also carry the extras eBay places in the box: a customer service search, a
    brand or store page, or eBay Stores.

    **Cross-linking**: A `query` or `product` row's `value` is a ready-made eBay search query. Pass it as the `q`
    parameter of the eBay Search API with the same `ebay_domain` to retrieve the matching listings, and a
    category's `category_id`, or a product's `category_id`, as its `category_id` parameter. A product's
    `link` opens eBay's search for the listings of that catalog product. For `store`, `shortcut` and
    `help` rows, open the row's `link`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: eBay Autocomplete
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["ebay_autocomplete"]
            default: "ebay_autocomplete"
        - name: q
          in: query
          required: true
          description: The partial or full search text to autocomplete. It needs at least one letter or number.
          schema:
            type: string
            maxLength: 200
        - name: ebay_domain
          in: query
          required: false
          description: eBay site whose search box the suggestions come from.
          schema:
            type: string
            default: "ebay.com"
            enum: ["ebay.com", "ebay.com.au", "ebay.at", "befr.ebay.be", "benl.ebay.be", "ebay.ca", "cafr.ebay.ca", "ebay.fr", "ebay.de", "ebay.ie", "ebay.it", "ebay.nl", "ebay.pl", "ebay.es", "ebay.ch", "ebay.co.uk"]
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Timeout, or eBay could not answer the request on any attempt. The body is a bare
            {"error": ...} rather than a search response, and the search is not billed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        suggestions:
          type: array
          description: >-
            The suggestions in the order eBay's search box shows them, empty when eBay has none for the
            query.
          items:
            $ref: '#/components/schemas/Suggestion'
        error:
          type: string
          description: Error message when eBay refuses the text in q and its search box shows no suggestions for it
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: The query eBay suggested for, as typed
    Suggestion:
      type: object
      required: [position, type, value, link]
      properties:
        position:
          type: integer
          description: 1-based position of the suggestion in eBay's search box
        type:
          type: string
          enum: ["query", "product", "help", "shortcut", "store"]
          description: >-
            The kind of row eBay shows: a search query, a catalog product, a customer service search, a
            shortcut to an eBay page such as a brand page or eBay Live, or an eBay Store
        value:
          type: string
          description: The suggested text, usable as the q parameter of the eBay Search API
        title:
          type: string
          description: Call to action or label eBay shows on a shortcut
        product_id:
          type: string
          description: eBay catalog product ID (ePID) of a product
        category_id:
          type: string
          description: eBay category of a product, usable as the category_id parameter of the eBay Search API
        store_id:
          type: string
          description: eBay ID of a store
        link:
          type: string
          description: eBay page the suggestion opens
        thumbnail:
          type: string
          description: Image of the product, page or store the suggestion opens
        categories:
          type: array
          description: The categories eBay's search box offers to search a query in
          items:
            $ref: '#/components/schemas/Category'
    Category:
      type: object
      required: [name, category_id, link]
      properties:
        name:
          type: string
          description: Category name as eBay shows it
        category_id:
          type: string
          description: eBay category ID, usable as the category_id parameter of the eBay Search API
        link:
          type: string
          description: eBay search page for the query inside the category
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: eBay search page for the query
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine identifier
        q:
          type: string
          description: Search text autocompleted
        ebay_domain:
          type: string
          description: eBay site the suggestions come from
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
