openapi: 3.0.0
info:
  title: SmartCustomer Reviews API
  description: |
    Get the customer reviews of a website or business on SmartCustomer (formerly Sitejabber), 20 per page.

    Each review carries its 1-5 rating, title, full text, review date and time, date of experience, helpful votes, badges such as Verified, images, the business's reply, and the author's name, profile link, avatar, location and review count. The response also returns the business's name, website, logo, overall rating and review count, and SmartCustomer's AI summary with its highlights and most discussed topics.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: SmartCustomer Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `smartcustomer_reviews`'
          schema:
            type: string
            enum: ["smartcustomer_reviews"]
        - name: domain
          in: query
          required: true
          description: The website's domain, such as `amazon.com`, of up to 253 characters. A smartcustomer.com or sitejabber.com review page URL also works, but the page returned always comes from `page`.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page of reviews, 20 per page.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1
      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'
        business:
          type: object
          required: [name]
          properties:
            name:
              type: string
              description: Business name.
            domain:
              type: string
              description: Domain the reviews are for.
            link:
              type: string
              description: The business's review page on SmartCustomer.
            website:
              type: string
              description: The business's own website.
            logo:
              type: string
              description: Business logo URL.
            description:
              type: string
              description: Business description.
            email:
              type: string
              description: Business contact email.
            address:
              type: string
              description: Business address.
            social_profiles:
              type: array
              description: Links to the business's social profiles.
              items:
                type: string
            rating:
              type: number
              description: Overall rating out of 5.
            reviews_count:
              type: integer
              description: Number of reviews SmartCustomer counts for the business, which can exceed the reviews its pages list.
        ai_summary:
          type: object
          description: SmartCustomer's AI summary of the reviews.
          properties:
            positive_highlights:
              type: array
              description: What reviewers praise.
              items:
                type: string
            negative_highlights:
              type: array
              description: What reviewers criticize.
              items:
                type: string
            topics:
              type: array
              description: The most discussed topics.
              items:
                type: object
                required: [name]
                properties:
                  name:
                    type: string
                    description: Topic name.
                  sentiment:
                    type: string
                    description: Prevailing sentiment of reviews on this topic, such as negative.
                  reviews_count:
                    type: integer
                    description: Number of reviews the summary read for this topic, the base of its shares.
                  positive_percentage:
                    type: number
                    description: Share of the topic's reviews_count reviews that are positive.
                  neutral_percentage:
                    type: number
                    description: Share of the topic's reviews_count reviews that are neutral.
                  negative_percentage:
                    type: number
                    description: Share of the topic's reviews_count reviews that are negative.
                  summary:
                    type: string
                    description: Summary of what reviewers say on this topic.
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
        pagination:
          type: object
          properties:
            current:
              type: integer
              description: Current page.
            next_page:
              type: integer
              description: Value to pass as `page` for the next page.
            total_pages:
              type: integer
              description: Number of pages of reviews.
        error:
          type: string
          description: Why there are no reviews to return.
    Review:
      type: object
      required: [position, review_id, link, rating, date, author]
      properties:
        position:
          type: integer
          description: Position of the review across pages.
        review_id:
          type: string
          description: SmartCustomer identifier of the review.
        link:
          type: string
          description: Link to the review.
        rating:
          type: number
          description: Rating from 1 to 5.
        title:
          type: string
          description: Review title.
        text:
          type: string
          description: Review text, with paragraphs on separate lines.
        date:
          type: string
          format: date
          description: Date the review was published.
        iso_date:
          type: string
          format: date-time
          description: Time the review was published, in UTC.
        experience_date:
          type: string
          format: date
          description: Date of the experience the review describes.
        helpful_votes:
          type: integer
          description: Number of helpful votes the review received.
        badges:
          type: array
          description: Badges shown on the review, such as Verified.
          items:
            type: string
        author:
          type: object
          required: [name]
          properties:
            name:
              type: string
              description: Author name as shown.
            link:
              type: string
              description: Author profile on SmartCustomer.
            avatar:
              type: string
              description: Author avatar URL.
            location:
              type: string
              description: Author location.
            reviews_count:
              type: integer
              description: Number of reviews the author has written.
            helpful_votes:
              type: integer
              description: Helpful votes the author has received across reviews.
        images:
          type: array
          description: Photos attached to the review.
          items:
            type: object
            required: [original]
            properties:
              original:
                type: string
                description: Full-size photo URL.
              thumbnail:
                type: string
                description: Thumbnail URL.
        reply:
          type: object
          description: The business's reply to the review.
          required: [text]
          properties:
            text:
              type: string
              description: Reply text.
            author:
              type: string
              description: Name of the business representative who replied.
            date:
              type: string
              format: date
              description: Date of the reply.
            iso_date:
              type: string
              format: date-time
              description: Time of the reply, in UTC.
    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: SmartCustomer 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
        domain:
          type: string
        page:
          type: integer
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong