Nimbryxo Studio
Actors/Yelp Business Search & Review Scraper

Yelp Business Search & Review Scraper

Search Yelp by keyword and location, or scrape specific business pages directly, to collect business details, ratings, categories, contact details, and customer reviews.

Open on ApifyGitHub source

Input schema

Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.

FieldTypeRequiredDescription
modestringrequiredSearch Yelp by keyword and location, or look up specific business URLs, aliases, or 22-character business IDs.
searchQuerystringoptionalKeyword to search for in mode=search, for example 'pizza', 'plumber', or 'coffee shop'.
locationstringoptionalCity, neighborhood, or ZIP code to search in mode=search, for example 'New York, NY' or '10012'.
Show all input fields
FieldTypeRequiredDescription
modestringrequiredSearch Yelp by keyword and location, or look up specific business URLs, aliases, or 22-character business IDs.
searchQuerystringoptionalKeyword to search for in mode=search, for example 'pizza', 'plumber', or 'coffee shop'.
locationstringoptionalCity, neighborhood, or ZIP code to search in mode=search, for example 'New York, NY' or '10012'.
startUrlsarrayoptionalIn mode=search, paste Yelp search URLs. In mode=direct, paste business URLs, aliases, or 22-character business IDs.
categoriesarrayoptionalOptional Yelp category aliases or names used to narrow search results, for example 'pizza', 'coffee', or 'home_services'. They are combined with the search query.
sortBystringoptionalOrdering for mode=search result pages.
pricearrayoptionalOptional price levels for mode=search. Leave empty for every price level.
minRatingnumberoptionalDrop businesses rated below this value. Set to 0 to keep every rating.
maxItemsintegeroptionalHard cap on business records in the dataset. Search is limited to Yelp's 240-result ceiling per query.
maxReviewsPerBusinessintegeroptionalMaximum reviews collected for each business. Reviews are paged 49 at a time from Yelp's public review feed.
includeReviewsbooleanoptionalTurn off to collect only business profiles and skip the review feed.
reviewSortstringoptionalOrdering applied to each business's review feed.
reviewRatingsarrayoptionalOnly collect reviews with these star ratings. Choose one or more values.
reviewLanguagestringoptionalLanguage for the review feed. Choose 'all' to page through every language Yelp reports for the business.
proxyConfigurationobjectoptionalOptional. The actor automatically uses Apify Proxy when Yelp blocks a request; add a country or custom proxy here only when you need a specific route.

Download the published input schema

