Metadata-Version: 2.4
Name: AD-SearchAPI
Version: 1.0.1
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

    pip install search-api

## Quick Start

    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, include_extra_info=True, phone_format="international")
    print(result)

    # Search by phone
    result = client.search_phone("+1234567890", include_house_value=True, include_extra_info=True, phone_format="international")
    print(result)

    # Search by domain
    result = client.search_domain("example.com")
    print(result)

## Features

- Email search with optional house value, extra info, and phone number formatting
- Phone number search with validation, formatting, and property details
- Domain search with comprehensive results
- Automatic caching of results
- Rate limiting and retry handling
- Type hints and comprehensive documentation
- Enhanced address model with property details (bedrooms, bathrooms, living area, home status)

## Advanced Usage

### Configuration

    from search_api import SearchAPI, SearchAPIConfig

    config = SearchAPIConfig(
        api_key="your_api_key",
        max_retries=3,
        timeout=30,
        base_url="https://search-api.dev",
        debug_mode=False,  # Enable debug logging
        proxy=None  # Optional proxy configuration
    )

    client = SearchAPI(config=config)

### Error Handling

    from search_api.exceptions import SearchAPIError

    try:
        result = client.search_email("example@domain.com")
    except SearchAPIError as e:
        print(f"Error: {e}")

### Address Model

The `Address` model includes detailed property information when `include_house_value` is enabled:

- `street: str` - Street address
- `city: Optional[str]` - City name
- `state: Optional[str]` - State abbreviation
- `postal_code: Optional[str]` - Postal code
- `country: Optional[str]` - Country name
- `zestimate: Optional[Decimal]` - Estimated property value
- `zpid: Optional[str]` - Zillow Property ID
- `bedrooms: Optional[int]` - Number of bedrooms
- `bathrooms: Optional[float]` - Number of bathrooms (supports half-baths)
- `living_area: Optional[int]` - Square footage
- `home_status: Optional[str]` - Property status (e.g., "For Sale", "Sold")

## 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, phone_format: str = "international") -> EmailSearchResult`
  - Search by email address. Returns an `EmailSearchResult` with name, date of birth, addresses, phone numbers, and optional extra info.
  - `phone_format`: Use "international" for E.164 format or "local" for national format.

- `search_phone(phone: str, include_house_value: bool = False, include_extra_info: bool = False, phone_format: str = "international") -> List[PhoneSearchResult]`
  - Search by phone number. Returns a list of `PhoneSearchResult` objects with name, date of birth, addresses, emails, and optional extra info.
  - `phone_format`: Use "international" for E.164 format or "local" for national format.

- `search_domain(domain: str) -> DomainSearchResult`
  - Search by domain name. Returns a `DomainSearchResult` with a list of associated email results.

### SearchAPIConfig

Configuration class for customizing client behavior.

#### Parameters

- `api_key: str` - Your API key (required)
- `cache_ttl: int` - Cache time-to-live in seconds (default: 3600)
- `max_retries: int` - Maximum number of retry attempts (default: 3)
- `timeout: int` - Request timeout in seconds (default: 30)
- `base_url: str` - API base URL (default: "https://search-api.dev")
- `debug_mode: bool` - Enable debug logging (default: False)
- `proxy: Optional[Dict]` - Proxy configuration (default: None)

## Contributing

Contributions are welcome! Please submit a Pull Request with your changes or open an issue for discussion.

## License

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