scrapercity 1.0.15 → 1.0.17

package/AGENT_DOCS.txt

@@ -50,8 +50,12 @@ apollo
 
 maps
   Body: { searchStringsArray: ["plumbers"], locationQuery: "Denver, CO", maxCrawledPlacesPerSearch: 500 }
-  Returns: { runId, datasetId, priceMicro }
+  Returns: { runId, datasetId, priceMicro, local_business_database? }
+    local_business_database (when there are matches): { matches, url, api } - businesses for the
+    same search already in the Local Business Database (ones you don't have), a dashboard link,
+    and the /api/v1/database/local-businesses call that returns them now.
   Cost: $0.01/place | Delivery: 5-30 min
+  To search by category and location without running a scrape, use the Local Business Database (below).
 
 email-validator
   Body: { emails: ["user@example.com", "test@company.com"] }
@@ -214,9 +218,39 @@ GET /api/v1/database/leads?title=CTO&country=United States&hasEmail=true&page=1&
   503: the search took too long to run. Narrow it (fewer titles or keywords, add a location
   or company size) and retry.
 
-GET /api/v1/database/local-businesses?...
+GET /api/v1/database/local-businesses?category=Dentist&country=US&hasContact=true&limit=100
+  Local businesses ($149/mo plan and up, 100k new businesses/day), same pattern as above.
+  Search the way you would on Google Maps:
+  keyword=thai restaurant (repeat for several; matches business names and categories, any keyword;
+           a place inside a keyword, "plumbers in Austin TX", is the location when none is sent)
+  location=Houston TX (repeat for several, up to 2,000: cities, states, countries or postal codes)
+           The response adds searched_as: { keywords: [{ text, words, categories, matches_nothing }],
+           places: [{ text, read_as, kind, not_found? }] }. A search that finds nothing adds
+           lead_database: { count, read_as, filters, dashboard_url } when the Lead Database has 100+
+           people for it (keywords read as job title or company keywords, whichever has more).
+  Filters: category (repeat for several), country (two-letter code), state, city, postalCode,
+  query (business name and description), title (business name, comma separated for several),
+  minRating, maxRating, minReviews, maxReviews,
+  hasEmail, hasPhone, hasWebsite, hasContact (only businesses with a named contact person).
+  box=minLat,minLng,maxLat,maxLng: only businesses inside that map area (a box that can't be
+           read returns 400).
+  Exclusions: notCategory (repeat for several)
+  url=<Google Maps search URL>: use that search's keyword and place (other params override).
+           The response adds search_translation: { applied, approximated, not_supported }.
+           A URL with nothing the database can use returns 400.
+  POST /api/v1/database/local-businesses with a JSON body takes the same parameters (arrays as
+           JSON arrays). Use it for a long url or long lists: a query string over ~16KB is refused.
+  Optional: excludeDelivered=true, after=<id> (as above).
+  Returns: { data: [...businesses], pagination: { page, limit, total, totalPages, has_more, next_after },
+             rate_limit, search_translation?, searched_as?, lead_database? }
+  Business fields include title, category_name, address, city, state, postal_code, country_code,
+  phone, website, emails, total_score, reviews_count, lat, lng, and contact_first_name,
+  contact_last_name, contact_job_title, contact_email, contact_mobile when there is a named contact.
+  503: the search took too long to run. Narrow it (add a category, a city, a state or a postal
+  code) and retry.
+
 GET /api/v1/database/ecommerce?...
-  Same pattern (including excludeDelivered and after), different datasets.
+  Same pattern (including excludeDelivered and after), different dataset.
 
 ────────────────────────────────────────
 ERROR CODES
@@ -251,3 +285,7 @@ WORKFLOW EXAMPLES
 
 6. REAL ESTATE PIPELINE:
    Zillow Agents + Property Lookup → download CSVs → enrich with email-finder
+
+7. LOCAL BUSINESS DATABASE (instant):
+   GET /api/v1/database/local-businesses?keyword=dentist&location=Austin%2C+TX&hasEmail=true&page=1
+   Loop pages until page > totalPages

package/README.md

@@ -105,6 +105,7 @@ curl -O https://app.scrapercity.com/api/downloads/RUN_ID \
 | **BuiltWith** | All sites using a technology | $4.99/search |
 | **Criminal Records** | Background check by name | $1.00 if found |
 | **Lead Database** | 3M+ B2B contacts, instant query ($149/mo plan and up) | Included |
+| **Local Business Database** | Local businesses with phones, emails and ratings, instant query ($149/mo plan and up) | Included |
 
 ## How It Works
 

package/SKILL.md

@@ -79,7 +79,7 @@ Apollo scrapes take **up to 4 days** to deliver. Do NOT poll in a loop.
 | GET | `/api/v1/scrape/logs/{runId}` | Run logs |
 | GET | `/api/v1/apollo-status` | Apollo service health: `{status: "url-based" or "legacy", message, timestamp}` |
 | GET | `/api/v1/database/leads?title=CTO&country=United%20States&hasEmail=true&limit=100` | Lead DB ($149/mo plan and up, 100k new leads/day). Optional: `excludeDelivered=true` (only leads you don't have yet), `after=0` then `pagination.next_after` (cursor paging). Company filters: `keywords`, `revenueMin`/`revenueMax`, `companyCountry`/`companyState`/`companyCity`. Exclusions: `notTitle`, `notKeywords`, `notIndustry`. `url=<people-search URL>` searches with that URL's filters. POST with a JSON body takes the same parameters (use it for a long `url`) |
-| GET | `/api/v1/database/local-businesses?...` | Local biz DB ($149/mo plan and up). Same optional `excludeDelivered` / `after` |
+| GET | `/api/v1/database/local-businesses?category=Dentist&country=US&hasContact=true&limit=100` | Local biz DB ($149/mo plan and up, 100k new businesses/day). Search like Google Maps: `keyword` (repeat; names and categories, any keyword) and `location` (repeat; cities, states, countries, postal codes), with `searched_as` in the response and `lead_database` when nothing is found but the Lead Database has 100+ people. Filters: `category`, `country`, `state`, `city`, `postalCode`, `query`, `minRating`/`maxRating`, `minReviews`/`maxReviews`, `hasEmail`, `hasPhone`, `hasWebsite`, `hasContact` (only businesses with a named contact person), `title` (business name), `box=minLat,minLng,maxLat,maxLng` (a map area). Exclusions: `notCategory`. `url=<Google Maps search URL>` searches with that URL's keyword and place. POST with a JSON body takes the same parameters (use it for a long `url`). Same optional `excludeDelivered` / `after` |
 | GET | `/api/v1/database/ecommerce?...` | Ecommerce DB ($149/mo plan and up). Same optional `excludeDelivered` / `after` |
 
 ## Status Values

package/bin/cli.mjs

@@ -402,6 +402,45 @@ async function main() {
         break
       }
 
+      // ── Database: Local businesses ($149/mo plan and up) ──
+      case 'db-local': {
+        const params = {}
+        const keyFor = { '--category': 'category', '--country': 'country', '--state': 'state', '--city': 'city',
+                        '--postal-code': 'postalCode', '--query': 'query', '--min-rating': 'minRating', '--max-rating': 'maxRating',
+                        '--min-reviews': 'minReviews', '--max-reviews': 'maxReviews', '--page': 'page', '--limit': 'limit',
+                        '--after': 'after', '--url': 'url', '--title': 'title', '--not-category': 'notCategory',
+                        '--box': 'box', '--keyword': 'keyword', '--location': 'location' }
+        // List filters take commas: --category "Dentist,Orthodontist" sends both. Locations take semicolons, since a
+        // place has commas of its own: --location "Houston, TX; Austin, TX"
+        // (--keyword goes as typed: the server splits a list on commas and keeps "plumbers in Austin, TX" whole)
+        const lists = new Set(['--category', '--country', '--not-category'])
+        for (const f of Object.keys(keyFor)) {
+          const v = flag(f)
+          if (v === undefined) continue
+          params[keyFor[f]] = lists.has(f) ? String(v).split(',').map(s => s.trim()).filter(Boolean)
+            : f === '--location' ? String(v).split(';').map(s => s.trim()).filter(Boolean) : v
+        }
+        if (flagBool('--has-email')) params.hasEmail = 'true'
+        if (flagBool('--has-phone')) params.hasPhone = 'true'
+        if (flagBool('--has-website')) params.hasWebsite = 'true'
+        if (flagBool('--has-contact')) params.hasContact = 'true'
+        if (flagBool('--exclude-delivered')) params.excludeDelivered = 'true'
+        const r = await sc.dbLocalBusinesses(params)
+        console.log(`${r.pagination?.total || '?'} total businesses, page ${r.pagination?.page || 1} of ${r.pagination?.totalPages || '?'}`)
+        if (r.pagination?.next_after) console.log(`Next page: --after ${r.pagination.next_after}`)
+        if (r.search_translation?.not_supported?.length) console.log(`Not supported from the search URL: ${r.search_translation.not_supported.join(', ')}`)
+        if (r.searched_as) {
+          const places = (r.searched_as.places || []).map(p => p.not_found ? `${p.text} (not found)` : p.read_as)
+          if (places.length) console.log(`Places: ${places.slice(0, 10).join('; ')}${places.length > 10 ? ` and ${places.length - 10} more` : ''}`)
+          const none = (r.searched_as.keywords || []).filter(k => k.matches_nothing).map(k => k.text)
+          if (none.length) console.log(`Keywords no business name or category has: ${none.join(', ')}`)
+        }
+        if (r.lead_database) console.log(`Nothing here, but the Lead Database has ${r.lead_database.count} people for this search by ${r.lead_database.read_as}: ${r.lead_database.dashboard_url}`)
+        console.log(json(r.data?.slice(0, 3) || r))
+        if (r.data?.length > 3) console.log(`... and ${r.data.length - 3} more`)
+        break
+      }
+
       // ── Poll (convenience) ────────────────────────────────
       case 'poll': {
         if (!args[0]) die('Usage: scrapercity poll <runId> [--interval 15]')
@@ -461,6 +500,17 @@ ScraperCity CLI - B2B lead generation from your terminal
       --url "<people-search URL>"  Search with that URL's filters
       --exclude-delivered                    Only leads you don't already have
       --after <id>                           Cursor paging (start with 0, then use the printed next id)
+    scrapercity db-local [filters]           Query local business database
+      --keyword "thai restaurant,sushi"      What the businesses do or are called (any of them)
+      --location "Houston, TX; Austin, TX"   Cities, states, countries or postal codes (separate with ;)
+      --category --country --state --city --postal-code --query --title
+      --min-rating --max-rating --min-reviews --max-reviews
+      --has-email --has-phone --has-website --has-contact (only businesses with a named contact person)
+      --not-category
+      --box "minLat,minLng,maxLat,maxLng"    Only businesses inside this map area
+      --url "<Google Maps search URL>"  Search with that URL's keyword and place
+      --exclude-delivered                    Only businesses you don't already have
+      --after <id>                           Cursor paging (start with 0, then use the printed next id)
 
   Env: SCRAPERCITY_API_KEY=...  or  scrapercity login
   Docs: https://scrapercity.com/agents

package/bin/mcp.mjs

@@ -81,6 +81,36 @@ const UTILITY_TOOLS = [
       excludeDelivered: { type: 'boolean', description: 'Skip leads this account already has (from the API or unlocked in the dashboard). With this on, keep page at 1 or use after.' },
       after: { type: 'string', description: 'Cursor paging: return leads after this lead id. Use "0" to start, then the pagination.next_after from each response.' }
     } }
+  },
+  {
+    name: 'query_local_business_database',
+    description: 'Query the local business database directly. Returns businesses with phone numbers, emails, websites, addresses and ratings, many with a named contact person. Up to 100 per request. Included with the $149/mo plan (100,000 new businesses a day; businesses you already have do not count again). Set hasContact=true for only businesses with a named contact person. For a daily pull of only new businesses set excludeDelivered=true. For big pulls page with after: send after="0" first, then the pagination.next_after from each response until it is null. Search the way you would on Google Maps: keyword (what the businesses do or are called, e.g. ["thai restaurant"]) and location (cities, states, countries or postal codes, e.g. ["Houston TX", "Austin TX"]); searched_as in the response says how each was read. A search that finds nothing also returns lead_database: the same search in the Lead Database when it has 100+ people. Have a Google Maps search URL? Pass it as url to search with its keyword and place right away (search_translation in the response says what was applied).',
+    inputSchema: { type: 'object', properties: {
+      keyword: { type: 'array', items: { type: 'string' }, description: 'What the businesses do or are called, as typed on Google Maps, e.g. ["thai restaurant", "sushi"]. Matches business names and categories; any keyword. A place inside a keyword ("plumbers in Austin TX") is used as the location when no location is given.' },
+      location: { type: 'array', items: { type: 'string' }, description: 'Cities, states, countries or postal codes, as typed, e.g. ["Houston TX", "78701", "Ontario", "Germany"] (up to 2,000; any of them).' },
+      url: { type: 'string', description: 'A Google Maps search URL (the address of a search on Google Maps). Its keyword and place become the search; any other filter you pass overrides the matching one.' },
+      category: { type: 'array', items: { type: 'string' }, description: 'Business categories, e.g. ["Dentist"]. A word also finds categories that contain it ("restaurant" finds "Mexican restaurant")' },
+      country: { type: 'array', items: { type: 'string' }, description: 'Two-letter country codes, e.g. ["US"]' },
+      state: { type: 'string', description: 'State or region, comma separated for several (US abbreviations work, e.g. "TX")' },
+      city: { type: 'string', description: 'City (partial match)' },
+      postalCode: { type: 'string', description: 'Postal or zip code' },
+      box: { type: 'string', description: 'A map area as "minLat,minLng,maxLat,maxLng" (e.g. "30.1,-97.9,30.5,-97.5"). Only businesses inside it.' },
+      query: { type: 'string', description: 'Search business names and descriptions' },
+      title: { type: 'string', description: 'Business name, comma separated for several (partial match)' },
+      notCategory: { type: 'array', items: { type: 'string' }, description: 'Exclude these business categories' },
+      minRating: { type: 'number', description: 'Minimum Google rating (1-5)' },
+      maxRating: { type: 'number', description: 'Maximum Google rating (1-5)' },
+      minReviews: { type: 'number', description: 'Minimum number of reviews' },
+      maxReviews: { type: 'number', description: 'Maximum number of reviews' },
+      hasEmail: { type: 'boolean', description: 'Only businesses with an email address' },
+      hasPhone: { type: 'boolean', description: 'Only businesses with a phone number' },
+      hasWebsite: { type: 'boolean', description: 'Only businesses with a website' },
+      hasContact: { type: 'boolean', description: 'Only businesses with a named contact person' },
+      page: { type: 'number', description: 'Page number (default 1)', default: 1 },
+      limit: { type: 'number', description: 'Results per page (max 100)', default: 50 },
+      excludeDelivered: { type: 'boolean', description: 'Skip businesses this account already has (from the API or unlocked in the dashboard). With this on, keep page at 1 or use after.' },
+      after: { type: 'string', description: 'Cursor paging: return businesses after this id. Use "0" to start, then the pagination.next_after from each response.' }
+    } }
   }
 ]
 
