AD-SearchAPI 1.0.0__tar.gz

ad_searchapi-1.0.0/AD_SearchAPI.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: AD-SearchAPI
+Version: 1.0.0
+Summary: A Python client library for the Search API
+Home-page: https://github.com/AntiChrist-Coder/search_api_library
+Author: Search API Team
+Author-email: support@search-api.dev
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: phonenumbers>=8.13.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: typing-extensions>=4.7.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Search API Python Client
+
+A Python client library for the Search API, providing easy access to email, phone, and domain search functionality.
+Acquire your API-Key through @ADSearchEngine_bot on Telegram
+
+## Installation
+
+```bash
+pip install search-api
+```
+
+## Quick Start
+
+```python
+from search_api import SearchAPI
+
+# Initialize the client with your API key
+client = SearchAPI(api_key="your_api_key")
+
+# Search by email
+result = client.search_email("example@domain.com", include_house_value=True)
+print(result)
+
+# Search by phone
+result = client.search_phone("+1234567890", include_extra_info=True)
+print(result)
+
+# Search by domain
+result = client.search_domain("example.com")
+print(result)
+```
+
+## Features
+
+- Email search with optional house value and extra info
+- Phone number search with validation and formatting
+- Domain search with comprehensive results
+- Automatic caching of results
+- Rate limiting and retry handling
+- Type hints and comprehensive documentation
+
+## Advanced Usage
+
+### Configuration
+
+```python
+from search_api import SearchAPI, SearchAPIConfig
+
+config = SearchAPIConfig(
+    api_key="your_api_key",
+    cache_ttl=3600,  # Cache results for 1 hour
+    max_retries=3,
+    timeout=30,
+    base_url="https://search-api.dev"
+)
+
+client = SearchAPI(config=config)
+```
+
+### Error Handling
+
+```python
+from search_api import SearchAPIError
+
+try:
+    result = client.search_email("example@domain.com")
+except SearchAPIError as e:
+    print(f"Error: {e.message}")
+    print(f"Status code: {e.status_code}")
+```
+
+## API Reference
+
+### SearchAPI
+
+Main client class for interacting with the Search API.
+
+#### Methods
+
+- `search_email(email: str, include_house_value: bool = False, include_extra_info: bool = False) -> Dict`
+- `search_phone(phone: str, include_house_value: bool = False, include_extra_info: bool = False) -> Dict`
+- `search_domain(domain: str) -> Dict`
+
+### SearchAPIConfig
+
+Configuration class for customizing client behavior.
+
+#### Parameters
+
+- `api_key: str` - Your API key
+- `cache_ttl: int` - Cache time-to-live in seconds
+- `max_retries: int` - Maximum number of retry attempts
+- `timeout: int` - Request timeout in seconds
+- `base_url: str` - API base URL
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

ad_searchapi-1.0.0/AD_SearchAPI.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+setup.py
+AD_SearchAPI.egg-info/PKG-INFO
+AD_SearchAPI.egg-info/SOURCES.txt
+AD_SearchAPI.egg-info/dependency_links.txt
+AD_SearchAPI.egg-info/requires.txt
+AD_SearchAPI.egg-info/top_level.txt
+search_api/__init__.py
+search_api/client.py
+search_api/exceptions.py
+search_api/models.py
+tests/test_client.py

ad_searchapi-1.0.0/AD_SearchAPI.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ad_searchapi-1.0.0/AD_SearchAPI.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.31.0
+phonenumbers>=8.13.0
+python-dateutil>=2.8.2
+cachetools>=5.3.0
+typing-extensions>=4.7.0

ad_searchapi-1.0.0/AD_SearchAPI.egg-info/top_level.txt

@@ -0,0 +1 @@
+search_api

ad_searchapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Search API Team
+
+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. 

