local-business-list

Local Business List

Overview

This skill produces a CSV of local businesses in one category and area where every row has a website, an email that passed validation, a phone in E.164, a full address, and a named contact or owner where one exists, plus a call file when the user phones. A short report answers first (how many, what it cost, what to send first), then shows coverage, the funnel and the checks. When the tools are not connected or the user has not approved spend, the same skill delivers a Plan: measured free counts, decisions, a usage ceiling and a dated run schedule, with no invented counts.

The mistake it prevents is running one Google Maps scrape for "dentists in Houston", getting a slice of the city, paying for hundreds of rows with no email, and mailing info@ addresses that bounce. Here the database goes first because it is included in the plan and can be counted before anything is spent. Scrapes fill only the sub-areas where the database is thin, and nothing ships until it has a website, an email, a dedupe pass and a valid result.

When to Use

• "Get me every dentist in the Austin area with an email."
• "Roofers in Florida, owner name if possible."
• "Scrape Google Maps for HVAC companies in Phoenix."
• "Med spas in Miami, Fort Lauderdale and West Palm."
• An agency or SaaS selling to small businesses needs its first list in a new city.

Use a different skill when:

Prerequisites

Authoritative Foundations

Details and the file routing table: references/framework-notes.md.

Workflow

0. Pick the report mode

In Plan mode, run the free public counts now when web access is available (NPI Registry for health practices, a state license file for trades) and use the measured count as the planning number. Never write a per-sub-area count, a match rate, a validation split or a hit rate that was not measured: those cells wait for the run, and the Run Schedule says when they arrive. The cost is a ceiling (units on the measured base x catalog price), never an expected spend built on a guessed hit rate.

1. Define the search

Write the search card before any call:

Keyword recipes for 30 verticals, with exclusions and the Website Finder title for each, are in references/local-category-recipes.md.

2. Split the geography

A metro becomes a list of sub-cities; a state becomes its cities or counties; a dense city core becomes map boxes. Lists for 15 large metros and the box-grid method are in references/metro-split-and-geo-recipes.md. The Local Business Database accepts up to 2,000 entries in location, so one call can carry every sub-city; scrapes run one sub-city per run.

Read searched_as in the first database response. Every place should show a read_as value; a place marked not_found needs a different spelling or a ZIP code.

3. Count before pulling

Run query_local_business_database with limit: 1 four times, adding one filter each time, and read pagination.total:

Then run call C once per sub-city to build the coverage table: sub-city, all (A), with website and email (C), email coverage C / A.

For health practices (NPI Registry, free) and licensed trades in states that publish licensee files, also match the outside list against the pool per sub-area against a coverage target the user sets: at or above it needs no scrape, below it gets one Maps run, and a sub-area still below after that gets a ZIP-level Maps split. Query the NPI Registry one city at a time (200 per page, at most 1,200 per query) and count only records whose practice address is in the sub-area. The procedure and match keys are in references/coverage-segments-and-handoff.md section 1.

Show the user the gap sub-areas, the planned pull and the ceiling for each paid step (scrapes, lookups, validation). Wait for a go-ahead before any paid step.

4. Pull with cursor paging

check_wallet, then page call C (or B if you will find emails) with limit: 100, after: "0", then each pagination.next_after until null. Add excludeDelivered: true when the account has pulled this search before and only new businesses are wanted. Save each page with source = local_db and the query fingerprint in source_detail.

5. Fill gaps with Maps and Yelp

For each gap sub-city, run scrape_maps with 2-3 searchStringsArray terms, locationQuery set to the sub-city, and maxCrawledPlacesPerSearch capped at 60 or less, since Google documents 60 results as the most one text search returns (the worked example uses 40). The ceiling is terms x cap x $0.0099. The start response can include a local_business_database block with matches already in the database that the account does not have; pull those first. If a term returns at its cap, the sub-city holds more: split it (neighborhoods, ZIP codes) before raising the cap. When the sub-city's outside-list or database count is already above the per-term cap, run it by ZIP from the start, using the ZIPs on the outside list's practice addresses.

Use scrape_yelp (searchTerms, locations, searchLimit) for verticals where Yelp listings are dense (restaurants, beauty, home services, auto) and for any sub-city where Maps still looks thin. Ceiling: terms x locations x searchLimit x $0.0099. Use scrape_angi for home services by ZIP code when the category has an Angi slug.

Dedupe scrape rows against the pulled pool before paying for anything downstream.

6. Screen out chains and groups

When the user wants independents, run the screen before any paid lookup: brands over the user's chain line, a group list built at run time (the national groups' location pages for the state, the groups' own announcements of supported offices, names the user sends), homepage text naming a group ("supported by", "affiliated with") when web access is available, and NPI officials with corporate titles. Every dropped row records its signal in independence. A corporate call outcome adds the parent to the list. Signals and sources: references/coverage-segments-and-handoff.md section 1c.

7. Find owners and missing emails

When owner names are wanted, try the sources in order: the state entity registry where it lists principals (search the legal name from the NPI record or license file), the NPI authorized official titled Owner, President or DDS/DMD, then a database or Website Finder contact titled Owner. For health practices, confirm the name against that person's own NPI individual record. A registered agent or office manager never goes in owner_name. Conflict rule and the owner_key that sends one email per owner while the call file keeps every location: references/coverage-segments-and-handoff.md section 1b.

Then fill missing emails:

Leave autoValidateEmails off; every email is validated once in step 9.

8. Filter, normalize, dedupe, suppress

Keep rows with a website and an email. Normalize per references/list-quality-standard.md section 3: phone to E.164, domain to registrable form (blank for facebook.com, yelp.com and other platform hosts), ZIP as text, business_name_key. Dedupe with the local-business keys: domain, then phone, then name key plus postal code, then name key plus street. Decide the chain policy with the user: one row per location (key on phone) or one row per brand (key on domain). Two locations that share one email always collapse to one row for email. Apply suppression: current customers, open deals, unsubscribes, past bounces, and anyone contacted inside the cool-off window the user sets.

9. Validate and route

Send every unique email to validate_emails. valid rows form the main CSV. Role addresses (info@, office@, contact@) stay in the main file on a local list, since the owner often reads them. The validator's valid_catch_all result maps to the catch_all bucket: a separate file in its own campaign, paused when its hard bounces pass 2% over 200 sends (Alex Berman's 2% line, Instantly's 200-send window). unknown is re-validated once. invalid and disposable are removed and added to the blocklist.

10. Segment, sample and hand off

