openapi: 3.0.0
info:
  title: Walmart Autocomplete API
  description: |
    The Walmart Autocomplete API returns the suggestions Walmart's search box shows while a query is being
    typed, in the order Walmart shows them. Each answer holds up to 10 query suggestions by default and up
    to 50 with num, most with a product thumbnail. Most answers also carry the Selections row Walmart shows
    above them, such as "Milk Selections": shortcuts into categories, filtered searches, brand pages and
    products.

    **Cross-linking**: Each query suggestion's `value` is a ready-made Walmart search query. Pass it as the
    `q` parameter of the Walmart Search API to retrieve the matching products. A Selections option's `value`,
    `category_id` and `filters` are the `q`, `category_id` and `filters` parameters of the Walmart Search API
    respectively. For a category option without a `value`, use its own `title` (for example, "Ground coffee")
    as `q`, together with its `category_id` and `filters`. Intent shortcuts such as "Get it today" may not
    translate into an equivalent search query; follow the option's original `link` to preserve that
    selection. An option's `product_id` is the `product_id` parameter of the Walmart Product API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Walmart Autocomplete
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["walmart_autocomplete"]
            default: "walmart_autocomplete"
        - name: q
          in: query
          required: true
          description: The partial or full search text to autocomplete.
          schema:
            type: string
            maxLength: 200
        - name: num
          in: query
          required: false
          description: >-
            Number of query suggestions to return. The Selections row, when Walmart shows one, comes in
            addition. Walmart returns all it has when it has fewer, usually between 40 and 50 for a common prefix.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      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 Walmart 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 Walmart's search box shows them, empty when Walmart has none for the
            query.
          items:
            $ref: '#/components/schemas/Suggestion'
        error:
          type: string
          description: Message naming the text in q that Walmart refused to suggest for
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: The query as Walmart read it, lowercased
    Suggestion:
      type: object
      required: [position, type, value]
      properties:
        position:
          type: integer
          description: 1-based position of the suggestion in Walmart's search box
        type:
          type: string
          enum: ["query", "refinement"]
          description: The kind of row Walmart shows, a search suggestion or the Selections row of shortcuts
        value:
          type: string
          description: The suggested search text, or the text Walmart names the Selections row after
        title:
          type: string
          description: Heading of the Selections row as Walmart shows it
        link:
          type: string
          description: Walmart search page the suggestion opens
        thumbnail:
          type: string
          description: Product image Walmart shows beside the suggestion
        options:
          type: array
          description: The shortcuts of the Selections row in the order Walmart shows them
          items:
            $ref: '#/components/schemas/RefinementOption'
    RefinementOption:
      type: object
      required: [title, link]
      properties:
        title:
          type: string
          description: Label of the shortcut
        value:
          type: string
          description: Search text the shortcut opens, usable as the q parameter of the Walmart Search API
        category_id:
          type: string
          description: Category the shortcut opens, usable as the category_id parameter of the Walmart Search API
        filters:
          type: string
          description: Filters the shortcut applies, usable as the filters parameter of the Walmart Search API
        product_id:
          type: string
          description: Product the shortcut opens, usable as the product_id parameter of the Walmart Product API
        link:
          type: string
          description: Walmart page the shortcut opens
        thumbnail:
          type: string
          description: Image Walmart shows for the shortcut
    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: Walmart 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
        num:
          type: integer
          description: Number of search suggestions requested
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
