openapi: 3.0.0
info:
  title: Facebook Business Page API
  description: |
    Retrieve the public profile of a Facebook Business Page or personal profile, including its name, follower counts, photos, and the details listed in the page's About section such as category, address, contact details, opening hours, and rating.

    Business pages and personal profiles expose different About fields. Business pages return fields such as `category`, `address`, `phone`, and `rating`, while personal profiles return fields such as `work`, `education`, `hometown`, and `relationship`. Both are returned under the same `about` object, and only the fields present on the profile are included.

    **Cross-linking**: `page_id` and `username` are the same identifiers used by the Facebook Business Page Reviews API, so a page located here can be passed straight to that API to fetch the reviews behind `about.rating` and `about.reviews_count`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Facebook Business Page
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to `facebook_business_page` for this API.
          schema:
            type: string
            enum: ["facebook_business_page"]
            default: "facebook_business_page"
        - 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`.
          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`.
          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`. Maximum length is 2048 characters.'
          schema:
            type: string
            maxLength: 2048
      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'
        about:
          $ref: '#/components/schemas/About'
        error:
          type: string
          description: Error message returned when the page cannot 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

    Page:
      type: object
      description: Identity and headline statistics of the Facebook page or profile
      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

    About:
      type: object
      description: Details from the page's About section. Business pages and personal profiles expose different subsets of these fields, and only fields present on the profile are returned.
      properties:
        category:
          type: string
          description: Categories assigned to the page, as displayed by Facebook
        category_formatted:
          type: array
          description: Categories split into individual values
          items:
            type: string
        address:
          type: string
          description: Street address of the business
        gps_coordinates:
          $ref: '#/components/schemas/GpsCoordinates'
        email:
          type: string
          description: Contact email address listed on the page
        phone:
          type: string
          description: Contact phone number listed on the page
        whatsapp_phone:
          type: string
          description: WhatsApp number listed on the page
        instagram_username:
          type: string
          description: Instagram username linked from the page
        youtube_channel_id:
          type: string
          description: YouTube channel linked from the page
        website:
          type: string
          description: Website listed on the page
        ratings:
          type: string
          description: 'Rating summary as displayed by Facebook, in one of two shapes: "100% recommend (2,186 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.'
        reviews_count:
          type: integer
          description: Total number of reviews the page has received
        business_hours:
          type: string
          description: Opening hours status as displayed by Facebook
        business_services:
          type: string
          description: Services the business offers
        languages:
          type: string
          description: Languages the business speaks
        price_range:
          type: string
          description: Price range of the business
        work:
          type: array
          description: Workplaces listed on a personal profile
          items:
            $ref: '#/components/schemas/ProfileEntry'
        education:
          type: array
          description: Schools listed on a personal profile
          items:
            $ref: '#/components/schemas/ProfileEntry'
        current_city:
          type: string
          description: Current city listed on a personal profile
        current_city_link:
          type: string
          description: Facebook URL of the current city
        hometown:
          type: string
          description: Hometown listed on a personal profile
        hometown_link:
          type: string
          description: Facebook URL of the hometown
        relationship:
          type: string
          description: Relationship status listed on a personal profile
        relationship_date:
          type: string
          description: Date associated with the relationship status

    GpsCoordinates:
      type: object
      description: Coordinates of the business address
      properties:
        latitude:
          type: number
          description: Latitude of the business
        longitude:
          type: number
          description: Longitude of the business

    ProfileEntry:
      type: object
      description: A work or education entry on a personal profile
      properties:
        title:
          type: string
          description: Title of the entry, such as the role and organization
        date:
          type: string
          description: Period associated with the entry
        description:
          type: string
          description: Additional detail listed under the entry
        link:
          type: string
          description: Facebook URL of the linked organization

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