1. Tag every row with segment from fields already pulled: named_contact or role_inbox, plus a situation tag that matches the offer (low_rating, few_reviews, high_rated_busy, new_license, multi_location). Rules and the offer each tag fits: references/coverage-segments-and-handoff.md section 2. The first campaign sends named_contact rows in the offer's segment first.
2. Open a random sample of main-file rows (size and pass line are the user's settings; the worked example uses 20) and record the result in the Checks table: category fit, open at the listed address, website is the business's own domain, phone E.164, owner name confirmed when owners were wanted, each as "N of M". Misses that repeat on one check mean the filter or normalizer is wrong: fix it and re-run, rather than patching rows.
3. Map columns for the sequencer and, when the user calls, the dialer with the outcome field set up before the first call block (section 3 and 4 of the same reference). Outcomes feed back: the sub-area with the highest wrong_number plus closed share gets a fresh Maps pull.
4. Write the CSV with the columns in Output Format, the catch-all file, the call file if the user phones, and the report from the template for the mode. Run scripts/check-output.py.

ScraperCity Implementation

Calls

Count (call C):

{"keyword": ["dentist", "dental clinic", "cosmetic dentist", "pediatric dentist"],
 "location": ["Austin TX", "Round Rock TX", "Cedar Park TX", "Georgetown TX", "Pflugerville TX",
              "Leander TX", "Kyle TX", "Buda TX", "San Marcos TX", "Lakeway TX"],
 "notCategory": ["Dental laboratory", "Dental supply store"],
 "hasWebsite": true, "hasEmail": true, "limit": 1}

Pull: the same body with "limit": 100, "after": "0", then pagination.next_after. CLI: npx scrapercity db-local with the keyword, location (semicolon separated), has-website and has-email flags. REST: GET or POST /api/v1/database/local-businesses; use POST for long location lists.

Maps for one gap sub-city:

{"searchStringsArray": ["dentist", "dental clinic"], "locationQuery": "Kyle, TX", "maxCrawledPlacesPerSearch": 40}

Yelp:

{"searchTerms": ["dentist"], "locations": ["San Marcos, TX", "Georgetown, TX"], "searchLimit": 30}

Website Finder for Maps rows with a website and no email:

{"domains": ["kylefamilydental.example", "budasmiles.example"], "jobTitle": "Office Manager", "autoValidateEmails": false}

Worked cost estimate

Dentists in the Austin metro, 10 sub-cities, database first, Maps in 4 thin sub-cities, Yelp in 2:

The ceiling shown before the scrapes was $3.17 (Maps) + $0.59 (Yelp) + $1.37 (validation of up to 810 emails) = $5.13, shown before any paid step, so it waited for a yes. The Website Finder ceiling ($1.30 for 26 domains) was shown and approved after the scrapes, once the domain count was known. Cost per send-ready business in the example: $4.78 / 545 = $0.009.

Error handling

Output Format

Files:

1. local-[category]-[area]-[date].csv: valid emails only, one row per owner when owners were found (per inbox otherwise), with the business columns from references/list-quality-standard.md section 2b plus subtype, independence, and owner_name, owner_check, owner_key when owners were wanted.
2. -catch-all.csv, and -call-file.csv when the user phones: one row per location phone, same columns plus an empty call_outcome.
3. The report, from templates/output-template.md (Delivered) or templates/plan-template.md (Plan).

Report sections, in order:

Rules for what the reader gets:

• Answer first. Short Answer is the first section: how many, what it costs, how it is checked, what to send first. Cost leads with the all-in figure for the user's plan status (plan price plus usage above its credit), then the usage ceiling, then per-run prices for gap scrapes. Hand work is listed with its row counts, never with invented hours.
• One status line. "Status: Plan" or "Status: Delivered" once under the title says what ran and when. It is not repeated in sections, table titles or notes.
• Each fact once. Coverage shows one row per gap sub-area plus one row for the rest; the funnel is the only place counts flow; Cost carries the source results (new rows and cost per new); Output Columns carries the example values, so there is no sample-row table; the hand-check results sit in the Checks table.
• Inputs a person chooses, not API detail. Category words, areas, exclusions and filters in plain words. No tool ids, parameter names, endpoints, request bodies, internal file paths or names of other builds. A handoff names the product and the step ("Mobile Finder on owner emails, $0.25 per number found").
• Every threshold carries its source or says it is the user's setting. Example: "pause at 2% hard bounces over 200 sends (Alex Berman's line, Instantly's 200-send window)"; "coverage target: yours". Segment cutoffs are the user's.
• Plan mode has no invented numbers. Only measured counts (with the date and source), catalog prices and arithmetic on them. No decimal shares, no projected funnel or validation split.
• Every date the user acts on is written. Plan: a Run Schedule with dates and who approves each paid step. Delivered: dated Next Steps with the sequencer and dialer import columns and the call outcome values.
• Only the job. Legal commentary, a frameworks list, a self-grading checklist and vendor pitches all stay out.

Quality Check

• The mode matches what ran: Delivered only after the tools ran and the user approved; otherwise Plan.
• Plan: every count is measured (source and date) or left to a dated step; the cost is a ceiling on catalog prices; decisions list every user setting.
• Delivered: count calls A to D ran before any pull or scrape, coverage rows sum to the total, and scrapes ran only in gap sub-areas with a stated cap.
• NPI queries ran one city at a time, none at the 1,200-record limit; sub-areas above the per-term Maps cap ran by ZIP.
• The independence screen ran before any paid lookup, and every dropped row names its signal.
• Every owner_name comes from a source that names the owner; conflicts are marked.
• Every main-file row has a website, a domain (or a noted platform host), email_status = valid and an E.164 phone; the funnel and validation buckets reconcile; catch-all rows are in their own file.
• Segments list each tag with its rule and send order (and counts when Delivered).
• Every threshold in the report names its source or the user.
• check_wallet ran and every paid step had a go-ahead.
• scripts/check-output.py report.md prints PASS.

Common Pitfalls

Execution Artifacts

Related Skills

• tam-builder to size every business in the market first.
• scrapercity-local-business-database for every database parameter.
• cold-email-list to carry this CSV into a sequencer with copy columns.
• email-list-cleaner to re-validate the list before a later re-launch.
• decision-maker-finder for named managers at multi-location groups.
• mobile-appender for owner mobiles with line-type and suppression checks.
• cold-email-copywriting for the first email to one sub-segment.