openapi: 3.0.0
info:
  title: Yellow Pages Place API
  description: >-
    Get a Yellow Pages business page by its place_id: contact details, address and coordinates, weekly hours,
    categories, Yellow Pages and Tripadvisor ratings, badges such as years in business and claimed, the More Info
    details (services, brands, payment methods, neighborhoods and other information), photos, and the first ten
    reviews with their per-aspect stars. The place_id is the number that ends a Yellow Pages business page URL.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Yellow Pages Place Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to yellowpages_place.
        schema:
          type: string
          enum: ["yellowpages_place"]
      - name: place_id
        in: query
        required: true
        description: Numeric id of the Yellow Pages business, the number that ends its page URL.
        schema:
          type: string
          pattern: "^[1-9][0-9]{0,11}$"
      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"
        place_result:
          "$ref": "#/components/schemas/PlaceResult"
        reviews:
          type: array
          description: The ten most recent reviews of the business.
          items:
            "$ref": "#/components/schemas/Review"
        reviews_pagination:
          "$ref": "#/components/schemas/ReviewsPagination"
        error:
          type: string
          description: Message returned instead of place_result when Yellow Pages has no business with the place_id.
    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: Yellow Pages 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
          enum: ["yellowpages_place"]
          description: Set to yellowpages_place.
        place_id:
          type: string
          pattern: "^[1-9][0-9]{0,11}$"
          description: Numeric id of the Yellow Pages business.
    PlaceResult:
      type: object
      required:
      - place_id
      - title
      - link
      - type
      - categories
      - phone
      properties:
        place_id:
          type: string
          description: Numeric id of the business on Yellow Pages.
        title:
          type: string
          description: Name of the business.
        link:
          type: string
          description: Yellow Pages page of the business.
        type:
          type: string
          description: Kind of business, such as Restaurant, Dentist or LocalBusiness.
        categories:
          type: array
          description: Yellow Pages categories the business is listed in.
          items:
            "$ref": "#/components/schemas/Category"
        rating:
          type: number
          description: Average Yellow Pages rating, from 1 to 5 in half stars.
        reviews:
          type: integer
          description: Number of Yellow Pages reviews.
        web_reviews:
          type: array
          description: Ratings of the business on other review sites.
          items:
            "$ref": "#/components/schemas/WebReview"
        phone:
          type: string
          description: Main phone number.
        extra_phones:
          type: array
          description: Other phone numbers, such as fax or toll-free lines.
          items:
            "$ref": "#/components/schemas/ExtraPhone"
        address:
          type: string
          description: Address as the page shows it.
        street_address:
          type: string
          description: Street line of the address.
        city:
          type: string
          description: City of the business.
        state:
          type: string
          description: Two-letter state code.
        postal_code:
          type: string
          description: Five-digit ZIP code.
        gps_coordinates:
          "$ref": "#/components/schemas/GpsCoordinates"
        website:
          type: string
          description: Website of the business.
        email:
          type: string
          description: Email address of the business.
        open_state:
          type: string
          description: Whether the business is open at the time of the search, as the page words it.
        hours:
          type: string
          description: Opening hours for the day of the search, as the page words them.
        open_hours:
          "$ref": "#/components/schemas/OpenHours"
        open_hours_text:
          type: string
          description: Opening hours the business writes as text instead of a weekly table.
        years_in_business:
          type: integer
          description: Number of years the business has operated.
        years_with_yp:
          type: integer
          description: Number of years the business has advertised with Yellow Pages.
        is_claimed:
          type: boolean
          description: Whether the owner has claimed the listing.
        is_paid_listing:
          type: boolean
          description: Whether the listing is a paid Yellow Pages listing.
        is_preferred:
          type: boolean
          description: Whether the business carries the YP Preferred badge.
        amenities:
          type: array
          description: Amenities the business lists.
          items:
            type: string
        slogan:
          type: string
          description: Slogan of the business.
        special_offer:
          "$ref": "#/components/schemas/SpecialOffer"
        description:
          type: string
          description: General information the business gives about itself.
        business_history:
          type: string
          description: History the business gives, such as the year it opened.
        services:
          type: array
          description: Services and products the business offers.
          items:
            type: string
        brands:
          type: array
          description: Brands the business carries or services.
          items:
            type: string
        payment_methods:
          type: array
          description: Payment methods the business accepts.
          items:
            type: string
        price:
          type: string
          description: Price range in dollar signs.
        languages:
          type: array
          description: Languages spoken at the business.
          items:
            type: string
        ownership:
          type: string
          description: Ownership of the business, such as Locally Owned.
        has_free_estimates:
          type: boolean
          description: Whether the business offers free estimates.
        neighborhoods:
          type: array
          description: Neighborhoods the business is in.
          items:
            type: string
        location_description:
          type: string
          description: Where the business is located, such as the venue it is inside.
        accreditations:
          type: array
          description: Accreditations of the business.
          items:
            type: string
        associations:
          type: array
          description: Associations the business belongs to.
          items:
            type: string
        also_known_as:
          type: array
          description: Other names of the business.
          items:
            type: string
        other_links:
          type: array
          description: Other websites of the business.
          items:
            type: string
        social_links:
          type: array
          description: Social media pages of the business.
          items:
            type: string
        other_information:
          type: array
          description: Other details the business lists, such as parking, cuisines or accepted insurance.
          items:
            "$ref": "#/components/schemas/OtherInformation"
        logo:
          type: string
          description: Logo of the business.
        thumbnail:
          type: string
          description: Main photo of the business.
        images:
          type: array
          description: Photos shown on the business page.
          items:
            "$ref": "#/components/schemas/Image"
        total_images:
          type: integer
          description: Number of photos in the business gallery, excluding videos.
    Category:
      type: object
      required:
      - title
      - link
      properties:
        title:
          type: string
          description: Name of the category.
        link:
          type: string
          description: Yellow Pages page of the category in the business's city.
    WebReview:
      type: object
      required:
      - title
      - link
      - rating
      - reviews
      properties:
        title:
          type: string
          description: Name of the review site.
        link:
          type: string
          description: Reviews of the business on that site.
        rating:
          type: number
          description: Average rating on that site, from 1 to 5.
        reviews:
          type: integer
          description: Number of reviews on that site.
    ExtraPhone:
      type: object
      required:
      - title
      - phone
      properties:
        title:
          type: string
          description: Label of the number, such as Fax or TollFree.
        phone:
          type: string
          description: Phone number.
    GpsCoordinates:
      type: object
      required:
      - latitude
      - longitude
      properties:
        latitude:
          type: number
          description: Latitude of the business.
        longitude:
          type: number
          description: Longitude of the business.
    OpenHours:
      type: object
      description: Opening hours for each day of the week as the page shows them, such as 9:00 am - 5:00 pm, Open 24 Hours or Closed.
      additionalProperties: false
      properties:
        monday:
          type: string
          description: Opening hours on Monday.
        tuesday:
          type: string
          description: Opening hours on Tuesday.
        wednesday:
          type: string
          description: Opening hours on Wednesday.
        thursday:
          type: string
          description: Opening hours on Thursday.
        friday:
          type: string
          description: Opening hours on Friday.
        saturday:
          type: string
          description: Opening hours on Saturday.
        sunday:
          type: string
          description: Opening hours on Sunday.
    SpecialOffer:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          description: Message the business shows on its page.
        link:
          type: string
          description: Page the message links to.
    OtherInformation:
      type: object
      required:
      - title
      - value
      properties:
        title:
          type: string
          description: Name of the detail.
        value:
          type: string
          description: Value of the detail.
    Image:
      type: object
      required:
      - original
      - thumbnail
      - source
      properties:
        original:
          type: string
          description: Full-size photo.
        thumbnail:
          type: string
          description: Smaller copy of the photo.
        source:
          type: string
          enum: ["Yellow Pages", "Tripadvisor"]
          description: Site the photo comes from.
    Review:
      type: object
      required:
      - position
      - review_id
      - user
      - iso_date
      - rating
      - votes
      properties:
        position:
          type: integer
          description: Position of the review on the page, starting at 1.
        review_id:
          type: string
          description: Unique identifier of the review.
        user:
          "$ref": "#/components/schemas/User"
        iso_date:
          type: string
          format: date
          description: Date the review was posted or last edited, as YYYY-MM-DD.
        is_edited:
          type: boolean
          description: Whether the reviewer edited the review.
        rating:
          type: number
          description: Overall rating the reviewer gave, from 1 to 5.
        subratings:
          type: array
          description: Ratings the reviewer gave for each aspect, such as food or professionalism.
          items:
            "$ref": "#/components/schemas/Subrating"
        title:
          type: string
          description: Title of the review.
        text:
          type: string
          description: Text of the review.
        votes:
          type: integer
          description: Number of readers who found the review helpful.
        response:
          "$ref": "#/components/schemas/ReviewResponse"
    ReviewResponse:
      type: object
      required:
      - text
      - iso_date
      properties:
        text:
          type: string
          description: Reply of the business to the review.
        iso_date:
          type: string
          format: date
          description: Date of the reply, as YYYY-MM-DD.
    User:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name the reviewer shows.
        link:
          type: string
          description: Yellow Pages page of the reviewer's reviews.
        thumbnail:
          type: string
          description: Profile photo of the reviewer.
    Subrating:
      type: object
      required:
      - text
      - value
      properties:
        text:
          type: string
          description: Aspect rated.
        value:
          type: number
          description: Rating for the aspect, from 1 to 5.
    ReviewsPagination:
      type: object
      required:
      - current
      - total
      - next
      properties:
        current:
          type: integer
          description: Page of reviews returned.
        total:
          type: integer
          description: Number of reviews across all pages.
        next:
          type: string
          description: Yellow Pages page with the next ten reviews.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
