scrapercity-local-business-database

ScraperCity Local Business Database

Overview

This skill turns "get me every [type of business] in [place]" into a Local Business Database search that matches the right businesses, a count check, a paging plan inside the 100,000 new businesses a day allowance, and segments by rating and review count so each segment gets a message that fits its situation.

The database is included with the Growth plan ($149/mo) and up. Every business returned is saved to the account. Only new businesses count toward the daily allowance; fetching one the account already has is free. Many records carry a named contact (first name, last name, job title, email, mobile).

The mistakes it prevents:

• Paying $0.0099 per business for a scrape_maps run when the database returns the same search in seconds at no extra cost.
• Sending one generic email to a 4.9-star clinic with 800 reviews and a 3.1-star clinic with 9 reviews.
• A 503 on "restaurants in Texas" because the search was never narrowed by city, category or map box.
• Reading an empty result as "no market" when searched_as shows the place was not found, or the lead_database block shows 100+ people for the same search.

When to Use

• "Find every dentist in Austin with an email."
• "Pull HVAC companies across Dallas-Fort Worth with under 50 reviews."
• "I have this Google Maps search URL, get me the businesses."
• "Give me med spas in Florida with a named owner."
• "Set up a daily feed of new roofers in Colorado."
• "Should I use the database or the Google Maps scraper?"

Use a different skill for nearby jobs:

Prerequisites

• Growth or Scale plan (run check_wallet and read plan.name). On Starter, use scrape_maps, scrape_yelp or scrape_angi.
• What the businesses do, in the words a person would type into Google Maps.
• Where: cities, states, postal codes, countries, or a map box.
• Contact needs: email, phone, website, named contact.
• Volume and cadence: one-off or daily.

Authoritative Foundations

Routing and detail: references/framework-notes.md.

Workflow

1. Confirm access, pick the tool

Run check_wallet. Then choose:

2. Write the search the way a person types it into Google Maps

• keyword: what the businesses do or are called, as an array: ["dentist"], ["thai restaurant", "sushi"]. Matches business names and categories, any keyword.
• location: as an array, up to 2,000 places, any match: ["Austin TX", "Round Rock TX", "78701"]. Cities, states, countries or postal codes.
• A place inside a keyword ("plumbers in Austin TX") is used as the location when location is empty.
• On the CLI, --location separates places with semicolons ("Houston, TX; Austin, TX") because a place has its own commas.

Read searched_as in the response. keywords[].categories shows which categories each keyword matched; matches_nothing: true means no business name or category has it, so rephrase. places[].read_as shows how each place was read; not_found means drop or respell it.

3. Add filters

Filters narrow the keyword and location search. Full list in references/filter-semantics.md:

• category (array, a word also finds categories that contain it: "restaurant" finds "Mexican restaurant"), notCategory (array).
• country (two-letter codes: ["US"]), state (string, commas for several, "TX" works), city (partial match), postalCode, box.
• query (business names and descriptions), title (business name, comma list, partial match).
• minRating, maxRating (1-5), minReviews, maxReviews.
• hasEmail, hasPhone, hasWebsite, hasContact (a named contact person).

4. Count check

Send the search with limit: 1. Read pagination.total, searched_as, and the one row.

A 503 means the search ran too long. Add a category, a city, a state or a postal code, or tile with box (step 6).

5. Segment by rating and reviews

Run one count per segment so the message can match it. Bands from the BrightLocal 2026 lines (4.0 stars, 4.5 stars, 20 reviews):

The five bands do not overlap; dedupe on business id anyway before sending. Opening angles per offer are in references/segmentation-and-tiling.md.

6. Tile big metros with box

box is "minLat,minLng,maxLat,maxLng". For a dense category in a big metro, split the metro into equal tiles, count each with limit: 1, and split any tile that returns 503 into four (half the step). The USGS figures convert a step in degrees to miles (0.25 degrees is about 17 by 14 miles at 38 degrees north). A box that cannot be read returns 400. Tiling recipe and a stdlib tile generator are in references/segmentation-and-tiling.md.

7. Pull with the cursor

limit: 100, after: "0", then pagination.next_after until null. For a feed of only new businesses, add excludeDelivered: true and keep page at 1 or use after. Long location lists or a long url go as POST /api/v1/database/local-businesses with a JSON body (query strings past about 16KB are refused).

8. QA and hand off

Check a random sample of rows (the size is your call; the example checks 20): category fits, address inside the place, rating and reviews inside the segment band, email or phone present as required. When misses share a pattern, add a notCategory or tighten the place before the bulk pull. Send emails to validate_emails before any campaign. For businesses without a named contact, run find_emails only where you have a person's name and the website domain.

ScraperCity Implementation

MCP

{
  "keyword": ["dentist"],
  "location": ["Austin TX", "Round Rock TX", "Cedar Park TX", "Pflugerville TX"],
  "notCategory": ["Dental laboratory", "Dental supply store"],
  "hasEmail": true,
  "minRating": 4.0,
  "limit": 1
}

CLI

npx scrapercity db-local --keyword "dentist" \
  --location "Austin, TX; Round Rock, TX; Cedar Park, TX; Pflugerville, TX" \
  --not-category "Dental laboratory" --has-email --min-rating 4 --limit 1

The CLI prints the total, the next cursor, how each place was read, keywords that match nothing, and the Lead Database fallback when the search finds nothing.

REST

curl -s -G "https://app.scrapercity.com/api/v1/database/local-businesses" \
  -H "Authorization: Bearer $SCRAPERCITY_API_KEY" \
  --data-urlencode "keyword=dentist" \
  --data-urlencode "location=Austin, TX" --data-urlencode "location=Round Rock, TX" \
  --data-urlencode "hasEmail=true" --data-urlencode "limit=100" --data-urlencode "after=0"

Repeat a key for several values. A Google Maps search URL goes in url; its keyword and place become the search, other parameters override, and the response adds search_translation (applied, approximated, not_supported). A URL with nothing usable returns 400.

Returned fields

title, category_name, address, city, state, postal_code, country_code, phone, website, emails, total_score (the rating), reviews_count, lat, lng, and when there is a named contact: contact_first_name, contact_last_name, contact_job_title, contact_email, contact_mobile. The response also carries pagination, rate_limit, and when relevant search_translation, searched_as, lead_database.

Database or scraper

Worked cost estimate

Dentists in the Austin metro, hasEmail: true. Count check returns 1,146. 412 have a named contact.

Email Finder bills only emails found, so the actual line is found emails x $0.05. The same 1,146 businesses through scrape_maps would cost 1,146 x $0.0099 = $11.35 before enrichment, without rating filters or named contacts. Show this table and get a go-ahead before any paid step.

Output Format

A local pull plan in Markdown from templates/output-template.md:

1. Request Summary: business type, places, contact needs, plan.
2. Search Spec: parameter, value, reason.
3. Count Check: total, searched_as notes, fallback block if any.
4. Segments: one row per rating and review segment with filters and count.
5. Pull Plan: paging, excludeDelivered, tiles, days.
6. Cost Estimate: $ table with total.
7. Sample QA and Next Steps.

Check it with python3 scripts/check-output.py plan.md.

• Each fact once; every call and script written out in full (no "..." values, no loop described in a comment); no counts or results marked assumed. If nothing has run, say so once at the top.
• What the reader receives is the deliverable only: no internal file paths, reference section numbers or runbook IDs; another skill is named only in a handoff line that tells the user what to run next; no tables of checks that were not run (one "Not checked:" line instead); and no repeated identical rows where one template plus a list will do.

Quality Check

• Every search row uses a parameter that exists in query_local_business_database.
• country values are two-letter codes.
• Every box reads as four numbers with min below max.
• A count from a limit: 1 call is shown before the bulk pull.
• Every segment states its rating band and review band, and the segments are deduped.
• excludeDelivered is never paired with page above 1.
• The cost table uses catalog prices, and paid spend is approved first.
• Sample QA reports on-target rows as "N / M", and any shared miss pattern is fixed in the search.

Common Pitfalls

Execution Artifacts

Related Skills

• local-business-list: the strategy layer for local lists.
• scrapercity-lead-database: when the lead_database fallback appears, or the target is a role.
• scrapercity-mcp, scrapercity-cli, scrapercity-api: access paths.
• email-list-cleaner, cold-email-list: validation and the send-ready file.
• cold-calling: phone outreach to the businesses.
• using-scrapercity-skills: router.