ad_searchapi-1.0.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: AD-SearchAPI
+Version: 1.0.0
+Summary: A Python client library for the Search API
+Home-page: https://github.com/AntiChrist-Coder/search_api_library
+Author: Search API Team
+Author-email: support@search-api.dev
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: phonenumbers>=8.13.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: typing-extensions>=4.7.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Search API Python Client
+
+A Python client library for the Search API, providing easy access to email, phone, and domain search functionality.
+Acquire your API-Key through @ADSearchEngine_bot on Telegram
+
+## Installation
+
+```bash
+pip install search-api
+```
+
+## Quick Start
+
+```python
+from search_api import SearchAPI
+
+# Initialize the client with your API key
+client = SearchAPI(api_key="your_api_key")
+
+# Search by email
+result = client.search_email("example@domain.com", include_house_value=True)
+print(result)
+
+# Search by phone
+result = client.search_phone("+1234567890", include_extra_info=True)
+print(result)
+
+# Search by domain
+result = client.search_domain("example.com")
+print(result)
+```
+
+## Features
+
+- Email search with optional house value and extra info
+- Phone number search with validation and formatting
+- Domain search with comprehensive results
+- Automatic caching of results
+- Rate limiting and retry handling
+- Type hints and comprehensive documentation
+
+## Advanced Usage
+
+### Configuration
+
+```python
+from search_api import SearchAPI, SearchAPIConfig
+
+config = SearchAPIConfig(
+    api_key="your_api_key",
+    cache_ttl=3600,  # Cache results for 1 hour
+    max_retries=3,
+    timeout=30,
+    base_url="https://search-api.dev"
+)
+
+client = SearchAPI(config=config)
+```
+
+### Error Handling
+
+```python
+from search_api import SearchAPIError
+
+try:
+    result = client.search_email("example@domain.com")
+except SearchAPIError as e:
+    print(f"Error: {e.message}")
+    print(f"Status code: {e.status_code}")
+```
+
+## API Reference
+
+### SearchAPI
+
+Main client class for interacting with the Search API.
+
+#### Methods
+
+- `search_email(email: str, include_house_value: bool = False, include_extra_info: bool = False) -> Dict`
+- `search_phone(phone: str, include_house_value: bool = False, include_extra_info: bool = False) -> Dict`
+- `search_domain(domain: str) -> Dict`
+
+### SearchAPIConfig
+
+Configuration class for customizing client behavior.
+
+#### Parameters
+
+- `api_key: str` - Your API key
+- `cache_ttl: int` - Cache time-to-live in seconds
+- `max_retries: int` - Maximum number of retry attempts
+- `timeout: int` - Request timeout in seconds
+- `base_url: str` - API base URL
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

ad_searchapi-1.0.0/README.md

@@ -0,0 +1,102 @@
+# Search API Python Client
+
+A Python client library for the Search API, providing easy access to email, phone, and domain search functionality.
+Acquire your API-Key through @ADSearchEngine_bot on Telegram
+
+## Installation
+
+```bash
+pip install search-api
+```
+
+## Quick Start
+
+```python
+from search_api import SearchAPI
+
+# Initialize the client with your API key
+client = SearchAPI(api_key="your_api_key")
+
+# Search by email
+result = client.search_email("example@domain.com", include_house_value=True)
+print(result)
+
+# Search by phone
+result = client.search_phone("+1234567890", include_extra_info=True)
+print(result)
+
+# Search by domain
+result = client.search_domain("example.com")
+print(result)
+```
+
+## Features
+
+- Email search with optional house value and extra info
+- Phone number search with validation and formatting
+- Domain search with comprehensive results
+- Automatic caching of results
+- Rate limiting and retry handling
+- Type hints and comprehensive documentation
+
+## Advanced Usage
+
+### Configuration
+
+```python
+from search_api import SearchAPI, SearchAPIConfig
+
+config = SearchAPIConfig(
+    api_key="your_api_key",
+    cache_ttl=3600,  # Cache results for 1 hour
+    max_retries=3,
+    timeout=30,
+    base_url="https://search-api.dev"
+)
+
+client = SearchAPI(config=config)
+```
+
+### Error Handling
+
+```python
+from search_api import SearchAPIError
+
+try:
+    result = client.search_email("example@domain.com")
+except SearchAPIError as e:
+    print(f"Error: {e.message}")
+    print(f"Status code: {e.status_code}")
+```
+
+## API Reference
+
+### SearchAPI
+
+Main client class for interacting with the Search API.
+
+#### Methods
+
+- `search_email(email: str, include_house_value: bool = False, include_extra_info: bool = False) -> Dict`
+- `search_phone(phone: str, include_house_value: bool = False, include_extra_info: bool = False) -> Dict`
+- `search_domain(domain: str) -> Dict`
+
+### SearchAPIConfig
+
+Configuration class for customizing client behavior.
+
+#### Parameters
+
+- `api_key: str` - Your API key
+- `cache_ttl: int` - Cache time-to-live in seconds
+- `max_retries: int` - Maximum number of retry attempts
+- `timeout: int` - Request timeout in seconds
+- `base_url: str` - API base URL
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