View complete JSON
{
  "description": "Choose keyword search or direct business lookup, then set review depth and filters.",
  "properties": {
    "categories": {
      "default": [],
      "description": "Optional Yelp category aliases or names used to narrow search results, for example 'pizza', 'coffee', or 'home_services'. They are combined with the search query.",
      "editor": "stringList",
      "prefill": [],
      "title": "Categories",
      "type": "array"
    },
    "includeReviews": {
      "default": true,
      "description": "Turn off to collect only business profiles and skip the review feed.",
      "prefill": true,
      "title": "Include reviews",
      "type": "boolean"
    },
    "location": {
      "default": "New York, NY",
      "description": "City, neighborhood, or ZIP code to search in mode=search, for example 'New York, NY' or '10012'.",
      "editor": "textfield",
      "prefill": "",
      "title": "Location",
      "type": "string"
    },
    "maxItems": {
      "default": 50,
      "description": "Hard cap on business records in the dataset. Search is limited to Yelp's 240-result ceiling per query.",
      "maximum": 500,
      "minimum": 1,
      "prefill": 1,
      "title": "Maximum businesses",
      "type": "integer"
    },
    "maxReviewsPerBusiness": {
      "default": 20,
      "description": "Maximum reviews collected for each business. Reviews are paged 49 at a time from Yelp's public review feed.",
      "maximum": 1000,
      "minimum": 1,
      "prefill": 5,
      "title": "Reviews per business",
      "type": "integer"
    },
    "minRating": {
      "default": 0,
      "description": "Drop businesses rated below this value. Set to 0 to keep every rating.",
      "maximum": 5,
      "minimum": 0,
      "prefill": 0,
      "title": "Minimum rating",
      "type": "number"
    },
    "mode": {
      "default": "search",
      "description": "Search Yelp by keyword and location, or look up specific business URLs, aliases, or 22-character business IDs.",
      "editor": "select",
      "enum": [
        "search",
        "direct"
      ],
      "enumTitles": [
        "Search Yelp by keyword and location",
        "Scrape specific business URLs or IDs"
      ],
      "prefill": "direct",
      "title": "Mode",
      "type": "string"
    },
    "price": {
      "default": [],
      "description": "Optional price levels for mode=search. Leave empty for every price level.",
      "editor": "select",
      "items": {
        "enum": [
          "$",
          "$$",
          "$$$",
          "$$$$"
        ],
        "type": "string"
      },
      "prefill": [],
      "title": "Price levels",
      "type": "array"
    },
    "proxyConfiguration": {
      "description": "Optional. The actor automatically uses Apify Proxy when Yelp blocks a request; add a country or custom proxy here only when you need a specific route.",
      "editor": "proxy",
      "title": "Proxy configuration",
      "type": "object"
    },
    "reviewLanguage": {
      "default": "en",
      "description": "Language for the review feed. Choose 'all' to page through every language Yelp reports for the business.",
      "editor": "select",
      "enum": [
        "all",
        "en",
        "es",
        "fr",
        "de",
        "it",
        "pt",
        "nl",
        "sv",
        "da",
        "no",
        "fi",
        "pl",
        "cs",
        "el",
        "tr",
        "ru",
        "uk",
        "he",
        "ar",
        "hi",
        "bn",
        "ta",
        "th",
        "vi",
        "id",
        "ms",
        "tl",
        "zh",
        "ja",
        "ko"
      ],
      "enumTitles": [
        "All available languages",
        "English",
        "Spanish",
        "French",
        "German",
        "Italian",
        "Portuguese",
        "Dutch",
        "Swedish",
        "Danish",
        "Norwegian",
        "Finnish",
        "Polish",
        "Czech",
        "Greek",
        "Turkish",
        "Russian",
        "Ukrainian",
        "Hebrew",
        "Arabic",
        "Hindi",
        "Bengali",
        "Tamil",
        "Thai",
        "Vietnamese",
        "Indonesian",
        "Malay",
        "Tagalog",
        "Chinese",
        "Japanese",
        "Korean"
      ],
      "prefill": "en",
      "title": "Review language",
      "type": "string"
    },
    "reviewRatings": {
      "default": [
        "5",
        "4",
        "3",
        "2",
        "1"
      ],
      "description": "Only collect reviews with these star ratings. Choose one or more values.",
      "editor": "select",
      "items": {
        "enum": [
          "1",
          "2",
          "3",
          "4",
          "5"
        ],
        "type": "string"
      },
      "prefill": [
        "5",
        "4",
        "3",
        "2",
        "1"
      ],
      "title": "Review star ratings",
      "type": "array"
    },
    "reviewSort": {
      "default": "DATE_DESC",
      "description": "Ordering applied to each business's review feed.",
      "editor": "select",
      "enum": [
        "DATE_DESC",
        "DATE_ASC",
        "RATING_DESC",
        "RATING_ASC",
        "RELEVANCE_DESC",
        "ELITES_DESC"
      ],
      "enumTitles": [
        "Newest first",
        "Oldest first",
        "Highest rated first",
        "Lowest rated first",
        "Most relevant first",
        "Elite reviewers first"
      ],
      "prefill": "DATE_DESC",
      "title": "Review order",
      "type": "string"
    },
    "searchQuery": {
      "default": "pizza",
      "description": "Keyword to search for in mode=search, for example 'pizza', 'plumber', or 'coffee shop'.",
      "editor": "textfield",
      "prefill": "",
      "title": "Search query",
      "type": "string"
    },
    "sortBy": {
      "default": "recommended",
      "description": "Ordering for mode=search result pages.",
      "editor": "select",
      "enum": [
        "recommended",
        "rating",
        "reviewCount"
      ],
      "enumTitles": [
        "Recommended",
        "Highest rated",
        "Most reviewed"
      ],
      "prefill": "recommended",
      "title": "Search result order",
      "type": "string"
    },
    "startUrls": {
      "default": [],
      "description": "In mode=search, paste Yelp search URLs. In mode=direct, paste business URLs, aliases, or 22-character business IDs.",
      "editor": "stringList",
      "prefill": [
        "https://www.yelp.com/biz/prince-street-pizza-new-york-2"
      ],
      "title": "Start URLs",
      "type": "array"
    }
  },
  "required": [
    "mode"
  ],
  "schemaVersion": 1,
  "title": "Yelp Scraper Input",
  "type": "object"
}

Output schema

Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.

FieldTypeRequiredDescription
businessesstringoptionalDataset containing Yelp business records, their reviews, and any status records produced during the run.

Download the published output schema

