openapi: 3.0.0
info:
  title: Facebook Business Page Reviews API
  description: |
    Retrieve public recommendations left on a Facebook Business Page, including the review text, whether the reviewer recommends the business, the reviewer's profile, attached images, reactions, and comment threads.

    Facebook reviews are recommendations rather than star ratings, so each review reports `recommendation` ("recommends" or "doesn't recommend") instead of a numeric score. The page-level `rating` follows the same model: it is the percentage of reviewers who recommend the business, from 0 to 100, and not a score out of 5. These fields match the `about.ratings`, `about.rating`, and `about.reviews_count` fields of the Facebook Business Page API.

    **Cross-linking**: `page_id` and `username` are the same identifiers used by the Facebook Business Page API, so a page located there can be passed straight to this API. The `page` object returned on the first page mirrors the `page` object of the Facebook Business Page API. Paginate with `pagination.next_page_token`; token-based pages return reviews only and omit `page`, `rating`, and `reviews_count`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Facebook Business Page Reviews
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to `facebook_business_page_reviews` for this API.
          schema:
            type: string
            enum: ["facebook_business_page_reviews"]
            default: "facebook_business_page_reviews"
        - name: page_id
          in: query
          required: false
          description: The numeric ID of the Facebook Business Page. Provide exactly one of `page_id`, `username`, or `url`, unless `next_page_token` is used.
          schema:
            type: string
        - name: username
          in: query
          required: false
          description: The username (vanity URL slug) of the Facebook Business Page. Provide exactly one of `page_id`, `username`, or `url`, unless `next_page_token` is used.
          schema:
            type: string
        - name: url
          in: query
          required: false
          description: 'A full Facebook page URL. Accepts direct page URLs, `profile.php?id=` URLs, `/pages/<name>/<id>` URLs, and mobile share links (`facebook.com/share/<token>/`), which are resolved to their canonical page. Provide exactly one of `page_id`, `username`, or `url`, unless `next_page_token` is used. Maximum length is 2048 characters.'
          schema:
            type: string
            maxLength: 2048
        - name: next_page_token
          in: query
          required: false
          description: Token for retrieving the next set of reviews, taken from `pagination.next_page_token` of a previous response. When provided, it replaces `page_id`, `username`, and `url`.
          schema:
            type: string
      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'
        page:
          $ref: '#/components/schemas/Page'
        ratings:
          type: string
          description: 'Rating summary as displayed by Facebook, in one of two shapes: "64% recommend (906 reviews)" or "Not yet rated (1 review)". `rating` and `reviews_count` are the values parsed out of it.'
        rating:
          type: integer
          description: 'Percentage of reviewers who recommend the business, from 0 to 100. This is a recommendation rate, not a star rating: Facebook reviews are recommendations, so there is no score out of 5. Omitted when the page has not been rated yet, and on responses fetched with `next_page_token`.'
        reviews_count:
          type: integer
          description: Total number of reviews the page has received. Omitted on responses fetched with `next_page_token`.
        reviews:
          type: array
          description: Reviews returned for the requested page
          items:
            $ref: '#/components/schemas/Review'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message returned when no reviews can be retrieved

    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: Facebook 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: The engine used for this search
        page_id:
          type: string
          description: The page ID used for this search
        username:
          type: string
          description: The page username used for this search
        url:
          type: string
          description: The page URL used for this search
        next_page_token:
          type: string
          description: The pagination token used for this search

    Page:
      type: object
      description: Details of the Facebook Business Page the reviews belong to. Returned only on the first page of results; responses fetched with `next_page_token` omit it.
      properties:
        id:
          type: string
          description: Numeric ID of the page
        name:
          type: string
          description: Display name of the page
        link:
          type: string
          description: Canonical Facebook URL of the page
        username:
          type: string
          description: Username (vanity URL slug) of the page
        alternate_name:
          type: string
          description: Secondary name shown alongside the page name
        is_verified:
          type: boolean
          description: Whether the page carries a verified badge
        followers:
          $ref: '#/components/schemas/SocialMetric'
        following:
          $ref: '#/components/schemas/SocialMetric'
        profile_photo_original:
          type: string
          description: URL of the page's profile photo image file
        profile_photo_link:
          type: string
          description: Facebook URL of the profile photo post
        cover_photo_original:
          type: string
          description: URL of the page's cover photo image file
        cover_photo_link:
          type: string
          description: Facebook URL of the cover photo post

    SocialMetric:
      type: object
      description: A follower or following count with its Facebook listing URL
      properties:
        text:
          type: string
          description: Count as displayed by Facebook
        link:
          type: string
          description: Facebook URL listing the accounts
        count:
          type: integer
          description: Count parsed into a number

    Review:
      type: object
      properties:
        review_id:
          type: string
          description: Facebook post ID of the review
        link:
          type: string
          description: Facebook URL of the review post
        recommendation:
          type: string
          description: Whether the reviewer recommends the business
          enum: ["recommends", "doesn't recommend"]
        text:
          type: string
          description: Body of the review
        date:
          type: string
          description: Date the review was published, in "Mon DD, YYYY" format
        iso_date:
          type: string
          format: date-time
          description: Date the review was published, in ISO 8601 format
        user:
          $ref: '#/components/schemas/ReviewUser'
        tags:
          type: array
          description: Labels Facebook attached to the review
          items:
            type: string
        images:
          type: array
          description: Images attached to the review
          items:
            $ref: '#/components/schemas/Image'
        reactions_count:
          type: integer
          description: Number of reactions the review received
        comments_count:
          type: integer
          description: Total number of comments on the review
        comments:
          type: array
          description: Comments returned with the review
          items:
            $ref: '#/components/schemas/Comment'

    ReviewUser:
      type: object
      description: Facebook profile of the reviewer
      properties:
        user_id:
          type: string
          description: ID of the reviewer's profile
        name:
          type: string
          description: Name of the reviewer
        link:
          type: string
          description: Facebook URL of the reviewer's profile
        thumbnail:
          type: string
          description: URL of the reviewer's profile picture

    Image:
      type: object
      properties:
        link:
          type: string
          description: URL of the image file
        width:
          type: integer
          description: Width of the image in pixels
        height:
          type: integer
          description: Height of the image in pixels

    Comment:
      type: object
      properties:
        comment_id:
          type: string
          description: ID of the comment
        text:
          type: string
          description: Body of the comment
        date:
          type: string
          description: Date the comment was published, in "Mon DD, YYYY" format
        iso_date:
          type: string
          format: date-time
          description: Date the comment was published, in ISO 8601 format
        user:
          $ref: '#/components/schemas/CommentUser'

    CommentUser:
      type: object
      description: Facebook profile of the commenter
      properties:
        user_id:
          type: string
          description: ID of the commenter's profile
        name:
          type: string
          description: Name of the commenter
        thumbnail:
          type: string
          description: URL of the commenter's profile picture

    Pagination:
      type: object
      properties:
        next_page_token:
          type: string
          description: Token for retrieving the next set of reviews. Pass it back as the `next_page_token` parameter. Absent on the last page.

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong