Local Business Lead Enrichment Engine

Find local businesses via the Google Places API and enrich each lead with Yelp ratings in a single run. One search in, one merged, sales-ready dataset out.

What it does

This actor turns a simple query like "dentists in Austin, TX" into an enriched lead list. Each business comes back with:

• Core info (from Google Places): name, address, city, state, ZIP, phone, website, opening hours, categories, and Google Place ID
• Google ratings: rating + review count
• Yelp ratings (optional): rating, review count, and Yelp business URL, matched via the official Yelp Fusion API

Both data sources are official, key-based APIs — you bring the keys, the actor does the searching, matching, and joining.

When to use it

• Sales teams building prospect lists for outbound
• Marketing agencies researching a new territory
• Lead generation services building B2B databases
• Local SEO consultants identifying businesses needing online-presence help

Required setup

Google Places API key (required)

The actor uses the Google Places API (New) — Text Search and Place Details. You must provide your own key:

1. Go to Google Cloud Console
2. Create a project (or use an existing one)
3. Enable the Places API (New)
4. Create an API key (APIs & Services → Credentials → Create → API Key)
5. (Recommended) Restrict the key to the Places API

Google bills its own per-request usage fees for Text Search and Place Details, separate from your Apify usage. Check Google's current Places API pricing and free-tier credit before running large searches.

If the Google API key is missing, the run exits cleanly in demo mode and pushes a single guidance row (it does not fail).

Yelp Fusion API key (optional)

For Yelp rating enrichment:

1. Go to Yelp Developers
2. Create an app and copy the API key
3. Provide it as yelpApiKey and leave enrichYelp enabled

If you don't provide a Yelp key (or set enrichYelp to false), Yelp enrichment is silently skipped and yelp* fields come back null.

Input parameters

Field	Type	Required	Default	Description
query	string	yes	dentists	Business type (e.g., "plumbers", "coffee shops")
location	string	yes	Austin, TX	City, state, or address to search around
googleApiKey	secret string	required for real results	—	Google Places API (New) key. Without it the run returns demo-mode guidance.
maxResults	integer	no	50	Max businesses to return (1–200)
enrichYelp	boolean	no	true	Cross-reference each business with the Yelp Fusion API
yelpApiKey	secret string	required if enrichYelp is on	—	Yelp Fusion API key

Output format

Each enriched lead:

{
  "name": "Smith Family Dentistry",
  "address": "123 Main St, Austin, TX 78701, USA",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "phone": "(512) 555-1234",
  "website": "https://smithfamilydental.com",
  "googlePlaceId": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "googleRating": 4.7,
  "googleReviewCount": 234,
  "googleCategories": ["dentist", "health"],
  "hours": {
    "monday": "8:00 AM – 5:00 PM",
    "tuesday": "8:00 AM – 5:00 PM"
  },
  "yelpRating": 4.5,
  "yelpReviewCount": 89,
  "yelpUrl": "https://www.yelp.com/biz/smith-family-dentistry",
  "bbbRating": null,
  "bbbAccredited": null,
  "emails": [],
  "socialMedia": {},
  "enrichedAt": "2026-07-11T12:30:00.000Z"
}

Fields that couldn't be enriched come back null (ratings) or empty (arrays/objects).

Reserved fields: bbbRating, bbbAccredited, emails, and socialMedia are retained in the output shape for backward compatibility but are not populated in the current version — they are always null/empty. BBB lookup and website email/social scraping were removed in v1.7.

Status rows

On demo-mode, no-result, and error runs the actor pushes a single status row instead of leads, so the dataset is never empty. These rows carry a status field (demo_mode | no_results | api_error | error) plus a human-readable message. A per-run summary (totals, sources used, any per-lead errors) is also written to the key-value store under OUTPUT.

How enrichment works

1. Google Places Text Search — finds up to maxResults businesses matching query + location
2. Google Places Details — fetches phone, website, hours, categories, and address components for each place
3. Yelp match (if enabled and a key is provided) — tries a phone-number match first (most accurate), then falls back to a name + location search and picks the best name-similarity match

Businesses are processed in small concurrent batches to respect Yelp API rate limits. A failure enriching one business is caught and logged; it never aborts the whole run.

Pricing model

Pay-per-result: each row pushed to the dataset is one billable result. Google's own Places API usage fees are billed separately by Google against your API key.

Example inputs

Basic: dentists in Austin (Google + Yelp)

{
  "query": "dentists",
  "location": "Austin, TX",
  "maxResults": 50,
  "googleApiKey": "YOUR_GOOGLE_KEY",
  "enrichYelp": true,
  "yelpApiKey": "YOUR_YELP_KEY"
}

Fast mode (Google only)

{
  "query": "coffee shops",
  "location": "Seattle, WA",
  "maxResults": 100,
  "googleApiKey": "YOUR_GOOGLE_KEY",
  "enrichYelp": false
}

Limitations

• Two data sources only. Enrichment is Google Places (New) + the Yelp Fusion API. There is no BBB lookup, no website email scraping, and no social-media extraction in this version (removed in v1.7). The bbbRating, bbbAccredited, emails, and socialMedia fields are always null/empty.
• Bring your own keys. A Google Places API key is required for real results; a Yelp Fusion key is required for Yelp enrichment. Google/Yelp charge their own usage fees and enforce their own quotas against your keys.
• Google result cap. Google Places Text Search paginates 20 results per page. Very large maxResults values are bounded by what Google returns for the query; you may receive fewer than requested.
• Yelp matching is best-effort. Phone matches are reliable when a business has a registered phone; the name + location fallback can occasionally mismatch or find no match, in which case yelp* fields are null.
• Missing fields are normal. Businesses without a website, phone, or rating on Google will have those fields null. Yelp rate limits (HTTP 429) or an expired/invalid key cause Yelp fields to be skipped for that business.
• Graceful, non-failing behavior. Missing inputs, zero search results, an all-failed enrichment batch, and upstream API errors do not crash the run — the actor pushes a structured status row and exits successfully. This keeps runs "healthy" but means a status row in the dataset is expected on those paths.
• US / English-oriented. Phone normalization defaults to +1 for 10-digit numbers, and address parsing assumes US-style locality/administrative-area components.

Version history

• v1.8 — Accurate dataset schema (real output shape), demo/no-result/error status rows, empty-dataset guards
• v1.7 — Removed BBB lookup and website email/social scraping; Google Places + Yelp only
• v1.2 — Added output schema + dataset views for clickable results
• v1.1 — Logo + metadata
• v1.0 — Initial release