scrapercity 1.0.0__tar.gz

scrapercity-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScraperCity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scrapercity-1.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: scrapercity
+Version: 1.0.0
+Summary: B2B lead generation for AI agents. 20+ tools: Apollo, Google Maps, email finder, skip trace, and more.
+Author-email: ScraperCity <support@scrapercity.com>
+License: MIT
+Project-URL: Homepage, https://scrapercity.com
+Project-URL: Documentation, https://scrapercity.com/agents/AGENT_DOCS.txt
+Project-URL: Repository, https://github.com/scrapercity/scrapercity-python
+Project-URL: Issues, https://github.com/scrapercity/scrapercity-python/issues
+Keywords: leads,apollo,scraping,b2b,email-finder,sales,lead-generation,google-maps,skip-trace,langchain,openai-agents,ai-agent,prospecting,contact-enrichment,email-validation,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.1; extra == "openai"
+Dynamic: license-file
+
+# ScraperCity Python SDK
+
+B2B lead generation for AI agents and Python developers. 20+ tools including Apollo scraping, Google Maps, email finder/validator, mobile lookup, skip trace, ecommerce store data, and more.
+
+## Install
+
+```bash
+pip install scrapercity
+```
+
+## Quick Start
+
+```python
+from scrapercity import ScraperCity
+
+sc = ScraperCity("your-api-key")
+
+# Check balance
+print(sc.wallet())
+
+# Scrape Google Maps
+result = sc.scrape_maps("plumbers", "Denver, CO", limit=200)
+print(result["runId"])
+
+# Query lead database (requires $649/mo plan)
+leads = sc.query_leads(title="CEO", state="California", limit=50)
+```
+
+## LangChain / LangGraph
+
+```python
+from scrapercity import langchain_tools
+from langgraph.prebuilt import create_react_agent
+
+tools = langchain_tools(api_key="your-key")
+agent = create_react_agent(llm, tools)
+result = agent.invoke({"messages": [{"role": "user", "content": "Find 50 CEOs in New York"}]})
+```
+
+## OpenAI Agents SDK
+
+```python
+from agents import Agent
+from scrapercity.openai_tools import get_tools, init
+
+init("your-api-key")
+agent = Agent(name="Lead Gen Agent", tools=get_tools())
+```
+
+## OpenAI Function Calling
+
+```python
+from scrapercity.openai_tools import get_function_definitions, handle_tool_call, init
+
+init("your-api-key")
+tools = get_function_definitions()
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=tools
+)
+
+# Handle the tool call
+for call in response.choices[0].message.tool_calls:
+    result = handle_tool_call(call.function.name, json.loads(call.function.arguments))
+```
+
+## Available Methods
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `scrape_apollo(url, count)` | B2B contacts from Apollo.io | $0.0039/lead |
+| `scrape_maps(query, location)` | Google Maps businesses | $0.01/place |
+| `validate_emails(emails)` | Email deliverability check | $0.0036/email |
+| `find_emails(contacts)` | Email from name + company | $0.05/contact |
+| `find_mobiles(inputs)` | Phone from LinkedIn/email | $0.25/input |
+| `find_people(**params)` | Skip trace by name/email/phone | $0.02/result |
+| `scrape_store_leads(**params)` | Shopify/WooCommerce stores | $0.0039/lead |
+| `scrape_builtwith(technology)` | Sites using a technology | $4.99/search |
+| `search_criminal_records(name)` | Background check | $1.00 if found |
+| `query_leads(**params)` | 4M+ B2B database (instant) | Included ($649 plan) |
+| `scrape_yelp(**params)` | Yelp business listings | varies |
+| `scrape_angi(keyword, zips)` | Angi service providers | varies |
+| `scrape_zillow_agents(location)` | Zillow real estate agents | varies |
+| `scrape_airbnb(**params)` | Airbnb host emails | varies |
+| `scrape_youtube_email(channels)` | YouTube channel emails | varies |
+
+## Authentication
+
+```bash
+export SCRAPERCITY_API_KEY="your-key"
+```
+
+Or pass directly: `ScraperCity(api_key="your-key")`
+
+Get your API key at [scrapercity.com](https://scrapercity.com)
+
+## License
+
+MIT

scrapercity-1.0.0/README.md

@@ -0,0 +1,101 @@
+# ScraperCity Python SDK
+
+B2B lead generation for AI agents and Python developers. 20+ tools including Apollo scraping, Google Maps, email finder/validator, mobile lookup, skip trace, ecommerce store data, and more.
+
+## Install
+
+```bash
+pip install scrapercity
+```
+
+## Quick Start
+
+```python
+from scrapercity import ScraperCity
+
+sc = ScraperCity("your-api-key")
+
+# Check balance
+print(sc.wallet())
+
+# Scrape Google Maps
+result = sc.scrape_maps("plumbers", "Denver, CO", limit=200)
+print(result["runId"])
+
+# Query lead database (requires $649/mo plan)
+leads = sc.query_leads(title="CEO", state="California", limit=50)
+```
+
+## LangChain / LangGraph
+
+```python
+from scrapercity import langchain_tools
+from langgraph.prebuilt import create_react_agent
+
+tools = langchain_tools(api_key="your-key")
+agent = create_react_agent(llm, tools)
+result = agent.invoke({"messages": [{"role": "user", "content": "Find 50 CEOs in New York"}]})
+```
+
+## OpenAI Agents SDK
+
+```python
+from agents import Agent
+from scrapercity.openai_tools import get_tools, init
+
+init("your-api-key")
+agent = Agent(name="Lead Gen Agent", tools=get_tools())
+```
+
+## OpenAI Function Calling
+
+```python
+from scrapercity.openai_tools import get_function_definitions, handle_tool_call, init
+
+init("your-api-key")
+tools = get_function_definitions()
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=tools
+)
+
+# Handle the tool call
+for call in response.choices[0].message.tool_calls:
+    result = handle_tool_call(call.function.name, json.loads(call.function.arguments))
+```
+
+## Available Methods
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `scrape_apollo(url, count)` | B2B contacts from Apollo.io | $0.0039/lead |
+| `scrape_maps(query, location)` | Google Maps businesses | $0.01/place |
+| `validate_emails(emails)` | Email deliverability check | $0.0036/email |
+| `find_emails(contacts)` | Email from name + company | $0.05/contact |
+| `find_mobiles(inputs)` | Phone from LinkedIn/email | $0.25/input |
+| `find_people(**params)` | Skip trace by name/email/phone | $0.02/result |
+| `scrape_store_leads(**params)` | Shopify/WooCommerce stores | $0.0039/lead |
+| `scrape_builtwith(technology)` | Sites using a technology | $4.99/search |
+| `search_criminal_records(name)` | Background check | $1.00 if found |
+| `query_leads(**params)` | 4M+ B2B database (instant) | Included ($649 plan) |
+| `scrape_yelp(**params)` | Yelp business listings | varies |
+| `scrape_angi(keyword, zips)` | Angi service providers | varies |
+| `scrape_zillow_agents(location)` | Zillow real estate agents | varies |
+| `scrape_airbnb(**params)` | Airbnb host emails | varies |
+| `scrape_youtube_email(channels)` | YouTube channel emails | varies |
+
+## Authentication
+
+```bash
+export SCRAPERCITY_API_KEY="your-key"
+```
+
+Or pass directly: `ScraperCity(api_key="your-key")`
+
+Get your API key at [scrapercity.com](https://scrapercity.com)
+
+## License
+
+MIT

scrapercity-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scrapercity"
+version = "1.0.0"
+description = "B2B lead generation for AI agents. 20+ tools: Apollo, Google Maps, email finder, skip trace, and more."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "ScraperCity", email = "support@scrapercity.com"}]
+keywords = [
+    "leads", "apollo", "scraping", "b2b", "email-finder", "sales",
+    "lead-generation", "google-maps", "skip-trace", "langchain",
+    "openai-agents", "ai-agent", "prospecting", "contact-enrichment",
+    "email-validation", "mcp"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+
+[project.urls]
+Homepage = "https://scrapercity.com"
+Documentation = "https://scrapercity.com/agents/AGENT_DOCS.txt"
+Repository = "https://github.com/scrapercity/scrapercity-python"
+Issues = "https://github.com/scrapercity/scrapercity-python/issues"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2"]
+openai = ["openai-agents>=0.1"]
+
+[tool.setuptools.packages.find]
+include = ["scrapercity*"]

scrapercity-1.0.0/scrapercity/__init__.py

@@ -0,0 +1,11 @@
+"""ScraperCity - B2B lead generation for AI agents and Python developers."""
+from scrapercity.client import ScraperCity
+
+__version__ = "1.0.0"
+__all__ = ["ScraperCity", "langchain_tools"]
+
+
+def langchain_tools(api_key=None):
+    """Lazy import to avoid requiring langchain-core for basic usage."""
+    from scrapercity.langchain_tools import get_tools
+    return get_tools(api_key)

scrapercity-1.0.0/scrapercity/client.py

@@ -0,0 +1,225 @@
+"""ScraperCity API client."""
+import os
+import json
+import time
+from pathlib import Path
+from typing import Any, Optional
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+
+BASE_URL = "https://app.scrapercity.com"
+
+
+class ScraperCity:
+    """ScraperCity API client for B2B lead generation.
+
+    Usage:
+        from scrapercity import ScraperCity
+        sc = ScraperCity("your-api-key")
+        result = sc.wallet()
+    """
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.environ.get("SCRAPERCITY_API_KEY") or self._load_rc()
+        if not self.api_key:
+            raise ValueError(
+                "No API key. Pass api_key= or set SCRAPERCITY_API_KEY env var. "
+                "Get yours at scrapercity.com"
+            )
+
+    def _load_rc(self) -> Optional[str]:
+        rc = Path.home() / ".scrapercityrc"
+        if rc.exists():
+            data = json.loads(rc.read_text())
+            return data.get("apiKey")
+        return None
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> dict:
+        url = path if path.startswith("http") else f"{BASE_URL}{path}"
+        data = json.dumps(body).encode() if body and method != "GET" else None
+        req = Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("User-Agent", "scrapercity-python/1.0")
+        try:
+            with urlopen(req) as resp:
+                return json.loads(resp.read())
+        except HTTPError as e:
+            text = e.read().decode()
+            try:
+                err = json.loads(text)
+            except Exception:
+                err = {"raw": text}
+            raise RuntimeError(err.get("error", err.get("message", f"HTTP {e.code}"))) from e
+
+    def _get(self, path: str) -> dict:
+        return self._request("GET", path)
+
+    def _post(self, path: str, body: dict) -> dict:
+        return self._request("POST", path, body)
+
+    # ── Wallet & Runs ──────────────────────────────────────────
+    def wallet(self) -> dict:
+        """Check account balance, plan, and billing info."""
+        return self._get("/api/v1/wallet")
+
+    def runs(self, hours: int = 24, limit: int = 50) -> dict:
+        """List recent scraper runs."""
+        return self._get(f"/api/v1/runs?hours={hours}&limit={limit}")
+
+    # ── Status / Download / Cancel ─────────────────────────────
+    def status(self, run_id: str) -> dict:
+        """Check status of a scraper run."""
+        return self._get(f"/api/v1/scrape/status/{run_id}")
+
+    def cancel(self, run_id: str) -> dict:
+        """Cancel a running scraper job."""
+        return self._post(f"/api/v1/scrape/cancel/{run_id}", {})
+
+    def download(self, run_id: str, output_path: Optional[str] = None) -> dict:
+        """Download CSV results of a completed run."""
+        url = f"{BASE_URL}/api/downloads/{run_id}"
+        req = Request(url)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        with urlopen(req) as resp:
+            data = resp.read()
+        out = output_path or f"{run_id}.csv"
+        Path(out).write_bytes(data)
+        return {"path": out, "bytes": len(data)}
+
+    # ── Apollo ─────────────────────────────────────────────────
+    def scrape_apollo(self, url: str, count: int = 1000, file_name: str = "") -> dict:
+        """Scrape B2B contacts from Apollo.io using a search URL."""
+        return self._post("/api/v1/scrape/apollo", {"url": url, "count": count, "fileName": file_name})
+
+    def scrape_apollo_filters(self, **filters) -> dict:
+        """Scrape Apollo.io using filter parameters."""
+        return self._post("/api/v1/scrape/apollo-filters", filters)
+
+    # ── Maps ───────────────────────────────────────────────────
+    def scrape_maps(self, query: str, location: str, limit: int = 500) -> dict:
+        """Scrape businesses from Google Maps."""
+        q = [query] if isinstance(query, str) else query
+        return self._post("/api/v1/scrape/maps", {
+            "searchStringsArray": q,
+            "locationQuery": location,
+            "maxCrawledPlacesPerSearch": limit
+        })
+
+    # ── Email Validator ────────────────────────────────────────
+    def validate_emails(self, emails: list[str]) -> dict:
+        """Validate email addresses for deliverability."""
+        return self._post("/api/v1/scrape/email-validator", {"emails": emails})
+
+    # ── Email Finder ───────────────────────────────────────────
+    def find_emails(self, contacts: list[dict], validate: bool = False, mobiles: bool = False) -> dict:
+        """Find business email addresses from name + company."""
+        return self._post("/api/v1/scrape/email-finder", {
+            "contacts": contacts,
+            "autoValidateEmails": validate,
+            "autoFindMobiles": mobiles
+        })
+
+    # ── Mobile Finder ──────────────────────────────────────────
+    def find_mobiles(self, inputs: list[str]) -> dict:
+        """Find mobile numbers from LinkedIn URLs or work emails."""
+        return self._post("/api/v1/scrape/mobile-finder", {"inputs": inputs})
+
+    # ── People Finder / Skip Trace ─────────────────────────────
+    def find_people(self, **params) -> dict:
+        """Skip trace - look up personal info by name, email, phone, or address."""
+        return self._post("/api/v1/scrape/people-finder", params)
+
+    # ── Store Leads (Ecommerce) ────────────────────────────────
+    def scrape_store_leads(self, **params) -> dict:
+        """Get ecommerce store data (Shopify, WooCommerce, etc)."""
+        return self._post("/api/v1/scrape/store-leads", params)
+
+    # ── BuiltWith ──────────────────────────────────────────────
+    def scrape_builtwith(self, technology: str, file_name: str = "") -> dict:
+        """Find websites using a specific technology."""
+        return self._post("/api/v1/scrape/builtwith", {"technology": technology, "fileName": file_name})
+
+    # ── Criminal Records ───────────────────────────────────────
+    def search_criminal_records(self, name: str, state: str = "", dob: str = "") -> dict:
+        """Search criminal records by name."""
+        return self._post("/api/v1/scrape/criminal-records", {"name": name, "state": state, "dob": dob})
+
+    # ── Airbnb ─────────────────────────────────────────────────
+    def scrape_airbnb(self, **params) -> dict:
+        """Scrape Airbnb host emails by city or listing URL."""
+        return self._post("/api/v1/scrape/airbnb-email", params)
+
+    # ── YouTube Email ──────────────────────────────────────────
+    def scrape_youtube_email(self, channels: list[str]) -> dict:
+        """Find business emails for YouTube channels."""
+        return self._post("/api/v1/scrape/youtube-email", {"channels": channels})
+
+    # ── Website Finder ─────────────────────────────────────────
+    def scrape_website_finder(self, domains: list[str], job_title: str = "") -> dict:
+        """Find contact info from website domains."""
+        return self._post("/api/v1/scrape/website-finder", {"domains": domains, "jobTitle": job_title})
+
+    # ── Yelp ───────────────────────────────────────────────────
+    def scrape_yelp(self, **params) -> dict:
+        """Scrape business listings from Yelp."""
+        return self._post("/api/v1/scrape/yelp-scraper", params)
+
+    # ── Angi ───────────────────────────────────────────────────
+    def scrape_angi(self, keyword: str, zip_codes: list[str] = None, max_items: int = 100) -> dict:
+        """Scrape from Angi (Angie's List)."""
+        return self._post("/api/v1/scrape/angi-angies-list-scraper", {
+            "keyword": keyword, "zipCodes": zip_codes or [], "maxItems": max_items
+        })
+
+    # ── Zillow Agents ──────────────────────────────────────────
+    def scrape_zillow_agents(self, location: str, **opts) -> dict:
+        """Scrape real estate agents from Zillow."""
+        return self._post("/api/v1/scrape/zillow-agents", {"location": location, **opts})
+
+    # ── BizBuySell ─────────────────────────────────────────────
+    def scrape_bizbuysell(self, start_urls: list[str], max_items: int = 100) -> dict:
+        """Scrape business-for-sale listings."""
+        return self._post("/api/v1/scrape/bizbuysell-scraper", {"startUrls": start_urls, "maxItems": max_items})
+
+    # ── Crexi ──────────────────────────────────────────────────
+    def scrape_crexi(self, start_urls: list[str]) -> dict:
+        """Scrape commercial real estate from Crexi."""
+        return self._post("/api/v1/scrape/crexi-scraper", {"startUrls": start_urls})
+
+    # ── Property Lookup ────────────────────────────────────────
+    def scrape_property_lookup(self, addresses: list[str], include_owner: bool = False) -> dict:
+        """Look up property data by address."""
+        return self._post("/api/v1/scrape/property-lookup", {
+            "addresses": addresses, "includeOwnerContact": include_owner
+        })
+
+    # ── Lead Database ($649 plan) ──────────────────────────────
+    def query_leads(self, **params) -> dict:
+        """Query 4M+ B2B contacts instantly."""
+        qs = urlencode({k: v for k, v in params.items() if v}, doseq=True)
+        return self._get(f"/api/v1/database/leads?{qs}")
+
+    def query_local_businesses(self, **params) -> dict:
+        """Query local business database."""
+        qs = urlencode({k: v for k, v in params.items() if v}, doseq=True)
+        return self._get(f"/api/v1/database/local-businesses?{qs}")
+
+    def query_ecommerce(self, **params) -> dict:
+        """Query ecommerce store database."""
+        qs = urlencode({k: v for k, v in params.items() if v}, doseq=True)
+        return self._get(f"/api/v1/database/ecommerce?{qs}")
+
+    # ── Poll ───────────────────────────────────────────────────
+    def poll_until_done(self, run_id: str, interval: int = 15, timeout: int = 3600) -> dict:
+        """Poll a run until it completes. Returns final status."""
+        start = time.time()
+        while time.time() - start < timeout:
+            s = self.status(run_id)
+            if s.get("status") == "SUCCEEDED":
+                return s
+            if s.get("status") in ("FAILED", "CANCELLED"):
+                raise RuntimeError(f"Run {run_id} ended: {s.get('status')} - {s.get('statusMessage', '')}")
+            time.sleep(interval)
+        raise TimeoutError(f"Timed out after {timeout}s waiting for {run_id}")

scrapercity-1.0.0/scrapercity/langchain_tools.py

@@ -0,0 +1,122 @@
+"""LangChain tool wrappers for ScraperCity.
+
+Usage with LangChain:
+    from scrapercity import langchain_tools
+    tools = langchain_tools()
+    # Use with any LangChain agent
+
+Usage with LangGraph:
+    from scrapercity import langchain_tools
+    from langgraph.prebuilt import create_react_agent
+    tools = langchain_tools()
+    agent = create_react_agent(llm, tools)
+"""
+import json
+from typing import Optional
+
+from scrapercity.client import ScraperCity
+
+
+def get_tools(api_key: Optional[str] = None) -> list:
+    """Return a list of LangChain tools for ScraperCity.
+
+    Args:
+        api_key: ScraperCity API key. Falls back to SCRAPERCITY_API_KEY env var.
+
+    Returns:
+        List of LangChain tools ready to use with any agent.
+    """
+    try:
+        from langchain_core.tools import tool as langchain_tool
+    except ImportError:
+        raise ImportError("Install langchain-core: pip install scrapercity[langchain]")
+
+    sc = ScraperCity(api_key)
+
+    @langchain_tool
+    def check_wallet() -> str:
+        """Check ScraperCity account balance, plan, and billing info. Call this FIRST to verify credits."""
+        return json.dumps(sc.wallet(), indent=2)
+
+    @langchain_tool
+    def list_runs(hours: int = 24, limit: int = 20) -> str:
+        """List recent ScraperCity scraper runs with status, lead counts, and costs."""
+        return json.dumps(sc.runs(hours, limit), indent=2)
+
+    @langchain_tool
+    def scrape_apollo(url: str, count: int = 1000) -> str:
+        """Scrape B2B contacts from Apollo.io using a search URL. Delivery takes up to 4 days."""
+        return json.dumps(sc.scrape_apollo(url, count), indent=2)
+
+    @langchain_tool
+    def scrape_maps(query: str, location: str, limit: int = 500) -> str:
+        """Scrape businesses from Google Maps. Returns names, addresses, phones, emails, ratings."""
+        return json.dumps(sc.scrape_maps(query, location, limit), indent=2)
+
+    @langchain_tool
+    def validate_emails(emails: list[str]) -> str:
+        """Validate email addresses. Returns deliverability status, catch-all detection, MX records."""
+        return json.dumps(sc.validate_emails(emails), indent=2)
+
+    @langchain_tool
+    def find_emails(contacts: list[dict]) -> str:
+        """Find business email addresses from name + company. Each contact needs name AND company/domain."""
+        return json.dumps(sc.find_emails(contacts), indent=2)
+
+    @langchain_tool
+    def find_mobiles(inputs: list[str]) -> str:
+        """Find mobile phone numbers from LinkedIn URLs or work emails."""
+        return json.dumps(sc.find_mobiles(inputs), indent=2)
+
+    @langchain_tool
+    def find_people(name: list[str] = None, email: list[str] = None, phone_number: list[str] = None) -> str:
+        """Skip trace / people finder. Look up personal info by name, email, or phone."""
+        params = {}
+        if name:
+            params["name"] = name
+        if email:
+            params["email"] = email
+        if phone_number:
+            params["phone_number"] = phone_number
+        return json.dumps(sc.find_people(**params), indent=2)
+
+    @langchain_tool
+    def scrape_store_leads(platform: str = "shopify", country_code: str = "", total_leads: int = 1000) -> str:
+        """Get ecommerce store data (Shopify, WooCommerce, etc). Instant results from cached database."""
+        return json.dumps(sc.scrape_store_leads(platform=platform, countryCode=country_code, totalLeads=total_leads), indent=2)
+
+    @langchain_tool
+    def query_lead_database(title: str = "", industry: str = "", state: str = "", city: str = "", limit: int = 50) -> str:
+        """Query 4M+ B2B contacts instantly by title, industry, and location. Requires $649/mo plan."""
+        return json.dumps(sc.query_leads(title=title, industry=industry, state=state, city=city, limit=limit), indent=2)
+
+    @langchain_tool
+    def check_run_status(run_id: str) -> str:
+        """Check status of a scraper run. Returns RUNNING/SUCCEEDED/FAILED and download URL when done."""
+        return json.dumps(sc.status(run_id), indent=2)
+
+    @langchain_tool
+    def download_results(run_id: str, output_path: str = "") -> str:
+        """Download CSV results of a completed scraper run."""
+        return json.dumps(sc.download(run_id, output_path or None), indent=2)
+
+    @langchain_tool
+    def cancel_run(run_id: str) -> str:
+        """Cancel a running scraper job."""
+        return json.dumps(sc.cancel(run_id), indent=2)
+
+    return [
+        check_wallet,
+        list_runs,
+        scrape_apollo,
+        scrape_maps,
+        validate_emails,
+        find_emails,
+        find_mobiles,
+        find_people,
+        scrape_store_leads,
+        query_lead_database,
+        check_run_status,
+        download_results,
+        cancel_run,
+    ]

scrapercity-1.0.0/scrapercity/openai_tools.py

@@ -0,0 +1,343 @@
+"""OpenAI Agents SDK tool definitions for ScraperCity.
+
+Usage with OpenAI Agents SDK:
+    from scrapercity.openai_tools import get_tools
+    from agents import Agent
+
+    tools = get_tools()
+    agent = Agent(name="Lead Gen Agent", tools=tools)
+
+Usage with OpenAI function calling:
+    from scrapercity.openai_tools import get_function_definitions, handle_tool_call
+    functions = get_function_definitions()
+    # Pass to chat.completions.create(tools=functions)
+    # Then: result = handle_tool_call(function_name, arguments)
+"""
+import json
+from typing import Optional
+
+from scrapercity.client import ScraperCity
+
+_client: Optional[ScraperCity] = None
+
+
+def _get_client() -> ScraperCity:
+    global _client
+    if _client is None:
+        _client = ScraperCity()
+    return _client
+
+
+def init(api_key: Optional[str] = None):
+    """Initialize the ScraperCity client. Call before using tools."""
+    global _client
+    _client = ScraperCity(api_key)
+
+
+# ── Tool handler functions ─────────────────────────────────────
+
+def _check_wallet(**kwargs) -> str:
+    return json.dumps(_get_client().wallet(), indent=2)
+
+def _list_runs(hours: int = 24, limit: int = 20, **kwargs) -> str:
+    return json.dumps(_get_client().runs(hours, limit), indent=2)
+
+def _scrape_apollo(url: str, count: int = 1000, **kwargs) -> str:
+    return json.dumps(_get_client().scrape_apollo(url, count), indent=2)
+
+def _scrape_maps(query: str, location: str, limit: int = 500, **kwargs) -> str:
+    return json.dumps(_get_client().scrape_maps(query, location, limit), indent=2)
+
+def _validate_emails(emails: list, **kwargs) -> str:
+    return json.dumps(_get_client().validate_emails(emails), indent=2)
+
+def _find_emails(contacts: list, **kwargs) -> str:
+    return json.dumps(_get_client().find_emails(contacts), indent=2)
+
+def _find_mobiles(inputs: list, **kwargs) -> str:
+    return json.dumps(_get_client().find_mobiles(inputs), indent=2)
+
+def _find_people(**params) -> str:
+    return json.dumps(_get_client().find_people(**params), indent=2)
+
+def _scrape_store_leads(platform: str = "shopify", country_code: str = "", total_leads: int = 1000, **kwargs) -> str:
+    return json.dumps(_get_client().scrape_store_leads(platform=platform, countryCode=country_code, totalLeads=total_leads), indent=2)
+
+def _query_lead_database(title: str = "", industry: str = "", state: str = "", city: str = "", limit: int = 50, **kwargs) -> str:
+    return json.dumps(_get_client().query_leads(title=title, industry=industry, state=state, city=city, limit=limit), indent=2)
+
+def _check_run_status(run_id: str, **kwargs) -> str:
+    return json.dumps(_get_client().status(run_id), indent=2)
+
+def _download_results(run_id: str, output_path: str = "", **kwargs) -> str:
+    return json.dumps(_get_client().download(run_id, output_path or None), indent=2)
+
+def _cancel_run(run_id: str, **kwargs) -> str:
+    return json.dumps(_get_client().cancel(run_id), indent=2)
+
+
+_HANDLERS = {
+    "check_wallet": _check_wallet,
+    "list_runs": _list_runs,
+    "scrape_apollo": _scrape_apollo,
+    "scrape_maps": _scrape_maps,
+    "validate_emails": _validate_emails,
+    "find_emails": _find_emails,
+    "find_mobiles": _find_mobiles,
+    "find_people": _find_people,
+    "scrape_store_leads": _scrape_store_leads,
+    "query_lead_database": _query_lead_database,
+    "check_run_status": _check_run_status,
+    "download_results": _download_results,
+    "cancel_run": _cancel_run,
+}
+
+
+def handle_tool_call(function_name: str, arguments: dict) -> str:
+    """Handle a tool call from OpenAI function calling.
+
+    Args:
+        function_name: The function name from the model's tool call.
+        arguments: The parsed arguments dict.
+
+    Returns:
+        JSON string result.
+    """
+    handler = _HANDLERS.get(function_name)
+    if not handler:
+        return json.dumps({"error": f"Unknown function: {function_name}"})
+    return handler(**arguments)
+
+
+def get_function_definitions() -> list[dict]:
+    """Return OpenAI function calling tool definitions.
+
+    Use with: openai.chat.completions.create(tools=get_function_definitions())
+    """
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": "check_wallet",
+                "description": "Check ScraperCity account balance, plan, and billing info. Call FIRST to verify credits.",
+                "parameters": {"type": "object", "properties": {}}
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "list_runs",
+                "description": "List recent scraper runs with status, lead counts, and costs.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "hours": {"type": "integer", "description": "Hours back to look (default 24)", "default": 24},
+                        "limit": {"type": "integer", "description": "Max runs to return (default 20)", "default": 20}
+                    }
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "scrape_apollo",
+                "description": "Scrape B2B contacts from Apollo.io using a search URL. Delivery takes up to 4 days.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "url": {"type": "string", "description": "Full Apollo.io search URL"},
+                        "count": {"type": "integer", "description": "Number of leads (min 500, max 50000)", "default": 1000}
+                    },
+                    "required": ["url"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "scrape_maps",
+                "description": "Scrape businesses from Google Maps with phones, emails, ratings.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string", "description": "Search keyword e.g. 'plumbers'"},
+                        "location": {"type": "string", "description": "City/area e.g. 'Denver, CO'"},
+                        "limit": {"type": "integer", "description": "Max places (default 500)", "default": 500}
+                    },
+                    "required": ["query", "location"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "validate_emails",
+                "description": "Validate email deliverability, catch-all detection, MX records.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "emails": {"type": "array", "items": {"type": "string"}, "description": "Emails to validate"}
+                    },
+                    "required": ["emails"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "find_emails",
+                "description": "Find business email addresses from name + company.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "contacts": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "first_name": {"type": "string"},
+                                    "last_name": {"type": "string"},
+                                    "domain": {"type": "string"},
+                                    "company_name": {"type": "string"}
+                                }
+                            },
+                            "description": "Contacts to find emails for"
+                        }
+                    },
+                    "required": ["contacts"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "find_mobiles",
+                "description": "Find mobile phone numbers from LinkedIn URLs or work emails.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "inputs": {"type": "array", "items": {"type": "string"}, "description": "LinkedIn URLs or work emails"}
+                    },
+                    "required": ["inputs"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "find_people",
+                "description": "Skip trace / people finder. Look up by name, email, phone, or address.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "array", "items": {"type": "string"}, "description": "Full names"},
+                        "email": {"type": "array", "items": {"type": "string"}, "description": "Emails"},
+                        "phone_number": {"type": "array", "items": {"type": "string"}, "description": "Phone numbers"}
+                    }
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "scrape_store_leads",
+                "description": "Get ecommerce store data (Shopify, WooCommerce, etc). Instant results.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "platform": {"type": "string", "description": "e.g. shopify, woocommerce", "default": "shopify"},
+                        "country_code": {"type": "string", "description": "e.g. US, GB"},
+                        "total_leads": {"type": "integer", "description": "Number of leads", "default": 1000}
+                    }
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "query_lead_database",
+                "description": "Query 4M+ B2B contacts instantly by title, industry, location. Requires $649/mo plan.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "title": {"type": "string", "description": "Job title filter"},
+                        "industry": {"type": "string", "description": "Company industry"},
+                        "state": {"type": "string", "description": "Person state"},
+                        "city": {"type": "string", "description": "Person city"},
+                        "limit": {"type": "integer", "description": "Results per page (max 100)", "default": 50}
+                    }
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "check_run_status",
+                "description": "Check status of a scraper run. Returns RUNNING/SUCCEEDED/FAILED.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "run_id": {"type": "string", "description": "The run ID"}
+                    },
+                    "required": ["run_id"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "download_results",
+                "description": "Download CSV results of a completed run.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "run_id": {"type": "string", "description": "The run ID"},
+                        "output_path": {"type": "string", "description": "File path to save CSV"}
+                    },
+                    "required": ["run_id"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "cancel_run",
+                "description": "Cancel a running scraper job.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "run_id": {"type": "string", "description": "The run ID to cancel"}
+                    },
+                    "required": ["run_id"]
+                }
+            }
+        }
+    ]
+
+
+def get_tools():
+    """Return tools compatible with OpenAI Agents SDK.
+
+    Usage:
+        from agents import Agent
+        from scrapercity.openai_tools import get_tools, init
+
+        init("your-api-key")
+        agent = Agent(name="Lead Gen", tools=get_tools())
+    """
+    try:
+        from agents import FunctionTool
+    except ImportError:
+        raise ImportError("Install openai-agents: pip install openai-agents")
+
+    tools = []
+    for defn in get_function_definitions():
+        fn = defn["function"]
+        handler = _HANDLERS[fn["name"]]
+        tools.append(FunctionTool(
+            name=fn["name"],
+            description=fn["description"],
+            params_json_schema=fn["parameters"],
+            on_invoke_tool=lambda ctx, args, h=handler: h(**json.loads(args))
+        ))
+    return tools