View complete JSON
{
  "actorOutputSchemaVersion": 1,
  "description": "Yelp business profiles with nested review rows, ratings, hours, contact details, and explicit status records for blocked or missing businesses.",
  "properties": {
    "businesses": {
      "description": "Dataset containing Yelp business records, their reviews, and any status records produced during the run.",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "Yelp Businesses & Reviews",
      "type": "string"
    }
  },
  "title": "Yelp Business Profiles & Review History Output"
}

Dataset schema

Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.

Download the published dataset schema

View complete JSON
{
  "actorSpecification": 1,
  "title": "Yelp Businesses & Reviews",
  "views": {
    "detailed": {
      "display": {
        "component": "table",
        "properties": {
          "address": {
            "format": "object",
            "label": "Address"
          },
          "alias": {
            "format": "text",
            "label": "Alias"
          },
          "businessId": {
            "format": "text",
            "label": "Business ID"
          },
          "categories": {
            "format": "array",
            "label": "Categories"
          },
          "city": {
            "format": "text",
            "label": "City"
          },
          "country": {
            "format": "text",
            "label": "Country"
          },
          "description": {
            "format": "text",
            "label": "Description"
          },
          "encId": {
            "format": "text",
            "label": "Yelp business ID"
          },
          "hours": {
            "format": "object",
            "label": "Hours"
          },
          "isClaimed": {
            "format": "boolean",
            "label": "Claimed"
          },
          "isClosed": {
            "format": "boolean",
            "label": "Closed"
          },
          "lat": {
            "format": "number",
            "label": "Latitude"
          },
          "lng": {
            "format": "number",
            "label": "Longitude"
          },
          "name": {
            "format": "text",
            "label": "Name"
          },
          "phone": {
            "format": "text",
            "label": "Phone"
          },
          "photos": {
            "format": "array",
            "label": "Photos"
          },
          "price": {
            "format": "text",
            "label": "Price"
          },
          "rating": {
            "format": "number",
            "label": "Rating"
          },
          "recordType": {
            "format": "text",
            "label": "Record type"
          },
          "reviewCount": {
            "format": "number",
            "label": "Reviews"
          },
          "reviews": {
            "format": "array",
            "label": "Reviews"
          },
          "reviewsTotal": {
            "format": "number",
            "label": "Reviews in feed"
          },
          "scrapedAt": {
            "format": "text",
            "label": "Scraped at"
          },
          "searchLocation": {
            "format": "text",
            "label": "Search location"
          },
          "searchQuery": {
            "format": "text",
            "label": "Search query"
          },
          "searchRank": {
            "format": "number",
            "label": "Search rank"
          },
          "sourceUrl": {
            "format": "link",
            "label": "Source URL"
          },
          "sponsored": {
            "format": "boolean",
            "label": "Sponsored"
          },
          "state": {
            "format": "text",
            "label": "State"
          },
          "url": {
            "format": "link",
            "label": "Yelp URL"
          },
          "website": {
            "format": "link",
            "label": "Website"
          },
          "zip": {
            "format": "text",
            "label": "ZIP"
          }
        }
      },
      "title": "Detailed",
      "transformation": {
        "fields": [
          "recordType",
          "businessId",
          "encId",
          "alias",
          "name",
          "categories",
          "address",
          "city",
          "state",
          "zip",
          "country",
          "lat",
          "lng",
          "rating",
          "reviewCount",
          "reviewsTotal",
          "price",
          "phone",
          "website",
          "hours",
          "photos",
          "url",
          "isClosed",
          "isClaimed",
          "description",
          "reviews",
          "searchRank",
          "sponsored",
          "searchQuery",
          "searchLocation",
          "sourceUrl",
          "scrapedAt"
        ]
      }
    },
    "overview": {
      "display": {
        "component": "table",
        "properties": {
          "categories": {
            "format": "array",
            "label": "Categories"
          },
          "city": {
            "format": "text",
            "label": "City"
          },
          "name": {
            "format": "text",
            "label": "Name"
          },
          "phone": {
            "format": "text",
            "label": "Phone"
          },
          "price": {
            "format": "text",
            "label": "Price"
          },
          "rating": {
            "format": "number",
            "label": "Rating"
          },
          "reviewCount": {
            "format": "number",
            "label": "Reviews"
          },
          "searchRank": {
            "format": "number",
            "label": "Search rank"
          },
          "sponsored": {
            "format": "boolean",
            "label": "Sponsored"
          },
          "state": {
            "format": "text",
            "label": "State"
          },
          "url": {
            "format": "link",
            "label": "Yelp URL"
          }
        }
      },
      "title": "Overview",
      "transformation": {
        "fields": [
          "name",
          "rating",
          "reviewCount",
          "price",
          "phone",
          "city",
          "state",
          "categories",
          "url",
          "searchRank",
          "sponsored"
        ]
      }
    }
  }
}

Key-value schema

Published key-value store definitions, when provided by this build.

This definition is not present in the default published build. See the published README for available documentation.

Published README

Read the full published documentation

Yelp Business Profiles & Review History Extractor

Yelp packs a lot into each business page: star ratings, price signals, weekly hours, photo galleries, contact details, and years of customer reviews. This actor turns that material into structured business records, with the review feed paged well beyond the handful of reviews Yelp shows by default.

What this actor does

  • Finds businesses by keyword and location, or by a Yelp search URL that already contains filters.
  • Looks up exact businesses from a Yelp business URL, a bare alias such as prince-street-pizza-new-york-2, or a 22-character Yelp business ID.
  • Pages each business's review feed up to your chosen limit, including reviewer names, Elite years, photos, reactions, and owner replies.
  • Adds search metadata so you can tell organic ranking from sponsored placement and remove duplicate cards.
  • Omits empty fields at every level. A business that does not publish a website, price level, or owner reply simply has no such key in its record.
  • Writes an explicit status record when a business is missing, a page is blocked, or Yelp changes the data contract, so an empty dataset is never mistaken for a successful scrape.

Output per business

Each business is one dataset row. Reviews are nested under reviews.

Field Description
recordType business for a business row, status for a run status row
businessId Yelp's 22-character business ID
encId The same stable Yelp business ID, kept as a separate field for joins
alias Yelp URL slug, e.g. prince-street-pizza-new-york-2
name Business name
categories Array of Yelp category titles
address Object with streetAddress, addressLocality, addressRegion, postalCode, addressCountry, and formatted when supplied
city City name
state State or region code
zip Postal code
country Two-letter country code
lat Latitude
lng Longitude
rating Average star rating (number)
reviewCount Review total shown on the business profile
reviewsTotal Reviews available in the public review feed, when it differs from reviewCount
price Price level such as $ or $$
phone Business phone number
website Business website URL
hours Weekly hours keyed by short day name, each value an array of time ranges
photos Business photo URLs, including the primary photo and gallery
url Yelp business page URL
isClosed Whether Yelp marks the business as closed
isClaimed Whether the business profile has been claimed
description Short business summary from Yelp
reviews Array of review objects, omitted when reviews are off or none are available
searchRank Organic position in the search results, when found through search
sponsored true when the business first appeared as a sponsored card
searchQuery Keyword that found the business
searchLocation Location used for that search
searchCategory Category filter used for that search
sourceUrl Search page or business URL the record came from
scrapedAt ISO timestamp for the record

Review objects contain:

Field Description
id Review ID
rating Star rating (1–5)
text Full review text
author Reviewer display name
authorId Reviewer ID
authorUrl Reviewer profile URL
authorLocation Reviewer location as shown by Yelp
authorReviewCount Number of reviews on the reviewer's profile
date Review date in UTC
dateLocal Review date in the business's local time
photos Review photo URLs
ownerReply Object with text, author, and date when the business replied
elite Whether the reviewer has an Elite year
eliteYear The Elite year Yelp displays
language Review language code
isFirstReview Whether Yelp marks this as the reviewer's first review
checkInCount Check-in count attached to the review
reactions Object with useful, funny, and cool counts

Status records

When something prevents a business or search page from being collected, the dataset receives a row with recordType: "status":

  • status is not_found, blocked, api_drift, no_results, or invalid_input.
  • message explains what happened.
  • sourceUrl and businessId are included when known.
  • scrapedAt records when the status was written.

Legacy compatibility keys are also present when they have values: directUrl (same as url), bizId (same as alias), aggregatedRating (rating as text), priceRange (same as price), and images (same as photos). Review rows also keep isUsefulCount, isFunnyCount, and isCoolCount beside the reactions object.

Status rows are separate from business rows, so filter on recordType before loading the business records.

Input

Field Type Default Description
mode string search search discovers businesses by keyword, category, or Yelp search URL; direct scrapes business URLs, aliases, or business IDs
searchQuery string pizza Keyword for mode=search
location string New York, NY City, neighborhood, or ZIP for mode=search
startUrls array [] Yelp search URLs in mode=search, or business URLs, aliases, and IDs in mode=direct
categories array [] Yelp category aliases or names used to narrow a search
sortBy string recommended Search ordering: recommended, rating, or reviewCount
price array [] Price levels $, $$, $$$, $$$$; empty keeps all
minRating number 0 Drop businesses rated below this value (0–5)
maxItems integer 50 Maximum business records (1–500)
maxReviewsPerBusiness integer 20 Maximum reviews per business (1–1000)
includeReviews boolean true Turn off to skip review collection
reviewSort string DATE_DESC DATE_DESC, DATE_ASC, RATING_DESC, RATING_ASC, RELEVANCE_DESC, or ELITES_DESC
reviewRatings array ["5","4","3","2","1"] Star ratings to include
reviewLanguage string en Review language code, or all to page every language Yelp reports
proxyConfiguration object Apify Proxy AUTO Optional routing choice; the actor automatically uses a working route when Yelp blocks a request

mode is the only required field. mode=search needs a query, category, or search URL. mode=direct needs at least one business URL, alias, or ID.

{
  "mode": "search",
  "searchQuery": "ramen",
  "location": "Seattle, WA",
  "price": ["$$", "$$$"],
  "minRating": 4,
  "maxItems": 20,
  "maxReviewsPerBusiness": 30,
  "reviewSort": "DATE_DESC",
  "reviewLanguage": "en"
}

Example: specific businesses by URL

{
  "mode": "direct",
  "startUrls": [
    "https://www.yelp.com/biz/prince-street-pizza-new-york-2",
    "https://www.yelp.com/biz/bar-lento-new-york"
  ],
  "maxItems": 2,
  "maxReviewsPerBusiness": 100,
  "reviewSort": "RATING_DESC",
  "reviewRatings": ["5", "4"]
}

Example: businesses and reviews in another language

{
  "mode": "direct",
  "startUrls": ["https://www.yelp.com/biz/bar-lento-new-york"],
  "maxReviewsPerBusiness": 50,
  "reviewLanguage": "all"
}

Example: profiles only

{
  "mode": "search",
  "searchQuery": "coffee",
  "location": "Portland, OR",
  "categories": ["coffee"],
  "includeReviews": false,
  "maxItems": 10
}

Use cases

  • Competitive benchmarking — compare ratings, review volume, price levels, and review themes across a set of local businesses.
  • Review monitoring — schedule runs against your own locations and watch new reviews, owner replies, and rating changes over time.
  • Lead research — collect phone numbers, websites, cities, and categories for businesses in a target market.
  • Voice-of-customer analysis — export hundreds of reviews per business with ratings, dates, languages, and reviewer context.
  • Location planning — map business density and quality across ZIP codes, neighborhoods, or categories.
  • Data enrichment — join Yelp business IDs, aliases, websites, and coordinates to an existing CRM or dataset.

FAQ

Do I need to supply a proxy? No. The actor starts with a direct request and automatically routes through Apify Proxy when Yelp blocks it. Leave proxyConfiguration at its default, or supply a country or custom proxy only when you need a specific route.

How many businesses can one search return? Yelp caps a single search at 240 businesses, displayed 10 at a time. maxItems can be as high as 500 across multiple queries or direct URLs, but each individual search stops at Yelp's 240-result ceiling.

How many reviews can I collect per business? Up to 1,000. The review feed is paged at 49 reviews per request, so a deep run uses several requests per business. Set maxReviewsPerBusiness lower for faster, cheaper runs.

Why is reviewsTotal sometimes lower than reviewCount? Yelp's profile count and its public review feed are not identical. The feed leaves out reviews Yelp does not recommend, so reviewsTotal can be slightly lower than the number shown on the page.

What does reviewLanguage: "all" do? The actor reads the language counts Yelp reports for the business and pages each language until the review limit is reached, de-duplicating by review ID. It can use several requests per business.

Why is a business or review field missing? Yelp does not publish every field for every business. Missing values are omitted rather than written as null, empty strings, or empty arrays.

What happens when Yelp changes its data format? The actor writes an api_drift status row with a message and the source URL, and the run status message reports the problem. It does not silently return an empty dataset.

Can I use a Yelp search URL with filters already in it? Yes. Put it in startUrls with mode=search; the actor keeps the URL's query parameters and pages from its existing start position.

Does this actor collect the reviews Yelp does not recommend? No. It collects the public review feed. Reviews outside that feed are not exposed, which is why the feed total can differ from the profile count.

Is this affiliated with Yelp? No. This is an independent third-party actor and is not endorsed by or affiliated with Yelp.

Python quickstart

Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.

Open the step-by-step Python guide →

Source build u5WBu7wbluwWdJnfh. Documentation is regenerated from the default published build; private drafts are not included.