ad_searchapi-1.0.0/search_api/__init__.py

@@ -0,0 +1,22 @@
+from .client import SearchAPI, SearchAPIConfig
+from .exceptions import SearchAPIError
+from .models import (
+    EmailSearchResult,
+    PhoneSearchResult,
+    DomainSearchResult,
+    Address,
+    PhoneNumber,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "SearchAPI",
+    "SearchAPIConfig",
+    "SearchAPIError",
+    "EmailSearchResult",
+    "PhoneSearchResult",
+    "DomainSearchResult",
+    "Address",
+    "PhoneNumber",
+] 

ad_searchapi-1.0.0/search_api/client.py

@@ -0,0 +1,436 @@
+import json
+import re
+from datetime import date
+from decimal import Decimal
+from typing import Dict, List, Optional, Union
+from urllib.parse import urljoin
+
+import phonenumbers
+import requests
+from cachetools import TTLCache
+from dateutil.parser import parse
+
+from .exceptions import (
+    AuthenticationError,
+    InsufficientBalanceError,
+    RateLimitError,
+    SearchAPIError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    Address,
+    DomainSearchResult,
+    EmailSearchResult,
+    PhoneNumber,
+    PhoneSearchResult,
+    SearchAPIConfig,
+)
+
+# Major email domains that are not allowed for domain search
+MAJOR_DOMAINS = {
+    "gmail.com",
+    "yahoo.com",
+    "outlook.com",
+    "hotmail.com",
+    "aol.com",
+    "icloud.com",
+    "live.com",
+    "msn.com",
+    "comcast.net",
+    "me.com",
+    "mac.com",
+    "att.net",
+    "verizon.net",
+    "protonmail.com",
+    "zoho.com",
+    "yandex.com",
+    "mail.com",
+    "gmx.com",
+    "rocketmail.com",
+    "yahoo.co.uk",
+    "btinternet.com",
+    "bellsouth.net",
+}
+
+# Street type mapping
+STREET_TYPE_MAP = {
+    "st": "Street",
+    "ave": "Avenue",
+    "blvd": "Boulevard",
+    "rd": "Road",
+    "ln": "Lane",
+    "dr": "Drive",
+    "ct": "Court",
+    "ter": "Terrace",
+    "pl": "Place",
+    "way": "Way",
+    "pkwy": "Parkway",
+    "cir": "Circle",
+    "sq": "Square",
+    "hwy": "Highway",
+    "bend": "Bend",
+    "cove": "Cove",
+}
+
+# State abbreviations mapping
+STATE_ABBREVIATIONS = {
+    "al": "AL",
+    "ak": "AK",
+    "az": "AZ",
+    "ar": "AR",
+    "ca": "CA",
+    "co": "CO",
+    "ct": "CT",
+    "de": "DE",
+    "fl": "FL",
+    "ga": "GA",
+    "hi": "HI",
+    "id": "ID",
+    "il": "IL",
+    "in": "IN",
+    "ia": "IA",
+    "ks": "KS",
+    "ky": "KY",
+    "la": "LA",
+    "me": "ME",
+    "md": "MD",
+    "ma": "MA",
+    "mi": "MI",
+    "mn": "MN",
+    "ms": "MS",
+    "mo": "MO",
+    "mt": "MT",
+    "ne": "NE",
+    "nv": "NV",
+    "nh": "NH",
+    "nj": "NJ",
+    "nm": "NM",
+    "ny": "NY",
+    "nc": "NC",
+    "nd": "ND",
+    "oh": "OH",
+    "ok": "OK",
+    "or": "OR",
+    "pa": "PA",
+    "ri": "RI",
+    "sc": "SC",
+    "sd": "SD",
+    "tn": "TN",
+    "tx": "TX",
+    "ut": "UT",
+    "vt": "VT",
+    "va": "VA",
+    "wa": "WA",
+    "wv": "WV",
+    "wi": "WI",
+    "wy": "WY",
+}
+
+
+class SearchAPI:
+    """Main client for interacting with the Search API."""
+
+    def __init__(self, api_key: str = None, config: SearchAPIConfig = None):
+        """Initialize the Search API client.
+
+        Args:
+            api_key: Your API key
+            config: Optional configuration object
+        """
+        if config is None:
+            if api_key is None:
+                raise ValueError("Either api_key or config must be provided")
+            config = SearchAPIConfig(api_key=api_key)
+
+        self.config = config
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "User-Agent": config.user_agent,
+                "Accept": "application/json",
+            }
+        )
+        self.cache = TTLCache(maxsize=1000, ttl=config.cache_ttl)
+
+    def _make_request(
+        self,
+        endpoint: str,
+        params: Optional[Dict] = None,
+        method: str = "GET",
+        data: Optional[Dict] = None,
+    ) -> Dict:
+        """Make a request to the Search API.
+
+        Args:
+            endpoint: API endpoint
+            params: Query parameters
+            method: HTTP method
+            data: Request body data
+
+        Returns:
+            API response as dictionary
+
+        Raises:
+            SearchAPIError: If the request fails
+        """
+        url = urljoin(self.config.base_url, endpoint)
+        params = params or {}
+        params["api_key"] = self.config.api_key
+
+        try:
+            response = self.session.request(
+                method,
+                url,
+                params=params,
+                json=data,
+                timeout=self.config.timeout,
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 401:
+                raise AuthenticationError("Invalid API key", e.response.status_code)
+            elif e.response.status_code == 402:
+                raise InsufficientBalanceError(
+                    "Insufficient balance", e.response.status_code
+                )
+            elif e.response.status_code == 429:
+                raise RateLimitError("Rate limit exceeded", e.response.status_code)
+            elif e.response.status_code >= 500:
+                raise ServerError("Server error", e.response.status_code)
+            else:
+                raise SearchAPIError(
+                    f"HTTP error: {e.response.text}",
+                    e.response.status_code,
+                    e.response.json() if e.response.text else None,
+                )
+        except requests.exceptions.RequestException as e:
+            raise SearchAPIError(f"Request error: {str(e)}")
+
+    def _format_address(self, address_str: str) -> str:
+        """Format an address string according to standard conventions.
+
+        Args:
+            address_str: Raw address string
+
+        Returns:
+            Formatted address string
+        """
+        parts = [part.strip() for part in address_str.split(",") if part.strip()]
+        formatted_parts = []
+
+        for part in parts:
+            words = part.split()
+            for i, word in enumerate(words):
+                word_lower = word.lower()
+                words[i] = STREET_TYPE_MAP.get(word_lower, word.title())
+            formatted_parts.append(" ".join(words))
+
+        if formatted_parts:
+            last_part = formatted_parts[-1].split()
+            if len(last_part) > 1 and last_part[-1].isdigit():
+                state = last_part[-2].lower()
+                if state in STATE_ABBREVIATIONS:
+                    last_part[-2] = STATE_ABBREVIATIONS[state]
+                formatted_parts[-1] = " ".join(last_part)
+            elif last_part:
+                state = last_part[-1].lower()
+                if state in STATE_ABBREVIATIONS:
+                    last_part[-1] = STATE_ABBREVIATIONS[state]
+                    formatted_parts[-1] = " ".join(last_part)
+
+        return ", ".join(formatted_parts)
+
+    def _parse_address(self, address_data: Union[str, Dict]) -> Address:
+        """Parse address data into an Address object.
+
+        Args:
+            address_data: Address data as string or dictionary
+
+        Returns:
+            Address object
+        """
+        if isinstance(address_data, str):
+            return Address(street=self._format_address(address_data))
+        else:
+            return Address(
+                street=address_data.get("street", ""),
+                city=address_data.get("city"),
+                state=address_data.get("state"),
+                postal_code=address_data.get("postal_code"),
+                country=address_data.get("country"),
+                zestimate=Decimal(str(address_data["zestimate"]))
+                if "zestimate" in address_data
+                else None,
+            )
+
+    def _parse_phone_number(self, phone_str: str) -> PhoneNumber:
+        """Parse and validate a phone number.
+
+        Args:
+            phone_str: Phone number string
+
+        Returns:
+            PhoneNumber object
+        """
+        try:
+            number = phonenumbers.parse(phone_str, "US")
+            is_valid = phonenumbers.is_valid_number(number)
+            formatted = phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164)
+            return PhoneNumber(number=formatted, is_valid=is_valid)
+        except phonenumbers.NumberParseException:
+            return PhoneNumber(number=phone_str, is_valid=False)
+
+    def search_email(
+        self, email: str, include_house_value: bool = False, include_extra_info: bool = False
+    ) -> EmailSearchResult:
+        """Search for information by email address.
+
+        Args:
+            email: Email address to search
+            include_house_value: Whether to include house value information
+            include_extra_info: Whether to include extra information
+
+        Returns:
+            EmailSearchResult object
+
+        Raises:
+            ValidationError: If the email is invalid
+            SearchAPIError: If the request fails
+        """
+        if not re.match(r"[^@]+@[^@]+\.[^@]+", email):
+            raise ValidationError("Invalid email format")
+
+        cache_key = f"email_{email}_{include_house_value}_{include_extra_info}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        params = {
+            "email": email,
+            "house_value": str(include_house_value).lower(),
+            "extra_info": str(include_extra_info).lower(),
+        }
+
+        response = self._make_request("search.php", params)
+        if "error" in response:
+            raise SearchAPIError(response["error"])
+
+        result = EmailSearchResult(
+            email=email,
+            name=response.get("name"),
+            dob=parse(response["dob"]).date() if response.get("dob") else None,
+            addresses=[
+                self._parse_address(addr) for addr in response.get("addresses", [])
+            ],
+            phone_numbers=[
+                self._parse_phone_number(num) for num in response.get("numbers", [])
+            ],
+            extra_info=response.get("extra_info"),
+        )
+
+        self.cache[cache_key] = result
+        return result
+
+    def search_phone(
+        self, phone: str, include_house_value: bool = False, include_extra_info: bool = False
+    ) -> PhoneSearchResult:
+        """Search for information by phone number.
+
+        Args:
+            phone: Phone number to search
+            include_house_value: Whether to include house value information
+            include_extra_info: Whether to include extra information
+
+        Returns:
+            PhoneSearchResult object
+
+        Raises:
+            ValidationError: If the phone number is invalid
+            SearchAPIError: If the request fails
+        """
+        phone_number = self._parse_phone_number(phone)
+        if not phone_number.is_valid:
+            raise ValidationError("Invalid phone number format")
+
+        cache_key = f"phone_{phone}_{include_house_value}_{include_extra_info}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        params = {
+            "phone": phone,
+            "house_value": str(include_house_value).lower(),
+            "extra_info": str(include_extra_info).lower(),
+        }
+
+        response = self._make_request("search.php", params)
+        if "error" in response:
+            raise SearchAPIError(response["error"])
+
+        result = PhoneSearchResult(
+            phone=phone_number,
+            name=response.get("name"),
+            dob=parse(response["dob"]).date() if response.get("dob") else None,
+            addresses=[
+                self._parse_address(addr) for addr in response.get("addresses", [])
+            ],
+            phone_numbers=[
+                self._parse_phone_number(num) for num in response.get("numbers", [])
+            ],
+            extra_info=response.get("extra_info"),
+        )
+
+        self.cache[cache_key] = result
+        return result
+
+    def search_domain(self, domain: str) -> DomainSearchResult:
+        """Search for information by domain name.
+
+        Args:
+            domain: Domain name to search
+
+        Returns:
+            DomainSearchResult object
+
+        Raises:
+            ValidationError: If the domain is invalid or is a major domain
+            SearchAPIError: If the request fails
+        """
+        domain = domain.lower().strip()
+        if not re.match(r"^[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,}$", domain):
+            raise ValidationError("Invalid domain format")
+
+        if domain in MAJOR_DOMAINS:
+            raise ValidationError("Searching major domains is not allowed")
+
+        cache_key = f"domain_{domain}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        params = {"domain": domain}
+        response = self._make_request("search.php", params)
+        if "error" in response:
+            raise SearchAPIError(response["error"])
+
+        results = []
+        for item in response.get("results", []):
+            email_result = EmailSearchResult(
+                email=item["email"],
+                name=item.get("name"),
+                addresses=[
+                    self._parse_address(addr) for addr in item.get("addresses", [])
+                ],
+                phone_numbers=[
+                    self._parse_phone_number(num) for num in item.get("phone_numbers", [])
+                ],
+            )
+            results.append(email_result)
+
+        result = DomainSearchResult(
+            domain=domain,
+            results=results,
+            total_results=len(results),
+        )
+
+        self.cache[cache_key] = result
+        return result 