scrapercity-1.0.0/scrapercity.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: scrapercity
+Version: 1.0.0
+Summary: B2B lead generation for AI agents. 20+ tools: Apollo, Google Maps, email finder, skip trace, and more.
+Author-email: ScraperCity <support@scrapercity.com>
+License: MIT
+Project-URL: Homepage, https://scrapercity.com
+Project-URL: Documentation, https://scrapercity.com/agents/AGENT_DOCS.txt
+Project-URL: Repository, https://github.com/scrapercity/scrapercity-python
+Project-URL: Issues, https://github.com/scrapercity/scrapercity-python/issues
+Keywords: leads,apollo,scraping,b2b,email-finder,sales,lead-generation,google-maps,skip-trace,langchain,openai-agents,ai-agent,prospecting,contact-enrichment,email-validation,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.1; extra == "openai"
+Dynamic: license-file
+
+# ScraperCity Python SDK
+
+B2B lead generation for AI agents and Python developers. 20+ tools including Apollo scraping, Google Maps, email finder/validator, mobile lookup, skip trace, ecommerce store data, and more.
+
+## Install
+
+```bash
+pip install scrapercity
+```
+
+## Quick Start
+
+```python
+from scrapercity import ScraperCity
+
+sc = ScraperCity("your-api-key")
+
+# Check balance
+print(sc.wallet())
+
+# Scrape Google Maps
+result = sc.scrape_maps("plumbers", "Denver, CO", limit=200)
+print(result["runId"])
+
+# Query lead database (requires $649/mo plan)
+leads = sc.query_leads(title="CEO", state="California", limit=50)
+```
+
+## LangChain / LangGraph
+
+```python
+from scrapercity import langchain_tools
+from langgraph.prebuilt import create_react_agent
+
+tools = langchain_tools(api_key="your-key")
+agent = create_react_agent(llm, tools)
+result = agent.invoke({"messages": [{"role": "user", "content": "Find 50 CEOs in New York"}]})
+```
+
+## OpenAI Agents SDK
+
+```python
+from agents import Agent
+from scrapercity.openai_tools import get_tools, init
+
+init("your-api-key")
+agent = Agent(name="Lead Gen Agent", tools=get_tools())
+```
+
+## OpenAI Function Calling
+
+```python
+from scrapercity.openai_tools import get_function_definitions, handle_tool_call, init
+
+init("your-api-key")
+tools = get_function_definitions()
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=tools
+)
+
+# Handle the tool call
+for call in response.choices[0].message.tool_calls:
+    result = handle_tool_call(call.function.name, json.loads(call.function.arguments))
+```
+
+## Available Methods
+
+| Method | Description | Cost |
+|--------|-------------|------|
+| `scrape_apollo(url, count)` | B2B contacts from Apollo.io | $0.0039/lead |
+| `scrape_maps(query, location)` | Google Maps businesses | $0.01/place |
+| `validate_emails(emails)` | Email deliverability check | $0.0036/email |
+| `find_emails(contacts)` | Email from name + company | $0.05/contact |
+| `find_mobiles(inputs)` | Phone from LinkedIn/email | $0.25/input |
+| `find_people(**params)` | Skip trace by name/email/phone | $0.02/result |
+| `scrape_store_leads(**params)` | Shopify/WooCommerce stores | $0.0039/lead |
+| `scrape_builtwith(technology)` | Sites using a technology | $4.99/search |
+| `search_criminal_records(name)` | Background check | $1.00 if found |
+| `query_leads(**params)` | 4M+ B2B database (instant) | Included ($649 plan) |
+| `scrape_yelp(**params)` | Yelp business listings | varies |
+| `scrape_angi(keyword, zips)` | Angi service providers | varies |
+| `scrape_zillow_agents(location)` | Zillow real estate agents | varies |
+| `scrape_airbnb(**params)` | Airbnb host emails | varies |
+| `scrape_youtube_email(channels)` | YouTube channel emails | varies |
+
+## Authentication
+
+```bash
+export SCRAPERCITY_API_KEY="your-key"
+```
+
+Or pass directly: `ScraperCity(api_key="your-key")`
+
+Get your API key at [scrapercity.com](https://scrapercity.com)
+
+## License
+
+MIT

scrapercity-1.0.0/scrapercity.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+scrapercity/__init__.py
+scrapercity/client.py
+scrapercity/langchain_tools.py
+scrapercity/openai_tools.py
+scrapercity.egg-info/PKG-INFO
+scrapercity.egg-info/SOURCES.txt
+scrapercity.egg-info/dependency_links.txt
+scrapercity.egg-info/requires.txt
+scrapercity.egg-info/top_level.txt

scrapercity-1.0.0/scrapercity.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scrapercity-1.0.0/scrapercity.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[langchain]
+langchain-core>=0.2
+
+[openai]
+openai-agents>=0.1

scrapercity-1.0.0/scrapercity.egg-info/top_level.txt

@@ -0,0 +1 @@
+scrapercity

scrapercity-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+