openapi: 3.0.0
info:
  title: Reviews.io Reviews API
  description: |
    Get the customer reviews of an online store on Reviews.io, 20 per page, sorted by most recent or highest rated and optionally filtered by star rating.

    Each review carries its 1-5 rating, full text, date, author name, badge such as Verified Buyer, photos and the store's reply. The response also returns the store's name, website, logo, overall rating, review count, the share of reviewers who recommend it, its contact details and its delivery and customer service metrics.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Reviews.io Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `reviews_io_reviews`'
          schema:
            type: string
            enum: ["reviews_io_reviews"]
        - name: store
          in: query
          required: true
          description: The store's name as it appears in its Reviews.io page URL, such as `gymshark-com`, or the full store page URL. The name has up to 128 characters, starts with a letter or digit, and uses only letters, digits, `.`, `_` and `-`.
          schema:
            type: string
        - name: sort_by
          in: query
          required: false
          description: Order of reviews.
          schema:
            type: string
            enum: ["most_recent", "highest_rated"]
            default: "most_recent"
        - name: rating
          in: query
          required: false
          description: Only reviews with this star rating.
          schema:
            type: integer
            enum: [1, 2, 3, 4, 5]
        - name: next_page_token
          in: query
          required: false
          description: The `pagination.next_page_token` from the previous page, sent with the same `sort_by` and `rating`, to get the next 20 reviews.
          schema:
            type: string
            pattern: '^[A-Za-z0-9]{1,16}$'
            maxLength: 16
      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
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        store:
          type: object
          required: [name, link, rating, reviews_count]
          properties:
            name:
              type: string
              description: Store name.
            link:
              type: string
              description: The store's review page on Reviews.io.
            website:
              type: string
              description: The store's own website.
            logo:
              type: string
              description: Store logo URL.
            rating:
              type: number
              description: Average rating on a 1-5 scale.
            reviews_count:
              type: integer
              description: Total number of reviews.
            recommend_percentage:
              type: integer
              description: Percentage of reviewers who recommend the store.
            description:
              type: string
              description: The store's description of itself.
            phone:
              type: string
              description: Store phone number.
            email:
              type: string
              description: Store contact email.
            address:
              type: string
              description: Store address.
            metrics:
              type: array
              description: The store's delivery and customer service metrics.
              items:
                type: object
                required: [category, name, value]
                properties:
                  category:
                    type: string
                    description: Group the metric belongs to, such as Shipping & Delivery.
                  name:
                    type: string
                    description: Metric name.
                  value:
                    type: string
                    description: Metric value as shown on the page.
        reviews:
          type: array
          items:
            type: object
            required: [position, review_id, rating]
            properties:
              position:
                type: integer
                description: Position of the review across pages.
              review_id:
                type: string
                description: Reviews.io review ID.
              link:
                type: string
                description: Link to the review on Reviews.io.
              rating:
                type: integer
                description: Rating on a 1-5 scale.
              text:
                type: string
                description: Full review text.
              date:
                type: string
                format: date
                description: 'Date the review was published. Format: YYYY-MM-DD'
              author:
                type: string
                description: Reviewer name as shown on Reviews.io.
              badge:
                type: string
                description: Reviewer badge, such as Verified Buyer.
              is_verified:
                type: boolean
                description: Whether the reviewer is verified.
              images:
                type: array
                description: Photos attached to the review.
                items:
                  type: string
              reply:
                type: string
                description: The store's reply to the review.
        pagination:
          type: object
          required: [current]
          properties:
            current:
              type: integer
              description: Current page number.
            next_page_token:
              type: string
              description: Token for the next page of reviews.
        error:
          type: string
          description: Why there are no reviews to return.
    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: Reviews.io 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
        store:
          type: string
        sort_by:
          type: string
          enum: ["most_recent", "highest_rated"]
        rating:
          type: integer
        next_page_token:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
