openapi: 3.0.0
info:
  title: Walmart Reviews API
  description: |
    The Walmart Reviews API returns customer reviews for a Walmart product, along with the rating histogram, aspect statistics, AI review summary, and pagination.

    **Cross-linking**: The `product_id` parameter accepts a Walmart product ID — the same identifier used by the Walmart Product API (the numeric part after `/ip/` in a Walmart product URL). The `aspect_id` parameter accepts an aspect ID returned in the `aspect_stats` array of a previous response from this API, letting you drill into reviews for a specific aspect.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Walmart Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["walmart_reviews"]
            default: "walmart_reviews"
        - name: product_id
          in: query
          required: true
          description: Walmart product ID to retrieve reviews for
          schema:
            type: string
        - name: rating
          in: query
          required: false
          description: Filter reviews by star rating
          schema:
            type: string
            enum: ["1", "2", "3", "4", "5"]
        - name: verified_purchases_only
          in: query
          required: false
          description: Return only reviews from verified purchases
          schema:
            type: boolean
        - name: sort_by
          in: query
          required: false
          description: Sort order for the returned reviews
          schema:
            type: string
            enum: ["relevance", "newest", "helpful", "highest_rating", "lowest_rating"]
        - name: page
          in: query
          required: false
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
        - name: aspect_id
          in: query
          required: false
          description: Filter reviews by a specific aspect. Use an aspect ID returned in the aspect_stats array of a previous response.
          schema:
            type: integer
      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. We could not retrieve results in 90 seconds.
          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'
        product:
          $ref: '#/components/schemas/Product'
        aspect_stats:
          type: array
          description: Aspects extracted from the reviews, each with a snippet count. Use an aspect id as the aspect_id parameter to filter reviews by that aspect.
          items:
            $ref: '#/components/schemas/AspectStat'
        reviews:
          $ref: '#/components/schemas/Reviews'
        ai_summary:
          $ref: '#/components/schemas/AiSummary'
        bullet_review_summary:
          $ref: '#/components/schemas/BulletReviewSummary'
        product_media:
          type: array
          description: Media (images/videos) attached to reviews of this product
          items:
            $ref: '#/components/schemas/ProductMediaItem'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when no results are found
    SearchMetadata:
      type: object
      required: [id, 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 URL for this search
        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: Engine used for the search
        product_id:
          type: string
          description: Walmart product ID searched for
        rating:
          type: string
          description: Star rating filter applied
        verified_purchases_only:
          type: string
          description: Whether only verified-purchase reviews were returned
        page:
          type: integer
          description: Page number requested
        sort_by:
          type: string
          description: Sort order applied
        aspect_id:
          type: integer
          description: Aspect filter applied
    SearchInformation:
      type: object
      description: Active-aspect context, present when the aspect_id parameter is used
      properties:
        sorting_by:
          type: string
          description: The sort order applied to the reviews
        active_aspect:
          type: object
          description: The aspect currently filtered on
          properties:
            id:
              type: string
              description: Aspect identifier
            name:
              type: string
              description: Aspect name
            count:
              type: integer
              description: Number of review snippets mentioning the aspect
        positive_aspect_count:
          type: integer
          description: Number of positive reviews for the active aspect
        negative_aspect_count:
          type: integer
          description: Number of negative reviews for the active aspect
    Product:
      type: object
      properties:
        title:
          type: string
          description: Product title
        link:
          type: string
          description: Canonical Walmart product URL
        rating:
          type: number
          description: Average overall rating
        reviews_count:
          type: integer
          description: Total number of reviews
        reviews_with_text_count:
          type: integer
          description: Number of reviews that include written text
        reviews_histogram:
          $ref: '#/components/schemas/ReviewsHistogram'
        recommended_percentage:
          type: number
          description: Percentage of reviewers who recommend the product
        media_count:
          type: integer
          description: Total number of media items across all reviews
    ReviewsHistogram:
      type: object
      description: Per-star breakdown of review counts, keyed by star rating (1-5)
      properties:
        '1':
          $ref: '#/components/schemas/RatingBucket'
        '2':
          $ref: '#/components/schemas/RatingBucket'
        '3':
          $ref: '#/components/schemas/RatingBucket'
        '4':
          $ref: '#/components/schemas/RatingBucket'
        '5':
          $ref: '#/components/schemas/RatingBucket'
    RatingBucket:
      type: object
      properties:
        count:
          type: integer
          description: Number of reviews with this star rating
        percentage:
          type: integer
          description: Percentage of reviews with this star rating
        with_text_count:
          type: integer
          description: Number of reviews with this star rating that include written text
    AspectStat:
      type: object
      properties:
        id:
          type: string
          description: Aspect identifier
        name:
          type: string
          description: Aspect name
        score:
          type: number
          description: Aspect score
        count:
          type: integer
          description: Number of review snippets mentioning the aspect
    Reviews:
      type: object
      properties:
        customer_reviews:
          type: array
          description: The reviews on the current page
          items:
            $ref: '#/components/schemas/Review'
        top_positive_review:
          $ref: '#/components/schemas/Review'
        top_negative_review:
          $ref: '#/components/schemas/Review'
    Review:
      type: object
      properties:
        id:
          type: string
          description: Review identifier
        reference_id:
          type: string
          description: Review reference identifier
        title:
          type: string
          description: Review title
        text:
          type: string
          description: Review body text
        rating:
          type: integer
          description: Star rating given in the review
        date:
          type: string
          description: 'Review submission date. Format: MM/DD/YYYY'
        iso_date:
          type: string
          description: 'Review submission date in ISO 8601 format (YYYY-MM-DD)'
        user_id:
          type: string
          description: Reviewer identifier
        user_name:
          type: string
          description: Reviewer display name
        positive_feedback:
          type: integer
          description: Number of helpful (positive) votes
        negative_feedback:
          type: integer
          description: Number of unhelpful (negative) votes
        badges:
          type: array
          description: Badges on the review (e.g. Verified Purchase)
          items:
            type: string
        seller_name:
          type: string
          description: Seller the review is associated with
        item_id:
          type: string
          description: Item identifier the review is associated with
        item_name:
          type: string
          description: Item name the review is associated with
        item_details:
          type: array
          description: Attributes of the reviewed item variant
          items:
            type: object
            properties:
              name:
                type: string
                description: Attribute name
              value:
                type: string
                description: Attribute value
        fulfilled_by:
          type: string
          description: Fulfillment provider
        media:
          type: array
          description: Media attached to the review
          items:
            $ref: '#/components/schemas/ReviewMedia'
    ReviewMedia:
      type: object
      properties:
        id:
          type: string
          description: Media identifier
        link:
          type: string
          description: Media URL
        caption:
          type: string
          description: Media caption
        type:
          type: string
          description: Media type
    AiSummary:
      type: object
      description: AI-generated summary of the product's reviews
      properties:
        title:
          type: string
          description: Summary title
        summary:
          type: string
          description: Summary text
        aspect_spans:
          type: array
          description: Aspects referenced within the summary text, with their character offsets
          items:
            type: object
            properties:
              id:
                type: integer
                description: Aspect identifier
              name:
                type: string
                description: Aspect text as it appears in the summary
              start:
                type: integer
                description: Start character offset within the summary
              end:
                type: integer
                description: End character offset within the summary
              sentiment:
                type: string
                description: Sentiment of the aspect mention
    BulletReviewSummary:
      type: object
      description: Aspect bullets grouped by sentiment polarity
      properties:
        pros:
          type: array
          description: Positive aspect bullets
          items:
            $ref: '#/components/schemas/BulletAspect'
        neutral:
          type: array
          description: Neutral aspect bullets
          items:
            $ref: '#/components/schemas/BulletAspect'
        cons:
          type: array
          description: Negative aspect bullets
          items:
            $ref: '#/components/schemas/BulletAspect'
    BulletAspect:
      type: object
      properties:
        id:
          type: string
          description: Aspect identifier
        name:
          type: string
          description: Aspect name
        text:
          type: string
          description: Short aspect pill text
        polarity:
          type: string
          description: Sentiment polarity of the aspect
        summary:
          type: string
          description: Summary of the aspect across reviews
    ProductMediaItem:
      type: object
      properties:
        id:
          type: string
          description: Media identifier
        review_id:
          type: string
          description: Identifier of the review the media belongs to
        type:
          type: string
          description: Media type
        normal_url:
          type: string
          description: Full-size media URL
        thumbnail_url:
          type: string
          description: Thumbnail media URL
        caption:
          type: string
          description: Media caption
        rating:
          type: integer
          description: Star rating of the review the media belongs to
    Pagination:
      type: object
      properties:
        current:
          type: integer
          description: Current page number
        next:
          type: string
          description: URL for the next page of reviews
        previous:
          type: string
          description: URL for the previous page of reviews
        total_pages:
          type: integer
          description: Total number of review pages
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong