Yelp Review + Owner-Response Incident Monitor

Monitor Yelp reviews for new 1–2 star incidents, unanswered complaints, slow owner responses, rating drops, complaint patterns, and review spikes. Stateful monitoring returns only meaningful changes since the previous run.

This Actor is a reputation monitor, not a generic Yelp data dump. Schedule it hourly or daily and connect its event dataset to Apify webhooks, APIs, Make, Zapier, or your own incident workflow.

What you can monitor

• Reputation monitoring: detect newly published damaging reviews without reprocessing the same history as new incidents.
• Owner-response SLA: identify low-star reviews that remain unanswered beyond your chosen threshold and detect replies added later.
• Agency and multi-location monitoring: check many client or franchise pages in one fault-tolerant run.
• Competitor monitoring: watch public rating, review-count, and complaint changes on competitor Yelp pages.
• Complaint intelligence: tag repeated service, wait-time, price, quality, cleanliness, delivery, and order problems without an AI key.
• Scheduled monitoring: use Apify Schedules to run the same input hourly or daily; monitoring state stays in the default Key-Value Store.

Example input

{
  "businesses": [
    {
      "name": "Example Restaurant",
      "url": "https://www.yelp.com/biz/example-restaurant"
    }
  ],
  "maxReviewsPerBusiness": 100,
  "onlyChanges": true,
  "maximumIncidentRating": 2,
  "unansweredAfterHours": 48,
  "detectSignals": true,
  "includeReviewText": true,
  "monitorOwnerResponses": true,
  "stateStoreName": "yelp-reputation-monitor-state"
}

encBizId is an optional advanced field on a business. It skips the one business-page resolution request when you already know the ID publicly embedded by Yelp. The URL remains the stable monitoring key. Supplying it is the most reliable and least expensive production mode because Yelp may withhold business-page HTML even from Residential proxy sessions.

Event output

With onlyChanges: true, Dataset rows are changes and incidents rather than a giant raw review dump:

{
  "eventId": "evt_6f2c84d1c19f7c11e62feebdc91f0a9a",
  "eventType": "UNANSWERED_NEGATIVE_REVIEW",
  "severity": "HIGH",
  "baselineRun": false,
  "businessName": "Example Restaurant",
  "businessUrl": "https://www.yelp.com/biz/example-restaurant",
  "reviewId": "public-yelp-review-id",
  "reviewUrl": "https://www.yelp.com/biz/example-restaurant?hrid=public-yelp-review-id",
  "rating": 1,
  "reviewDate": "2026-08-26T03:44:25.000Z",
  "reviewText": "The manager was rude and we waited almost an hour.",
  "ownerResponseExists": false,
  "responseDelayHours": null,
  "signals": ["SERVICE_COMPLAINT", "WAIT_TIME_COMPLAINT"],
  "detectedAt": "2026-08-29T09:00:00.000Z"
}

Every event has a deterministic ID where the source transition permits it. The Dataset Console view puts event type, severity, business, rating, response status, signals, and detection time first.

Incidents

Event	Trigger
NEW_NEGATIVE_REVIEW	A newly discovered review is at or below maximumIncidentRating.
NEW_REVIEW	A newly discovered review is above the negative threshold.
OWNER_RESPONSE_ADDED	A known review changed from no public owner response to a response.
UNANSWERED_NEGATIVE_REVIEW	A negative review crossed unansweredAfterHours without a response. Emitted once.
SLOW_OWNER_RESPONSE	A newly added response has reliable timestamps and exceeded the SLA.
RATING_DROP / RATING_INCREASE	Yelp's public aggregate rating changed between successful runs.
REVIEW_COUNT_CHANGED	Yelp's public aggregate review count changed.
REVIEW_VELOCITY_SPIKE	New reviews are at least max(5, 3 × recent run average) after two comparison runs.
NEGATIVE_REVIEW_SPIKE	The same heuristic applied only to reviews at or below the negative threshold.

Severity is deterministic. A new 1-star review, a cleanliness/safety signal, or at least three new negative reviews in one run is CRITICAL; negative SLA breaches and rating drops are HIGH; slow replies and general velocity spikes are MEDIUM; informational changes are LOW.

Complaint signals

The classifier matches curated phrases with positive-context and negation safeguards. Its confidence field is a heuristic confidence score, not a machine-learning probability. Evidence snippets are deliberately short. No OpenAI, Anthropic, Gemini, embeddings, or external AI service is used.

Supported signals:

• SERVICE_COMPLAINT
• WAIT_TIME_COMPLAINT
• PRICE_COMPLAINT
• QUALITY_COMPLAINT
• CLEANLINESS_COMPLAINT
• DELIVERY_OR_ORDER_COMPLAINT

Baseline and recurring state

The first successful check for each URL creates a baseline in MONITORING_STATE_V1 in the named Key-Value Store selected by stateStoreName. A named store is essential because each Actor run receives a fresh default store. Use a distinct name when separate Tasks must keep independent baselines.

• With onlyChanges: true, the baseline is quiet: historical reviews are stored but are not described as newly occurring incidents.
• Historical negative reviews already older than the SLA are marked as baseline-known, so they do not suddenly fire on run two.
• With onlyChanges: false, current records are emitted as REVIEW_SNAPSHOT rows clearly marked baselineRun: true on the first run.
• A later NO RESPONSE → RESPONSE EXISTS transition emits OWNER_RESPONSE_ADDED.
• Only successful business checks replace that business's state. One failed URL does not erase or advance its last known-good baseline.

To start a genuinely new baseline, use a new Key-Value Store or delete the MONITORING_STATE_V1 record intentionally.

Efficient recurring checks

Reviews are requested newest-first in 10-review cursor pages. A recurring check stops at the first of:

• maxReviewsPerBusiness;
• the optional date cutoff;
• Yelp's end-of-feed cursor; or
• 20 consecutive review IDs already present in state.

This keeps a business with thousands of historical reviews inexpensive after its baseline. The PPE-ready commercial unit is one successfully persisted business_checked event; Store pricing must be configured in Apify Console before charging is activated.

OUTPUT summary

The run's default Key-Value Store record OUTPUT includes run status, baseline status, the persistent state-store name, business success/failure counts, reviews and pages fetched, each major incident count, complaint-signal totals, timestamps, and actionable per-business failures. If every business fails, the Actor writes OUTPUT and fails the run instead of silently reporting an empty success.

Extraction method and public-data scope

The Actor reads only information publicly displayed by Yelp:

1. One HTTP request resolves a Yelp /biz/ URL through the page's public yelp-biz-id metadata. If Yelp challenges that lightweight request, the Actor retries the public page in a fingerprinted browser with fresh proxy sessions.
2. Yelp's logged-out frontend review feed is called directly over HTTP with GetBusinessReviewFeed.
3. Structured review IDs, rating, timestamps, full public text, minimal public reviewer display fields, aggregate rating/count, and bizUserPublicReply are normalized.

It does not log in, solve CAPTCHAs, access a Yelp for Business inbox, write reviews, use private user data, or attempt to deanonymize reviewers. Reviewer metadata is intentionally limited to the public display name and location needed for stable fallback IDs and human-readable incidents.

Proxy and access limitations

Yelp actively challenges automated and datacenter traffic. The input defaults to an Apify Residential US proxy because URL-to-business-ID resolution is otherwise frequently blocked. The structured review feed is usually cheaper and more permissive, but it can also be rate-limited.

• A residential proxy is recommended for Store and production runs; its usage is billed by Apify.
• No hard-coded proxy credentials or external API secrets are required.
• URL-only inputs depend on Yelp allowing the one public business-page resolution request. If all rotated browser sessions receive a DataDome/challenge shell, supply that page's public encBizId; review and owner-response monitoring then runs through the lightweight structured feed.
• Browser fallback rotates up to three isolated proxy sessions. If Yelp continues to serve a challenge, redirects away from /biz/, changes its persisted GraphQL document, or changes the response shape, that business fails with a diagnostic error.
• The Actor does not bypass a CAPTCHA or retry through an authentication wall.
• Public owner-response dates are nullable. Response-delay and slow-response events are emitted only when both dates parse reliably.
• Owner-response transitions can only be detected for reviews inside the configured recent-review inspection window. Increase maxReviewsPerBusiness if businesses commonly reply to older reviews.
• Yelp may alter or remove reviews between runs. The MVP detects additions and response transitions; it does not claim that an absent review was deleted when the recent-page cap may simply have excluded it.
• Business category and address metadata come from the permitted business page and can be null when Yelp omits it. Aggregate rating and count are taken from the structured review feed when available.

Review Yelp's terms and applicable law for your use case. You are responsible for having a lawful purpose for processing public review data.

Scheduling

Create an Apify Task with your input, run it once to establish the baseline, then create an Apify Schedule for that Task. Use the Dataset API or a webhook on successful runs to forward incident rows. Keep the same stateStoreName on every scheduled run; the Actor opens that named store explicitly, while each run still writes its own default OUTPUT record.

Local development

npm install
npm run build
npm test
npm run smoke:live

The live smoke command uses public Yelp IDs paired with their business URLs so it can validate review pagination without the challenged alias-resolution request. Full URL-only validation should be run on Apify with the default Residential proxy before Store publication.