@@ -116,6 +146,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           result = await sc.dbLeads(params)
           break
         }
+        case 'query_local_business_database': {
+          const params = { ...args }
+          for (const k of ['hasEmail', 'hasPhone', 'hasWebsite', 'hasContact', 'excludeDelivered']) {
+            if (params[k]) params[k] = 'true'
+            else delete params[k]
+          }
+          if (params.after !== undefined && params.after !== null) params.after = String(params.after)
+          result = await sc.dbLocalBusinesses(params)
+          break
+        }
         default:
           return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true }
       }

package/lib/catalog.generated.mjs

@@ -1,6 +1,6 @@
 // AUTO-GENERATED by scripts/generate.mjs — DO NOT EDIT BY HAND.
 // Source of truth: scraperConfigs.ts (+ src/config/scrapers.ts). Regenerate: npm run generate
-// Generated: 2026-10-02T14:29:37.617Z
+// Generated: 2026-10-09T16:22:32.237Z
 export const TOOLS = [
   {
     "name": "scrape_apollo",
@@ -169,6 +169,10 @@ export const TOOLS = [
         "maxCrawledPlacesPerSearch": {
           "type": "number",
           "description": "Maximum results per search term"
+        },
+        "url": {
+          "type": "string",
+          "description": "A Google Maps search link, instead of searchStringsArray and locationQuery. Its search words become the keywords and the place in them the location (\"thai restaurants vegas\" runs \"thai restaurants\" in Las Vegas, Nevada). With no place in the words, the map area the link shows is searched. The response says what it ran in search_translation. searchStringsArray, locationQuery or customGeolocation sent with it are used instead of the matching part of the link."
         }
       }
     }
@@ -655,6 +659,7 @@ export const ENDPOINTS = {
   "buy-credits": "/api/v1/buy-credits",
   "database-leads": "/api/v1/database/leads",
   "database-enrichment": "/api/v1/enrich",
+  "database-local-business-enrichment": "/api/v1/enrich/local-businesses",
   "database-local-businesses": "/api/v1/database/local-businesses",
   "database-ecommerce": "/api/v1/database/ecommerce"
 }

package/lib/client.mjs

@@ -183,14 +183,19 @@ export const dbLeads = (params) => {
   return get(`${ENDPOINTS['database-leads']}?${qstr}`)
 }
 
+// Same as dbLeads: a long request (a big Google Maps URL, long category lists) goes as a POST with a JSON body.
 export const dbLocalBusinesses = (params) => {
   const qs = new URLSearchParams()
+  const body = {}
   for (const [k, v] of Object.entries(params)) {
     if (v === undefined || v === null || v === '') continue
     if (Array.isArray(v)) v.forEach(x => qs.append(k, x))
     else qs.append(k, String(v))
+    body[k] = v
   }
-  return get(`${ENDPOINTS['database-local-businesses']}?${qs}`)
+  const qstr = qs.toString()
+  if (qstr.length > LONG_QUERY) return post(ENDPOINTS['database-local-businesses'], body)
+  return get(`${ENDPOINTS['database-local-businesses']}?${qstr}`)
 }
 
 export const dbEcommerce = (params) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrapercity",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "ScraperCity CLI & MCP Server - B2B lead generation for AI agents",
   "type": "module",
   "bin": {