🕵️ Contact Finder SDK

A robust, high-concurrency async Python SDK for the Website Contact Finder API. Effortlessly scrape emails, phone numbers, social media links, and rich company metadata from thousands of websites.

✨ Key Features

• 🚀 Async & High Concurrency: Processes hundreds of URLs simultaneously using asyncio and aiohttp.
• 🗂️ Multi-Project Isolation: Run multiple scrapers at once. Each project_name gets its own isolated data folder.
• 🔄 Smart Deduplication & Caching: Automatically skips URLs it has already scraped and resumes where it left off.
• 💾 Auto-Storage: Automatically saves results to structured .jsonl and .csv files.
• 🪝 Real-time Callbacks: Pass an on_success function to process data instantly as it arrives.

📦 Installation

pip install contact-finder-sdk

🔑 Prerequisites

You need a RapidAPI key to use this SDK.

1. Go to the Website Contact Finder API on RapidAPI.
2. Subscribe to the API and copy your X-RapidAPI-Key.

🚀 Quick Start (The Simplest Way)

The easiest way to use the SDK is to pass a Python list of URLs directly.

from contact_finder_sdk import ContactFinder

# Define what happens when a URL is successfully scraped
def handle_result(data):
    url = data.get("url") or data.get("data", {}).get("url")
    print(f"✅ Successfully scraped: {url}")

# Initialize the SDK
finder = ContactFinder(
    api_key="YOUR_RAPIDAPI_KEY_HERE", 
    project_name="quick_test"
)

# Run the scraper
finder.run(
    urls=["https://rapidapi.com", "https://github.com"],
    parse_mode="contact",       # Extracts emails, phones, and socials
    on_success=handle_result,   # Triggered for every success
    auto_store=True             # Saves results to a local 'data/' folder
)

📂 Reading from a CSV File

If you have a large list of URLs, pass a CSV file instead. The SDK will automatically read the file, extract the URLs, and process them.

finder.run(
    file_path="my_urls.csv",    # Path to your CSV file
    url_field_name="url",       # The name of the column containing the URLs
    parse_mode="full",          # Gets contact + profile + visuals + meta
    auto_store=True
)

🗂️ Multi-Project Isolation

One of the most powerful features is Project Isolation. If you are managing multiple clients or campaigns, simply assign a different project_name to each instance.

The SDK will automatically create separate, isolated folders for each project inside a local data/ directory. Their caches, CSVs, and logs will never mix.

# Instance 1: Client A
finder_a = ContactFinder(api_key="YOUR_KEY", project_name="client_A")
finder_a.run(urls=["https://client-a.com"], auto_store=True)
# Saves to: ./data/client_A/

# Instance 2: Client B
finder_b = ContactFinder(api_key="YOUR_KEY", project_name="client_B")
finder_b.run(urls=["https://client-b.com"], auto_store=True)
# Saves to: ./data/client_B/

⚙️ Configuration Parameters

When calling finder.run(), you can customize the behavior:

🔍 Parse Modes Explained

• "raw": Returns the exact, untouched JSON dictionary from the RapidAPI response.
• "contact": Returns a flattened dictionary containing only core contact info (Emails, Phones, Social Media links).
• "full": Returns a massive flattened dictionary containing Contact info + Company Profile + Visuals + Meta tags.

💾 Output Files

When auto_store=True, the SDK generates a data/<project_name>/ folder containing:

Note: The SDK is resumable. If your script crashes, simply run it again. It will read raw.jsonl, skip the URLs it already finished, and pick up exactly where it left off!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.