ad_searchapi-1.0.0/search_api/exceptions.py

@@ -0,0 +1,46 @@
+from typing import Optional
+
+
+class SearchAPIError(Exception):
+    """Base exception for all Search API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response: Optional[dict] = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        super().__init__(self.message)
+
+
+class AuthenticationError(SearchAPIError):
+    """Raised when there are authentication issues."""
+
+    pass
+
+
+class ValidationError(SearchAPIError):
+    """Raised when input validation fails."""
+
+    pass
+
+
+class RateLimitError(SearchAPIError):
+    """Raised when rate limit is exceeded."""
+
+    pass
+
+
+class InsufficientBalanceError(SearchAPIError):
+    """Raised when API key has insufficient balance."""
+
+    pass
+
+
+class ServerError(SearchAPIError):
+    """Raised when the server returns an error."""
+
+    pass 

ad_searchapi-1.0.0/search_api/models.py

@@ -0,0 +1,87 @@
+from dataclasses import dataclass, field
+from datetime import date
+from typing import List, Optional, Union
+from decimal import Decimal
+
+
+@dataclass
+class Address:
+    """Represents a physical address with optional Zestimate value."""
+
+    street: str
+    city: Optional[str] = None
+    state: Optional[str] = None
+    postal_code: Optional[str] = None
+    country: Optional[str] = None
+    zestimate: Optional[Decimal] = None
+
+    def __str__(self) -> str:
+        parts = [self.street]
+        if self.city:
+            parts.append(self.city)
+        if self.state:
+            parts.append(self.state)
+        if self.postal_code:
+            parts.append(self.postal_code)
+        if self.country:
+            parts.append(self.country)
+        return ", ".join(parts)
+
+
+@dataclass
+class PhoneNumber:
+    """Represents a phone number with validation."""
+
+    number: str
+    country_code: str = "US"
+    is_valid: bool = True
+
+    def __str__(self) -> str:
+        return self.number
+
+
+@dataclass
+class BaseSearchResult:
+    """Base class for all search results."""
+
+    name: Optional[str] = None
+    dob: Optional[date] = None
+    addresses: List[Address] = field(default_factory=list)
+    phone_numbers: List[PhoneNumber] = field(default_factory=list)
+
+
+@dataclass
+class EmailSearchResult(BaseSearchResult):
+    """Result from email search."""
+
+    email: str
+    extra_info: Optional[dict] = None
+
+
+@dataclass
+class PhoneSearchResult(BaseSearchResult):
+    """Result from phone search."""
+
+    phone: PhoneNumber
+    extra_info: Optional[dict] = None
+
+
+@dataclass
+class DomainSearchResult:
+    """Result from domain search."""
+
+    domain: str
+    results: List[EmailSearchResult] = field(default_factory=list)
+    total_results: int = 0
+
+
+@dataclass
+class SearchAPIConfig:
+    """Configuration for the Search API client."""
+
+    api_key: str
+    cache_ttl: int = 3600  # 1 hour
+    max_retries: int = 3
+    timeout: int = 30
+    base_url: str = "https://search-api.dev"
+    user_agent: str = "SearchAPI-Python/1.0.0" 

ad_searchapi-1.0.0/setup.cfg

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

ad_searchapi-1.0.0/setup.py

@@ -0,0 +1,32 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="AD-SearchAPI",
+    version="1.0.0",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.31.0",
+        "phonenumbers>=8.13.0",
+        "python-dateutil>=2.8.2",
+        "cachetools>=5.3.0",
+        "typing-extensions>=4.7.0",
+    ],
+    author="Search API Team",
+    author_email="support@search-api.dev",
+    description="A Python client library for the Search API",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/AntiChrist-Coder/search_api_library",
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    python_requires=">=3.7",
+) 

ad_searchapi-1.0.0/tests/test_client.py

@@ -0,0 +1,179 @@
+import pytest
+from unittest.mock import Mock, patch
+from datetime import date
+from decimal import Decimal
+
+from search_api import SearchAPI, SearchAPIConfig
+from search_api.exceptions import (
+    AuthenticationError,
+    ValidationError,
+    SearchAPIError,
+)
+from search_api.models import Address, PhoneNumber
+
+
+@pytest.fixture
+def client():
+    return SearchAPI(api_key="test_api_key")
+
+
+@pytest.fixture
+def mock_response():
+    return {
+        "name": "John Doe",
+        "dob": "1990-01-01",
+        "addresses": [
+            "123 Main St, New York, NY 10001",
+            {
+                "street": "456 Park Ave",
+                "city": "New York",
+                "state": "NY",
+                "postal_code": "10022",
+                "zestimate": 1500000,
+            },
+        ],
+        "numbers": ["+12125551234", "+12125556789"],
+    }
+
+
+def test_init_with_api_key():
+    client = SearchAPI(api_key="test_api_key")
+    assert client.config.api_key == "test_api_key"
+    assert client.config.base_url == "https://search-api.dev"
+
+
+def test_init_with_config():
+    config = SearchAPIConfig(
+        api_key="test_api_key",
+        cache_ttl=1800,
+        max_retries=5,
+        timeout=60,
+        base_url="https://custom-api.dev",
+    )
+    client = SearchAPI(config=config)
+    assert client.config == config
+
+
+def test_init_without_api_key_or_config():
+    with pytest.raises(ValueError):
+        SearchAPI()
+
+
+@patch("requests.Session.request")
+def test_search_email_success(mock_request, client, mock_response):
+    mock_request.return_value.json.return_value = mock_response
+    mock_request.return_value.status_code = 200
+
+    result = client.search_email("test@example.com")
+
+    assert result.name == "John Doe"
+    assert result.dob == date(1990, 1, 1)
+    assert len(result.addresses) == 2
+    assert len(result.phone_numbers) == 2
+    assert isinstance(result.addresses[0], Address)
+    assert isinstance(result.phone_numbers[0], PhoneNumber)
+    assert result.addresses[1].zestimate == Decimal("1500000")
+
+
+@patch("requests.Session.request")
+def test_search_email_invalid_format(client):
+    with pytest.raises(ValidationError):
+        client.search_email("invalid-email")
+
+
+@patch("requests.Session.request")
+def test_search_email_api_error(client):
+    mock_response = Mock()
+    mock_response.status_code = 401
+    mock_response.text = "Invalid API key"
+    mock_response.json.return_value = {"error": "Invalid API key"}
+
+    with patch("requests.Session.request", return_value=mock_response):
+        with pytest.raises(AuthenticationError):
+            client.search_email("test@example.com")
+
+
+@patch("requests.Session.request")
+def test_search_phone_success(mock_request, client, mock_response):
+    mock_request.return_value.json.return_value = mock_response
+    mock_request.return_value.status_code = 200
+
+    result = client.search_phone("+12125551234")
+
+    assert result.name == "John Doe"
+    assert result.dob == date(1990, 1, 1)
+    assert len(result.addresses) == 2
+    assert len(result.phone_numbers) == 2
+    assert isinstance(result.addresses[0], Address)
+    assert isinstance(result.phone_numbers[0], PhoneNumber)
+    assert result.addresses[1].zestimate == Decimal("1500000")
+
+
+@patch("requests.Session.request")
+def test_search_phone_invalid_format(client):
+    with pytest.raises(ValidationError):
+        client.search_phone("invalid-phone")
+
+
+@patch("requests.Session.request")
+def test_search_domain_success(mock_request, client):
+    mock_response = {
+        "results": [
+            {
+                "email": "test1@example.com",
+                "name": "John Doe",
+                "addresses": ["123 Main St, New York, NY 10001"],
+                "phone_numbers": ["+12125551234"],
+            },
+            {
+                "email": "test2@example.com",
+                "name": "Jane Smith",
+                "addresses": ["456 Park Ave, New York, NY 10022"],
+                "phone_numbers": ["+12125556789"],
+            },
+        ]
+    }
+    mock_request.return_value.json.return_value = mock_response
+    mock_request.return_value.status_code = 200
+
+    result = client.search_domain("example.com")
+
+    assert result.domain == "example.com"
+    assert result.total_results == 2
+    assert len(result.results) == 2
+    assert result.results[0].email == "test1@example.com"
+    assert result.results[1].email == "test2@example.com"
+
+
+@patch("requests.Session.request")
+def test_search_domain_major_domain(client):
+    with pytest.raises(ValidationError):
+        client.search_domain("gmail.com")
+
+
+@patch("requests.Session.request")
+def test_search_domain_invalid_format(client):
+    with pytest.raises(ValidationError):
+        client.search_domain("invalid-domain")
+
+
+def test_format_address(client):
+    address = "123 main st, new york, ny 10001"
+    formatted = client._format_address(address)
+    assert formatted == "123 Main Street, New York, NY 10001"
+
+
+def test_parse_phone_number(client):
+    phone = "+12125551234"
+    result = client._parse_phone_number(phone)
+    assert isinstance(result, PhoneNumber)
+    assert result.number == "+12125551234"
+    assert result.is_valid is True
+
+
+def test_parse_phone_number_invalid(client):
+    phone = "invalid-phone"
+    result = client._parse_phone_number(phone)
+    assert isinstance(result, PhoneNumber)
+    assert result.number == "invalid-phone"
+    assert result.is_valid is False