Yelp Business Detail Scraper

Scrape a single Yelp business page and extract structured business information such as contact details, ratings, categories, opening hours, amenities, business description, owner information, services, review highlights, related searches, and business photos.

Disclaimer: This is an independent, unofficial scraping tool. It is not affiliated with, endorsed by, or sponsored by Yelp. Users are responsible for complying with Yelp's terms, applicable laws, and any website access restrictions.

Features

• Scrapes a single Yelp business detail page.
• Accepts a full Yelp URL such as https://www.yelp.com/biz/biscuit-bitch-seattle.
• Also accepts a relative Yelp path such as /biz/biscuit-bitch-seattle.
• Automatically normalizes relative Yelp URLs to absolute URLs.
• Extracts business name, Yelp URL, claimed status, and business status.
• Extracts rating, review count, and price range.
• Extracts business categories.
• Extracts phone number, address, and external website.
• Extracts opening hours by day.
• Extracts detailed amenities with availability status when available.
• Extracts the business description / "About the Business" content.
• Extracts business history and year established when available.
• Extracts business owner information when available.
• Extracts services offered when available.
• Extracts Yelp review highlights.
• Extracts "People also searched for" terms.
• Extracts business photo URLs.
• Uses Yelp's embedded Apollo state when available for richer structured data.
• Uses retry logic for transient request failures.
• Detects common block/challenge responses.
• Uses a residential proxy when available through Apify Proxy.
• Maintains a reusable cookie cache between runs.
• Can refresh the cached cookie separately using the refreshCookieOnly input.
• Stores each successful scrape as one Dataset item.

Input

The Actor accepts the following input:

---

Field Type Required Default Description

---

url string Yes* --- Yelp business URL or relative /biz/... path.

refreshCookieOnly boolean No false Refresh/check the cached Yelp cookie without scraping a business page.

* url is required for a normal scrape. It is ignored when refreshCookieOnly is true.

Example input

{
  "url": "https://www.yelp.com/biz/biscuit-bitch-seattle",
  "refreshCookieOnly": false
}

Relative URL example

{
  "url": "/biz/biscuit-bitch-seattle?osq=Vegan+Restaurant",
  "refreshCookieOnly": false
}

The Actor converts the relative path to:

https://www.yelp.com/biz/biscuit-bitch-seattle?osq=Vegan+Restaurant

Output

The Actor writes one structured object to the Apify Dataset for each successful scrape.

Output structure

{
  "business": {
    "url": "https://www.yelp.com/biz/biscuit-bitch-seattle",
    "name": "Biscuit Bitch",
    "claimed": true,
    "status": null
  },
  "rating": {
    "rating": 4.2,
    "review_count": 3500,
    "price": "$$"
  },
  "category": [
    "Breakfast & Brunch",
    "Southern"
  ],
  "contact": {
    "phone": "+1 206-555-1234",
    "address": "Seattle, WA",
    "website": "https://example.com"
  },
  "hours": {
    "monday": {
      "hours": "8:00 AM-2:00 PM",
      "status": ""
    },
    "tuesday": {
      "hours": "8:00 AM-2:00 PM",
      "status": ""
    }
  },
  "amenities": [
    {
      "name": "Outdoor seating",
      "available": true
    },
    {
      "name": "Wi-Fi",
      "available": true
    }
  ],
  "about": "Business description when available.",
  "history": {
    "year_established": 2010,
    "description": "Business history when available."
  },
  "business_owner": {
    "name": "Owner Name",
    "role": "Owner",
    "bio": "Owner biography when available."
  },
  "services_offered": [
    "Catering"
  ],
  "review_highlights": [
    "Example review highlight"
  ],
  "people_also_searched": [
    "Breakfast",
    "Brunch"
  ],
  "image_details": {
    "images": [
      "https://example.com/photo1.jpg",
      "https://example.com/photo2.jpg"
    ]
  }
}

The example values above are illustrative. Actual values depend on the Yelp page being scraped.

Extracted fields

Business

• business.url --- Scraped Yelp business URL.
• business.name --- Business name.
• business.claimed --- Whether Yelp identifies the business as claimed.
• business.status --- Business status, such as permanently or temporarily closed, when available.

Rating

• rating.rating --- Yelp star rating.
• rating.review_count --- Number of reviews.
• rating.price --- Yelp price range.

Category

• category --- List of Yelp business categories.

Contact

• contact.phone --- Business phone number.
• contact.address --- Business address.
• contact.website --- Business's external website, when available.

Hours

• hours --- Opening hours organized by day.

Amenities

• amenities --- Available Yelp amenities and their active/available status when Apollo data is available.

About and business information

• about --- Business description.
• history.year_established --- Year established when available.
• history.description --- Business history description when available.
• business_owner.name --- Business owner name when available.
• business_owner.role --- Owner role when available.
• business_owner.bio --- Owner biography when available.
• services_offered --- Services listed by Yelp.

Reviews and discovery

• review_highlights --- Review highlight text extracted from the page.
• people_also_searched --- Related search terms displayed by Yelp.

Images

• image_details.images --- Business photo URLs.

How it works

The Actor uses the following high-level workflow:

Input Yelp URL
      |
      v
Normalize Yelp URL
      |
      v
Open / retrieve cached cookie
      |
      v
Configure Apify residential proxy
      |
      v
Fetch Yelp business page
      |
      +---- Block/challenge detected
      |          |
      |          v
      |     Refresh cookie
      |          |
      |          v
      |     Retry request
      |
      v
Parse HTML
      |
      +---- Extract visible page data
      |
      +---- Extract Apollo business data
      |
      v
Build structured result
      |
      v
Push result to Apify Dataset

Anti-block and reliability handling

Yelp may return challenge or access-denied pages instead of the requested business page. The Actor includes several mechanisms intended to improve reliability:

Cookie cache

A named Apify Key-Value Store is used for the cached cookie:

yelp-detail-cookie-cache

The cookie is reused across runs instead of being regenerated for every scrape.

Automatic cookie refresh

When a hard 403 block is detected, the Actor attempts to refresh the cookie using an automated Chrome session running through Xvfb.

The cookie refresh implementation is contained in:

src/cookie_refresh.py

Residential proxy

The Actor attempts to create an Apify residential proxy session:

Actor.create_proxy_configuration(groups=["RESIDENTIAL"])

If residential proxy configuration is unavailable, the Actor logs a warning and continues using the available connection.

Retry handling

The page fetcher retries transient failures and block responses before giving up.

HTTP 404 is treated as a genuine missing business page and is not repeatedly retried.

Scheduled cookie refresh

For workloads that run frequently, you can execute the Actor with:

{
  "refreshCookieOnly": true
}

This mode:

1. Loads the cached cookie.
2. Probes a Yelp business detail page.
3. Keeps the existing cookie if it still works.
4. Generates a fresh cookie if the cached cookie no longer works.
5. Does not scrape or push a business result.

This can be useful as a scheduled warm-up before regular scraping runs.

Project structure

yelp-business-detail-scraper/
│
├── .actor/
│   ├── actor.json
│   ├── input_schema.json
│   ├── output_schema.json
│   └── dataset_schema.json
│
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── cookie_refresh.py
│   ├── main.py
│   └── yelp_core.py
│
├── Dockerfile
├── requirements.txt
└── README.md

Main source files

src/main.py

Main Apify Actor entry point.

Responsible for:

• Reading Actor input.
• Opening the cookie cache.
• Configuring the residential proxy.
• Loading or refreshing cookies.
• Fetching the Yelp page.
• Calling the extraction logic.
• Pushing the final result to the Dataset.

src/yelp_core.py

Contains the main Yelp scraping and parsing logic.

Responsible for:

• URL normalization.
• HTTP session creation.
• Request retries.
• Block detection.
• Apollo-state extraction.
• Business data extraction.
• Contact extraction.
• Hours extraction.
• Amenities extraction.
• Photo extraction.
• Review-highlight extraction.
• Related-search extraction.

src/cookie_refresh.py

Handles automated browser-based cookie refresh using Chrome, Selenium/undetected-chromedriver, and Xvfb.

src/config.py

Contains browser profiles and common request headers.

.actor/input_schema.json

Defines the Actor's user inputs.

.actor/output_schema.json

Defines the structure of the Actor output.

.actor/dataset_schema.json

Controls how Dataset records are presented to users in Apify.

Docker environment

The Actor runs on Python 3.11.

Python 3.11 is intentionally used because the browser/cookie-refresh dependencies require compatibility with the current environment.

The Docker image installs:

• Google Chrome
• Xvfb
• Required fonts
• Python dependencies

The Actor is started with:

$python -m src.main

Dependencies

Main dependencies include:

• apify
• curl_cffi
• beautifulsoup4
• lxml
• undetected-chromedriver
• selenium
• pyvirtualdisplay

See requirements.txt for the exact package requirements.

Running locally

Install the dependencies:

$pip install -r requirements.txt

For the complete cookie-refresh workflow, the environment also needs Google Chrome and Xvfb.

Run the Actor with:

$python -m src.main

When running inside Apify, the Actor uses the Apify SDK to obtain input, proxy configuration, Key-Value Store access, and Dataset access.

Apify Store usage

Recommended workflow:

1. Enter a Yelp business URL.
2. Start the Actor.
3. The Actor loads a cached cookie or creates one when required.
4. The Yelp business page is fetched.
5. Business information is extracted.
6. The structured result is saved to the Dataset.
7. The Dataset can be exported as JSON, CSV, Excel, or other supported formats.

Example use case

Input:

https://www.yelp.com/biz/biscuit-bitch-seattle?osq=Vegan+Restaurant

The Actor extracts available business information from the detail page and returns it as a structured Dataset record.

Limitations

• Yelp page structure can change without notice.
• Some fields may be unavailable for particular businesses.
• Yelp may return challenge or access-denied pages.
• Some data is only available when Yelp embeds it in the page or Apollo state.
• Business pages with missing or changed HTML structures may return null or empty arrays for individual fields.
• Photo URLs and other page assets can change over time.
• The Actor does not guarantee that every Yelp field will be available on every business page.

Troubleshooting

Actor cannot fetch a business page

Check that:

• The input is a valid Yelp business URL.
• The Actor has sufficient memory and timeout.
• Apify Proxy is available.
• The Yelp page still exists.
• The Actor logs do not show repeated challenge or access-denied responses.

Cookie refresh fails

Check the Actor logs for Chrome/Xvfb errors.

The cookie refresh requires:

• Google Chrome
• Xvfb
• Selenium/undetected-chromedriver dependencies
• Sufficient Actor memory

Some fields are empty

This can happen when:

• Yelp does not expose the information for that business.
• The relevant section is not present.
• Yelp changes its HTML structure.
• Apollo state is unavailable.
• The business page is served differently based on location or session.

Recommended Apify configuration

For normal scraping:

{
  "refreshCookieOnly": false
}

For a scheduled cookie warm-up:

{
  "refreshCookieOnly": true
}

The Actor is configured with a default run timeout of 900 seconds and 2048 MB memory.

License

Add the license that applies to your project before publishing if your project requires one.

Disclaimer

This project is an independent tool for extracting publicly accessible information from Yelp business pages. It is not an official Yelp product and has no affiliation with Yelp.

Users are responsible for ensuring that their use of the Actor complies with applicable laws, website terms, robots/access restrictions, and any relevant data-protection requirements.