scrapercity 1.0.0

package/AGENT_DOCS.txt

@@ -0,0 +1,205 @@
+SCRAPERCITY API REFERENCE - FOR AI AGENTS
+==========================================
+
+BASE: https://app.scrapercity.com
+AUTH: Authorization: Bearer <api_key>
+ALL RESPONSES: JSON
+PATTERN: POST start → GET status → GET download
+
+PRICING: Plans $49, $149, $649/mo. Each gives wallet credits. Scrapers deduct per-lead.
+
+────────────────────────────────────────
+SCRAPE ENDPOINTS (POST /api/v1/scrape/{slug})
+────────────────────────────────────────
+
+apollo
+  Body: { url: "https://app.apollo.io/#/people?...", count: 1000, fileName: "My Export" }
+  Returns: { runId, message }
+  Cost: $0.0039/lead | Min 500, max 50000
+  DELIVERY: UP TO 4 DAYS. Use webhook, not polling.
+
+apollo-filters
+  Body: { seniorityLevel, functionDept, companyIndustry, personCountry, personState,
+          companyCountry, companyState, companySize, personTitles:[], companyDomains:[],
+          companyKeywords:[], personCities:[], companyCities:[], hasPhone, count, fileName }
+  At least one filter required.
+  Returns: { runId, message }
+  Cost: $0.0039/lead | DELIVERY: UP TO 4 DAYS.
+
+maps
+  Body: { searchStringsArray: ["plumbers"], locationQuery: "Denver, CO", maxCrawledPlacesPerSearch: 500 }
+  Returns: { runId, datasetId, priceMicro }
+  Cost: $0.01/place | Delivery: 5-30 min
+
+email-validator
+  Body: { emails: ["user@example.com", "test@company.com"] }
+  Returns: { runId, emailCount, estimatedCost }
+  Cost: $0.0036/email | Delivery: 1-10 min
+
+email-finder
+  Body: { contacts: [{ first_name: "John", last_name: "Doe", domain: "acme.com" }],
+          autoValidateEmails: false, autoFindMobiles: false }
+  Returns: { runId, contactCount, priceMicro }
+  Cost: $0.05/contact | Delivery: 1-10 min
+
+mobile-finder
+  Body: { inputs: ["linkedin.com/in/johndoe", "jane@company.com"] }
+  Returns: { runId, inputCount, priceMicro }
+  Cost: $0.25/input | Delivery: 1-5 min
+
+people-finder
+  Body: { name: ["John Doe"], email: [], phone_number: [], street_citystatezip: [], max_results: 1 }
+  Returns: { runId, totalSearches, estimatedCost }
+  Cost: $0.02/result | Delivery: 2-10 min
+
+store-leads
+  Body: { platform: "shopify", countryCode: "US", totalLeads: 1000,
+          emails: true, phones: true, category: "", city: "" }
+  Returns: { runId, totalLeads, estimatedCost }
+  Cost: $0.0039/lead | Delivery: INSTANT (cached DB)
+
+builtwith
+  Body: { technology: "Shopify", fileName: "Shopify sites" }
+  Returns: { runId, technology, estimatedCost }
+  Cost: $4.99 flat | Delivery: 1-5 min
+
+criminal-records
+  Body: { name: "John Smith", state: "CA", dob: "02/07/1992" }
+  state and dob optional.
+  Returns: { runId, name, state }
+  Cost: $1.00 only if records found | Delivery: 2-5 min
+
+airbnb-email
+  Body: { mode: "city", city: ["Miami, FL"], maxResults: 100 }
+  Modes: "city" (search cities), "single" (one listing URL), "bulk" (multiple listing URLs)
+  For single: { mode: "single", listingUrl: "https://airbnb.com/rooms/..." }
+  Optional: checkin, checkout, maxPages, onlyProHosts, onlyUniqueEmails
+  Returns: { runId }
+  Cost: $0.0001/listing | Delivery: 10-30 min
+
+youtube-email
+  Body: { channels: ["@MrBeast", "https://youtube.com/@Channel"] }
+  Accepts @handles or full YouTube URLs.
+  Returns: { runId }
+  Cost: per channel | Delivery: 5-15 min
+
+website-finder
+  Body: { domains: ["acme.com", "example.com"], jobTitle: "CEO" }
+  jobTitle is optional. Domains without https prefix.
+  Returns: { runId }
+  Cost: per domain | Delivery: 5-15 min
+
+yelp-scraper
+  Body: { searchTerms: ["plumbers"], locations: ["Denver, CO"], searchLimit: 10 }
+  OR: { directUrls: ["https://yelp.com/biz/..."] }
+  Returns: { runId }
+  Cost: $0.01/listing | Delivery: 5-15 min
+
+angi-angies-list-scraper
+  Body: { keyword: "plumbers", zipCodes: ["80202", "80203"], maxItems: 100 }
+  Returns: { runId }
+  Cost: $0.01/listing | Delivery: 5-15 min
+
+zillow-agents
+  Body: { location: "Denver, CO", specialty: "buyer", language: "English", searchLimit: 10 }
+  specialty and language optional.
+  Returns: { runId }
+  Cost: per agent | Delivery: 5-15 min
+
+bizbuysell-scraper
+  Body: { startUrls: ["https://bizbuysell.com/..."], maxItems: 100 }
+  Pass BizBuySell search result URLs.
+  Returns: { runId }
+  Cost: $0.01/listing | Delivery: 5-15 min
+
+crexi-scraper
+  Body: { startUrls: ["https://crexi.com/..."] }
+  Pass Crexi search result URLs.
+  Returns: { runId }
+  Cost: $0.029/listing | Delivery: 5-15 min
+
+property-lookup
+  Body: { addresses: ["123 Main St, Denver, CO 80202"], includeOwnerContact: false }
+  Full address with city, state, zip required.
+  Returns: { runId }
+  Cost: $0.15/address | Delivery: 2-10 min
+
+────────────────────────────────────────
+STATUS & DOWNLOAD
+────────────────────────────────────────
+
+GET /api/v1/scrape/status/{runId}
+  Returns: { status, statusMessage, handled, requested, outputUrl }
+  Status values: RUNNING | SUCCEEDED | FAILED | CANCELLED
+  When SUCCEEDED: outputUrl = "/api/downloads/{runId}"
+
+GET /api/downloads/{runId}
+  Returns: CSV file (binary stream)
+  Only available when status = SUCCEEDED
+
+POST /api/v1/scrape/cancel/{runId}
+  Cancel a running job.
+
+GET /api/v1/scrape/logs/{runId}
+  View run logs.
+
+────────────────────────────────────────
+ACCOUNT
+────────────────────────────────────────
+
+GET /api/v1/wallet
+  Returns: { email, wallet: { balance_dollars, total_balance_dollars }, plan: { name, usage_percent }, billing: { next_billing_date } }
+
+GET /api/v1/runs?hours=24&limit=50
+  Returns: { runs: [{ run_id, status, handled, url, file_name, created_at }] }
+
+GET /api/v1/apollo-status
+  Returns: { useApify, message } - check if Apollo URL endpoint is available
+
+────────────────────────────────────────
+DATABASES (GET, $649 plan only, 100k/day)
+────────────────────────────────────────
+
+GET /api/v1/database/leads?title=CTO&country=United States&hasEmail=true&page=1&limit=100
+  Filters: title, industry, country, state, city, companyName, companyDomain,
+           companySize, seniority, department, hasEmail, hasPhone, minEmployees, maxEmployees
+  Array params use repeated keys: ?seniority=vp&seniority=director
+  Returns: { data: [...leads], pagination: { page, limit, total, totalPages } }
+
+GET /api/v1/database/local-businesses?...
+GET /api/v1/database/ecommerce?...
+  Same pattern, different datasets.
+
+────────────────────────────────────────
+ERROR CODES
+────────────────────────────────────────
+401 = Invalid/missing API key
+402 = Insufficient balance (check wallet first!)
+403 = Account cancelled or charge processing
+409 = Duplicate request (same search within 2 min)
+429 = Rate limited / duplicate within 30s
+503 = Service temporarily unavailable
+
+────────────────────────────────────────
+WORKFLOW EXAMPLES
+────────────────────────────────────────
+
+1. MAPS SCRAPE (fast):
+   POST /api/v1/scrape/maps → get runId → poll status every 15s → download CSV
+
+2. APOLLO SCRAPE (slow):
+   POST /api/v1/scrape/apollo → get runId → configure webhook → wait for callback
+   Do NOT poll Apollo in a tight loop. Check once per hour at most.
+
+3. ENRICH PIPELINE:
+   Apollo/Maps → download CSV → extract emails → POST email-validator → download validated CSV
+
+4. LEAD DATABASE (instant):
+   GET /api/v1/database/leads?title=CTO&industry=computer+software&hasEmail=true&page=1
+   Loop pages until page > totalPages
+
+5. LOCAL BUSINESS PIPELINE:
+   Yelp/Angi/Maps → download CSV → POST email-finder with names+domains → POST mobile-finder
+
+6. REAL ESTATE PIPELINE:
+   Zillow Agents + Property Lookup → download CSVs → enrich with email-finder

package/README.md

@@ -0,0 +1,128 @@
+# ScraperCity - B2B Lead Generation for AI Agents
+
+Pull leads, validate emails, find mobile numbers, and scrape business data - all from your AI agent, CLI, or code.
+
+ScraperCity gives AI agents access to 15+ B2B data tools: Apollo scraping, Google Maps extraction, email finding/validation, mobile number lookup, skip tracing, ecommerce store data, criminal records, and more.
+
+## Quick Start
+
+### Option 1: CLI
+
+```bash
+npx scrapercity login            # enter your API key
+npx scrapercity wallet           # check balance
+npx scrapercity maps -q "plumbers" -l "Denver, CO"
+npx scrapercity poll <runId>     # wait for results
+npx scrapercity download <runId> # save CSV
+```
+
+### Option 2: MCP Server (Claude Code, Cursor, Windsurf, etc.)
+
+Add to your MCP config (e.g. `~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "scrapercity": {
+      "command": "npx",
+      "args": ["-y", "scrapercity-mcp"],
+      "env": {
+        "SCRAPERCITY_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Then tell your AI: *"Find 1000 plumbers in Denver with emails using ScraperCity"*
+
+### Option 3: Skill File (Claude Code)
+
+Copy the skill file into your project:
+
+```bash
+npx scrapercity-mcp --print-skill > SCRAPERCITY_SKILL.md
+```
+
+Or download from: `https://scrapercity.com/agents/SKILL.md`
+
+Then in Claude Code: *"Read SCRAPERCITY_SKILL.md and find me 2000 marketing directors at SaaS companies in California, validate their emails, and save to leads.csv"*
+
+### Option 4: Direct API
+
+```bash
+# Start a Maps scrape
+curl -X POST https://app.scrapercity.com/api/v1/scrape/maps \
+  -H "Authorization: Bearer $SCRAPERCITY_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"searchStringsArray":["plumbers"],"locationQuery":"Denver, CO","maxCrawledPlacesPerSearch":500}'
+
+# Check status
+curl https://app.scrapercity.com/api/v1/scrape/status/RUN_ID \
+  -H "Authorization: Bearer $SCRAPERCITY_API_KEY"
+
+# Download CSV when SUCCEEDED
+curl -O https://app.scrapercity.com/api/downloads/RUN_ID \
+  -H "Authorization: Bearer $SCRAPERCITY_API_KEY"
+```
+
+## Available Tools
+
+| Tool | What it does | Cost |
+|------|-------------|------|
+| **Apollo** | B2B contacts by job title, industry, location | $0.0039/lead |
+| **Google Maps** | Local businesses with phones, emails, reviews | $0.01/place |
+| **Email Validator** | Verify deliverability, catch-all, MX records | $0.0036/email |
+| **Email Finder** | Find business email from name + company | $0.05/contact |
+| **Mobile Finder** | Phone numbers from LinkedIn or email | $0.25/input |
+| **People Finder** | Skip trace by name, email, phone, address | $0.02/result |
+| **Store Leads** | Shopify/WooCommerce stores with contacts | $0.0039/lead |
+| **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 ($649 plan) | Included |
+
+## How It Works
+
+1. **Start a scrape** → get a `runId`
+2. **Poll status** (or use webhooks) → wait for `SUCCEEDED`
+3. **Download CSV** → leads with full contact info
+
+Apollo scrapes take up to 4 days. All other scrapers: 1-30 minutes. Store leads are instant.
+
+## Authentication
+
+Get your API key at [app.scrapercity.com/dashboard/api-docs](https://app.scrapercity.com/dashboard/api-docs)
+
+```bash
+# Environment variable (recommended)
+export SCRAPERCITY_API_KEY="your_key"
+
+# Or save to config file
+npx scrapercity login
+```
+
+## Webhooks
+
+For Apollo and long-running scrapes, configure a webhook at [app.scrapercity.com/dashboard/webhooks](https://app.scrapercity.com/dashboard/webhooks) to get notified when results are ready.
+
+## Plans
+
+| Plan | Price | Credits |
+|------|-------|---------|
+| Trial | Free | $5 |
+| Starter | $49/mo | $49 |
+| Growth | $149/mo | $149 + 10% bonus |
+| Professional | $649/mo | $649 + 30% bonus + Database API |
+
+Buy additional credits anytime. [scrapercity.com/pricing](https://scrapercity.com/pricing)
+
+## Links
+
+- [Agent Docs](https://scrapercity.com/agents) - setup guide
+- [API Reference](https://scrapercity.com/api-docs) - full documentation
+- [Skill File](https://scrapercity.com/agents/SKILL.md) - for Claude Code
+- [MCP Server Listing](https://scrapercity.com/agents) - configuration
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,98 @@
+# ScraperCity - B2B Lead Generation
+
+## Setup
+```bash
+export SCRAPERCITY_API_KEY="your_key"   # get from app.scrapercity.com/dashboard/api-docs
+npx scrapercity wallet                   # verify balance
+```
+
+## Core Pattern
+Every scraper follows: **start → poll → download**
+```
+POST /api/v1/scrape/{slug}  →  { runId }
+GET  /api/v1/scrape/status/{runId}  →  { status, handled, outputUrl }
+GET  /api/downloads/{runId}  →  CSV file
+```
+Auth: `Authorization: Bearer $SCRAPERCITY_API_KEY` on all requests.
+
+## All Scrapers (POST to /api/v1/scrape/{slug})
+
+| Slug | Input | Cost | Speed |
+|------|-------|------|-------|
+| `apollo` | `{url, count, fileName}` | $0.0039/lead | ~4 DAYS (use webhook) |
+| `apollo-filters` | `{seniorityLevel, functionDept, companyIndustry, personCountry, personState, companySize, personTitles[], companyDomains[], count}` | $0.0039/lead | ~4 DAYS |
+| `maps` | `{searchStringsArray:["query"], locationQuery, maxCrawledPlacesPerSearch}` | $0.01/place | 5-30 min |
+| `email-validator` | `{emails:["a@b.com"]}` | $0.0036/email | 1-10 min |
+| `email-finder` | `{contacts:[{first_name,last_name,domain}], autoValidateEmails, autoFindMobiles}` | $0.05/contact | 1-10 min |
+| `mobile-finder` | `{inputs:["linkedin.com/in/x","email@co.com"]}` | $0.25/input | 1-5 min |
+| `people-finder` | `{name:[], email:[], phone_number:[], street_citystatezip:[], max_results}` | $0.02/result | 2-10 min |
+| `store-leads` | `{platform, countryCode, totalLeads, emails:true, phones:true}` | $0.0039/lead | instant |
+| `builtwith` | `{technology}` | $4.99 flat | 1-5 min |
+| `criminal-records` | `{name, state, dob}` | $1.00 if found | 2-5 min |
+| `airbnb-email` | `{mode:"city", city:["Miami, FL"], maxResults:100}` | $0.0001/listing | 10-30 min |
+| `youtube-email` | `{channels:["@Handle","https://youtube.com/@X"]}` | per channel | 5-15 min |
+| `website-finder` | `{domains:["acme.com"], jobTitle:"CEO"}` | per domain | 5-15 min |
+| `yelp-scraper` | `{searchTerms:["plumbers"], locations:["Denver, CO"], searchLimit:10}` | $0.01/listing | 5-15 min |
+| `angi-angies-list-scraper` | `{keyword, zipCodes:["80202"], maxItems:100}` | $0.01/listing | 5-15 min |
+| `zillow-agents` | `{location:"Denver, CO", specialty, searchLimit:10}` | per agent | 5-15 min |
+| `bizbuysell-scraper` | `{startUrls:["<search-url>"], maxItems:100}` | $0.01/listing | 5-15 min |
+| `crexi-scraper` | `{startUrls:["<search-url>"]}` | $0.029/listing | 5-15 min |
+| `property-lookup` | `{addresses:["123 Main St, City, ST 12345"], includeOwnerContact:false}` | $0.15/address | 2-10 min |
+
+## ⚠ Apollo Delivery
+Apollo scrapes take **up to 4 days** to deliver. Do NOT poll in a loop.
+- Set up a webhook at `app.scrapercity.com/dashboard/webhooks`
+- Webhook fires when results are ready with `{runId, fileName, leadsCount}`
+- If you must poll, check once per hour max
+
+## Other Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/v1/wallet` | Balance, plan, billing |
+| GET | `/api/v1/runs?hours=24&limit=50` | Recent runs |
+| POST | `/api/v1/scrape/cancel/{runId}` | Cancel running job |
+| GET | `/api/v1/scrape/logs/{runId}` | Run logs |
+| GET | `/api/v1/apollo-status` | Apollo service health |
+| GET | `/api/v1/database/leads?title=CTO&country=US&hasEmail=true&page=1&limit=100` | Lead DB ($649 plan, 100k/day) |
+| GET | `/api/v1/database/local-businesses?...` | Local biz DB ($649 plan) |
+| GET | `/api/v1/database/ecommerce?...` | Ecommerce DB ($649 plan) |
+
+## Status Values
+`RUNNING` → `SUCCEEDED` or `FAILED` or `CANCELLED`
+
+## Error Codes
+- `401` - bad or missing API key
+- `402` - insufficient balance (check wallet first)
+- `403` - account cancelled or charge processing
+- `409` - duplicate request (same search submitted recently)
+- `429` - rate limited / duplicate within 30s
+- `503` - service temporarily unavailable
+
+## CLI Shorthand
+```bash
+scrapercity maps -q "plumbers" -l "Denver, CO" --limit 500
+scrapercity yelp -q "dentists" -l "Austin, TX"
+scrapercity airbnb --city "Miami, FL" --limit 200
+scrapercity youtube-email @MrBeast @PewDiePie
+scrapercity website-finder acme.com example.com --title "CEO"
+scrapercity angi -q "electricians" --zips "90210,90211"
+scrapercity zillow-agents -l "Denver, CO"
+scrapercity bizbuysell <bizbuysell-search-url>
+scrapercity crexi <crexi-search-url>
+scrapercity property-lookup "123 Main St, Denver, CO 80202" --owner-contact
+scrapercity poll <runId>          # polls until done
+scrapercity download <runId>      # saves CSV
+```
+
+## Tips
+- Always check `wallet` before large scrapes to avoid 402 errors
+- Apollo URL must be from apollo.io People search - other pages rejected
+- Maps: split large metro areas into sub-cities for better coverage
+- Email validator: dedupes automatically, only charges for unique emails
+- Store leads: zero COGS (cached DB), instant results
+- Yelp/Angi: can also pass directUrls instead of search terms
+- YouTube: accepts both @handles and full channel URLs
+- Website finder: domains only, no https:// prefix needed
+- Property lookup: full address with city, state, zip required
+- Downloads return CSV with all available fields