apivault-skip-trace 0.1.0__py3-none-any.whl

apivault_skip_trace/__init__.py

@@ -0,0 +1,15 @@
+"""Skip Trace & People Finder — Python SDK.
+
+Usage:
+    from apivault_skip_trace import SkipTrace
+
+    st = SkipTrace("your_apify_token")
+    results = st.search_name("John Smith", location="Springfield, IL")
+    for person in results:
+        print(person["fullName"], person.get("phones"), person.get("emails"))
+"""
+
+from .client import SkipTrace
+
+__all__ = ["SkipTrace"]
+__version__ = "0.1.0"

apivault_skip_trace/client.py

@@ -0,0 +1,173 @@
+"""Skip Trace client — thin wrapper over the Apify Actor API."""
+
+from __future__ import annotations
+
+import requests
+from typing import Any
+
+ACTOR_ID = "apivault_labs~skip-trace-people-finder"
+API_BASE = "https://api.apify.com/v2"
+
+
+class SkipTrace:
+    """Skip Trace & People Finder.
+
+    Look up anyone in the US by name, address, phone, or email.
+    Returns current + past addresses, phone numbers, emails,
+    relatives, aliases, and a match-confidence score.
+
+    Pricing: $6.50 per 1,000 lookups (pay only for matches).
+
+    Args:
+        token: Your Apify API token. Get one free at https://apify.com
+        timeout: Max seconds to wait for the run (default 120).
+        memory_mb: Memory for the run (default 256).
+    """
+
+    def __init__(self, token: str, *, timeout: int = 120, memory_mb: int = 256):
+        if not token:
+            raise ValueError(
+                "Apify API token required. Get one at https://console.apify.com/account#/integrations"
+            )
+        self._token = token
+        self._timeout = timeout
+        self._memory = memory_mb
+
+    def _run(self, input_data: dict[str, Any]) -> list[dict]:
+        """Run the actor and return dataset items."""
+        url = f"{API_BASE}/acts/{ACTOR_ID}/run-sync-get-dataset-items"
+        params = {"token": self._token, "timeout": self._timeout, "memory": self._memory}
+        resp = requests.post(url, json=input_data, params=params, timeout=self._timeout + 30)
+        if resp.status_code == 402:
+            raise RuntimeError(
+                "Insufficient Apify credits. Top up at https://console.apify.com/billing"
+            )
+        if resp.status_code >= 400:
+            raise RuntimeError(f"Apify API error {resp.status_code}: {resp.text[:200]}")
+        return resp.json()
+
+    def search_name(
+        self,
+        name: str,
+        *,
+        location: str | None = None,
+        max_results: int = 10,
+        source: str = "auto",
+    ) -> list[dict]:
+        """Search by full name.
+
+        Args:
+            name: Full name, e.g. "Jane Doe".
+            location: Optional city/state/ZIP to narrow results,
+                      e.g. "Springfield, IL 62704".
+            max_results: Max people to return (1-100).
+            source: "auto" (recommended), "merge" (cross-reference), or "default".
+
+        Returns:
+            List of person dicts with addresses, phones, emails, relatives, etc.
+        """
+        query = f"{name}; {location}" if location else name
+        return self._run({
+            "name": [query],
+            "max_results": max_results,
+            "source": source,
+        })
+
+    def search_address(
+        self,
+        street: str,
+        city_state_zip: str,
+        *,
+        max_results: int = 10,
+        source: str = "auto",
+    ) -> list[dict]:
+        """Reverse address lookup — find people associated with an address.
+
+        Args:
+            street: Street address, e.g. "123 Main St".
+            city_state_zip: City, state ZIP, e.g. "Springfield, IL 62704".
+            max_results: Max people to return.
+
+        Returns:
+            List of person dicts.
+        """
+        return self._run({
+            "street_citystatezip": [f"{street}; {city_state_zip}"],
+            "max_results": max_results,
+            "source": source,
+        })
+
+    def search_phone(
+        self,
+        phone: str,
+        *,
+        max_results: int = 10,
+        source: str = "auto",
+    ) -> list[dict]:
+        """Reverse phone lookup.
+
+        Args:
+            phone: US phone number, e.g. "(202) 555-0182" or "2025550182".
+
+        Returns:
+            List of person dicts.
+        """
+        return self._run({
+            "phone_number": [phone],
+            "max_results": max_results,
+            "source": source,
+        })
+
+    def search_email(
+        self,
+        email: str,
+        *,
+        max_results: int = 10,
+        source: str = "auto",
+    ) -> list[dict]:
+        """Reverse email lookup — find the person behind an email.
+
+        Args:
+            email: Email address, e.g. "jane.doe@gmail.com".
+
+        Returns:
+            List of person dicts.
+        """
+        return self._run({
+            "email": [email],
+            "max_results": max_results,
+            "source": source,
+        })
+
+    def bulk_search(
+        self,
+        *,
+        names: list[str] | None = None,
+        addresses: list[str] | None = None,
+        phones: list[str] | None = None,
+        emails: list[str] | None = None,
+        max_results: int = 100,
+        source: str = "auto",
+    ) -> list[dict]:
+        """Bulk lookup — multiple queries of any type in one call.
+
+        Args:
+            names: List of "Name; Location" strings.
+            addresses: List of "Street; City, ST ZIP" strings.
+            phones: List of phone numbers.
+            emails: List of emails.
+            max_results: Max per query.
+
+        Returns:
+            Combined list of all person dicts.
+        """
+        input_data: dict[str, Any] = {"max_results": max_results, "source": source}
+        if names:
+            input_data["name"] = names
+        if addresses:
+            input_data["street_citystatezip"] = addresses
+        if phones:
+            input_data["phone_number"] = phones
+        if emails:
+            input_data["email"] = emails
+        return self._run(input_data)

apivault_skip_trace-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: apivault-skip-trace
+Version: 0.1.0
+Summary: Skip Trace & People Finder — search by name, address, phone or email. Returns addresses, phones, emails, relatives, aliases. Powered by Apify.
+Author: apivault-labs
+License: MIT
+Project-URL: Homepage, https://apify.com/apivault_labs/skip-trace-people-finder
+Project-URL: Documentation, https://github.com/apivault-labs/apivault-skip-trace
+Project-URL: Repository, https://github.com/apivault-labs/apivault-skip-trace
+Project-URL: Issues, https://github.com/apivault-labs/apivault-skip-trace/issues
+Keywords: skip-trace,people-search,reverse-phone,reverse-address,public-records,lead-generation,real-estate,apify
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# apivault-skip-trace
+
+Skip Trace & People Finder — Python SDK. Search by name, address, phone, or email. Returns addresses, phones, emails, relatives, aliases, and a match-confidence score.
+
+**US public records. Real-time. No subscription. $6.50/1K lookups.**
+
+[![PyPI](https://img.shields.io/pypi/v/apivault-skip-trace)](https://pypi.org/project/apivault-skip-trace/)
+[![Python](https://img.shields.io/pypi/pyversions/apivault-skip-trace)](https://pypi.org/project/apivault-skip-trace/)
+
+## Install
+
+```bash
+pip install apivault-skip-trace
+```
+
+## Quick Start
+
+```python
+from apivault_skip_trace import SkipTrace
+
+st = SkipTrace("your_apify_token")  # get token at apify.com/account#/integrations
+
+# Search by name
+results = st.search_name("John Smith", location="Springfield, IL")
+for person in results:
+    print(person["fullName"], person.get("phones"), person.get("emails"))
+
+# Reverse phone lookup
+results = st.search_phone("(202) 555-0182")
+
+# Reverse address lookup
+results = st.search_address("123 Main St", "Springfield, IL 62704")
+
+# Reverse email lookup
+results = st.search_email("jane.doe@gmail.com")
+
+# Bulk (mixed queries in one call)
+results = st.bulk_search(
+    names=["John Smith; IL", "Jane Doe; NY"],
+    phones=["2025550182"],
+    emails=["test@example.com"],
+)
+```
+
+## What You Get Back
+
+Each person dict contains:
+
+| Field | Description |
+|---|---|
+| `fullName` | Full name |
+| `firstName`, `lastName` | Parsed name components |
+| `age`, `birthYear` | Age / birth year when available |
+| `currentAddress` | Most recent address |
+| `addresses` | All known addresses (current + past) |
+| `phones` | Phone numbers with type (mobile/landline) |
+| `emails` | Email addresses |
+| `relatives` | Names of associated people |
+| `aliases` | Also known as / maiden names |
+| `matchScore` | Confidence score (0-100) |
+| `bestEmail` | Top email (verified deliverable via MX) |
+
+## Pricing
+
+- **$6.50 per 1,000 lookups** (Apify pay-per-event)
+- Pay only for matches (empty results are free)
+- No subscription, no monthly minimum
+- Get $5 free credits at [apify.com](https://apify.com/pricing)
+
+## Get Your API Token
+
+1. Sign up at [apify.com](https://apify.com) (free)
+2. Go to [Settings → Integrations](https://console.apify.com/account#/integrations)
+3. Copy your API token
+
+## Use Cases
+
+- **Real estate** — find property owners, skip trace vacant homes
+- **Debt collection** — locate debtors with updated contact info
+- **Sales prospecting** — enrich leads with phone + email
+- **Background checks** — verify identity with addresses + relatives
+- **Fraud prevention** — cross-reference provided info against public records
+
+## Links
+
+- [Apify Store](https://apify.com/apivault_labs/skip-trace-people-finder) — run in browser, no code
+- [API Docs](https://docs.apify.com/api/v2) — REST API reference
+- [n8n Node](https://www.npmjs.com/package/n8n-nodes-apivault-skip-trace) — no-code automation
+
+## License
+
+MIT

apivault_skip_trace-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+apivault_skip_trace/__init__.py,sha256=bSw8yZjlo4Shp9-TZjEZsnODNiDTm4b-A18zW1DlUYU,413
+apivault_skip_trace/client.py,sha256=iyPgBocp54w6yfXTI6HFksHaPKlK6ARVGuE1eQXSuw8,5540
+apivault_skip_trace-0.1.0.dist-info/licenses/LICENSE,sha256=EtTrdubDHfHJzfIbw66oo9Fc0uNSOJKdZajcLAgqjSI,1091
+apivault_skip_trace-0.1.0.dist-info/METADATA,sha256=NYwRJPQcoDe59X_orWZIfF5kVvNZ5gtPLSoc5soU-JY,4385
+apivault_skip_trace-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+apivault_skip_trace-0.1.0.dist-info/top_level.txt,sha256=O_7Dbq8JxPZ6lgAQcsUif5zBwko0Vg9CsJjMtYukLsM,20
+apivault_skip_trace-0.1.0.dist-info/RECORD,,

apivault_skip_trace-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

apivault_skip_trace-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apivault-labs
+
+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.

apivault_skip_trace-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+apivault_skip_trace