serpex 2.0.2__tar.gz → 2.2.0__tar.gz

serpex-2.2.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: serpex
+Version: 2.2.0
+Summary: Official Python SDK for Serpex Search API - Fetch search results in JSON format
+Home-page: https://github.com/divyeshradadiya/serp-frontend
+Author: Serpex Team
+Author-email: Serpex Team <support@serpex.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/divyeshradadiya/serpex-sdk-python
+Project-URL: Repository, https://github.com/divyeshradadiya/serpex-sdk-python
+Project-URL: Bug Reports, https://github.com/divyeshradadiya/serpex-sdk-python/issues
+Project-URL: Documentation, https://github.com/divyeshradadiya/serpex-sdk-python#readme
+Keywords: serp,search,api,google,search-results,seo,python,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# serpex
+
+Official Python SDK for the Serpex SERP API - Fetch search results in JSON format.
+
+## Installation
+
+```bash
+pip install serpex
+```
+
+Or with poetry:
+
+```bash
+poetry add serpex
+```
+
+## Quick Start
+
+```python
+from serpex import SerpexClient
+
+# Initialize the client with your API key
+client = SerpexClient('your-api-key-here')
+
+# Search with auto-routing (recommended for simple use cases)
+results = client.search({
+    'q': 'python tutorial',
+    'engine': 'auto'
+})
+
+# Or using SearchParams object for type safety
+from serpex import SearchParams
+
+params = SearchParams(q='python tutorial', engine='auto')
+results = client.search(params)
+
+print(results.results[0].title)
+```
+
+## API Reference
+
+### SerpexClient
+
+#### Constructor
+
+```python
+SerpexClient(api_key: str, base_url: str = "https://api.serpex.dev")
+```
+
+- `api_key`: Your API key from the Serpex dashboard
+- `base_url`: Optional base URL (defaults to 'https://api.serpex.dev')
+
+#### Methods
+
+##### `extract(params: ExtractParams | Dict[str, Any]) -> ExtractResponse`
+
+Extract content from web pages and convert them to LLM-ready markdown data. Accepts up to 10 URLs per request.
+
+```python
+# Using dictionary (simple approach)
+results = client.extract({
+    'urls': [
+        'https://example.com',
+        'https://httpbin.org'
+    ]
+})
+
+# Using ExtractParams object (type-safe approach)
+from serpex import ExtractParams
+
+params = ExtractParams(urls=[
+    'https://example.com',
+    'https://httpbin.org'
+])
+results = client.extract(params)
+```
+
+## Extract Parameters
+
+The `ExtractParams` dataclass supports extraction parameters:
+
+```python
+@dataclass
+class ExtractParams:
+    # Required: URLs to extract (max 10)
+    urls: List[str]
+```
+
+## Extract Response Format
+
+```python
+@dataclass
+class ExtractResponse:
+    success: bool
+    results: List[ExtractResult]
+    metadata: ExtractMetadata
+
+@dataclass
+class ExtractResult:
+    url: str
+    success: bool
+    markdown: Optional[str] = None
+    error: Optional[str] = None
+    status_code: Optional[int] = None
+
+@dataclass
+class ExtractMetadata:
+    total_urls: int
+    processed_urls: int
+    successful_crawls: int
+    failed_crawls: int
+    credits_used: int
+    response_time: int
+    timestamp: str
+```
+
+## Search Parameters
+
+The `SearchParams` dataclass supports all search parameters:
+
+```python
+@dataclass
+class SearchParams:
+    # Required: search query
+    q: str
+
+    # Optional: Engine selection (defaults to 'auto')
+    engine: Optional[str] = 'auto'
+
+    # Optional: Search category (currently only 'web' supported)
+    category: Optional[str] = 'web'
+
+    # Optional: Time range filter
+    time_range: Optional[str] = 'all'
+
+    # Optional: Response format
+    format: Optional[str] = 'json'
+```
+
+## Supported Engines
+
+- **auto**: Automatically routes to the best available search engine
+- **google**: Google's primary search engine
+- **bing**: Microsoft's search engine
+- **duckduckgo**: Privacy-focused search engine
+- **brave**: Privacy-first search engine
+- **yahoo**: Yahoo search engine
+- **yandex**: Russian search engine
+
+## Response Format
+
+```python
+@dataclass
+class SearchResponse:
+    metadata: SearchMetadata
+    id: str
+    query: str
+    engines: List[str]
+    results: List[SearchResult]
+    answers: List[Any]
+    corrections: List[str]
+    infoboxes: List[Any]
+    suggestions: List[str]
+```
+
+## Error Handling
+
+The SDK raises `SerpApiException` for API errors:
+
+```python
+from serpex import SerpexClient, SerpApiException
+
+try:
+    results = client.search(SearchParams(q='test query'))
+except SerpApiException as e:
+    print(f"API error: {e}")
+    print(f"Status code: {e.status_code}")
+    print(f"Details: {e.details}")
+```
+
+## Examples
+
+### Basic Search
+```python
+results = client.search({
+    'q': 'coffee shops near me'
+})
+```
+
+### Advanced Search with Filters
+```python
+results = client.search({
+    'q': 'latest AI news',
+    'engine': 'google',
+    'time_range': 'day',
+    'category': 'web'
+})
+```
+
+### Using SearchParams Object
+```python
+from serpex import SearchParams
+
+params = SearchParams(
+    q='machine learning',
+    engine='auto',
+    time_range='month'
+)
+results = client.search(params)
+```
+
+### Extract Web Content to LLM-Ready Data
+
+#### Extract from a Single URL
+```python
+# Extract content from one website
+result = client.extract({
+    'urls': ['https://example.com']
+})
+
+if result.results[0].success:
+    print(f"✅ Extracted {len(result.results[0].markdown)} characters")
+    print("Markdown content:", result.results[0].markdown[:200] + "...")
+```
+
+#### Extract from Multiple URLs (up to 10 at once)
+```python
+# Extract content from multiple websites (up to 10 URLs)
+extract_results = client.extract({
+    'urls': [
+        'https://example.com',
+        'https://httpbin.org',
+        'https://github.com'
+    ]
+})
+
+print(f"Successfully extracted {extract_results.metadata.successful_crawls} pages")
+print(f"Total credits used: {extract_results.metadata.credits_used}")
+
+for result in extract_results.results:
+    if result.success:
+        print(f"✅ {result.url}: {len(result.markdown)} characters")
+        # Use result.markdown for LLM processing
+    else:
+        print(f"❌ {result.url}: {result.error}")
+```
+
+#### Sample Response
+```python
+# Example response structure
+{
+    'success': True,
+    'results': [
+        {
+            'url': 'https://example.com',
+            'success': True,
+            'markdown': '# Example Domain\n\nThis domain is for use in...',
+            'status_code': 200
+        }
+    ],
+    'metadata': {
+        'total_urls': 1,
+        'processed_urls': 1,
+        'successful_crawls': 1,
+        'failed_crawls': 0,
+        'credits_used': 3,
+        'response_time': 255,
+        'timestamp': '2025-11-13T10:30:00.000Z'
+    }
+}
+```
+
+### Using ExtractParams Object
+```python
+from serpex import ExtractParams
+
+params = ExtractParams(urls=[
+    'https://example.com',
+    'https://httpbin.org'
+])
+results = client.extract(params)
+```
+
+## Requirements
+
+- Python 3.8+
+- requests
+
+## License
+
+MIT

serpex-2.2.0/README.md

@@ -0,0 +1,291 @@
+# serpex
+
+Official Python SDK for the Serpex SERP API - Fetch search results in JSON format.
+
+## Installation
+
+```bash
+pip install serpex
+```
+
+Or with poetry:
+
+```bash
+poetry add serpex
+```
+
+## Quick Start
+
+```python
+from serpex import SerpexClient
+
+# Initialize the client with your API key
+client = SerpexClient('your-api-key-here')
+
+# Search with auto-routing (recommended for simple use cases)
+results = client.search({
+    'q': 'python tutorial',
+    'engine': 'auto'
+})
+
+# Or using SearchParams object for type safety
+from serpex import SearchParams
+
+params = SearchParams(q='python tutorial', engine='auto')
+results = client.search(params)
+
+print(results.results[0].title)
+```
+
+## API Reference
+
+### SerpexClient
+
+#### Constructor
+
+```python
+SerpexClient(api_key: str, base_url: str = "https://api.serpex.dev")
+```
+
+- `api_key`: Your API key from the Serpex dashboard
+- `base_url`: Optional base URL (defaults to 'https://api.serpex.dev')
+
+#### Methods
+
+##### `extract(params: ExtractParams | Dict[str, Any]) -> ExtractResponse`
+
+Extract content from web pages and convert them to LLM-ready markdown data. Accepts up to 10 URLs per request.
+
+```python
+# Using dictionary (simple approach)
+results = client.extract({
+    'urls': [
+        'https://example.com',
+        'https://httpbin.org'
+    ]
+})
+
+# Using ExtractParams object (type-safe approach)
+from serpex import ExtractParams
+
+params = ExtractParams(urls=[
+    'https://example.com',
+    'https://httpbin.org'
+])
+results = client.extract(params)
+```
+
+## Extract Parameters
+
+The `ExtractParams` dataclass supports extraction parameters:
+
+```python
+@dataclass
+class ExtractParams:
+    # Required: URLs to extract (max 10)
+    urls: List[str]
+```
+
+## Extract Response Format
+
+```python
+@dataclass
+class ExtractResponse:
+    success: bool
+    results: List[ExtractResult]
+    metadata: ExtractMetadata
+
+@dataclass
+class ExtractResult:
+    url: str
+    success: bool
+    markdown: Optional[str] = None
+    error: Optional[str] = None
+    status_code: Optional[int] = None
+
+@dataclass
+class ExtractMetadata:
+    total_urls: int
+    processed_urls: int
+    successful_crawls: int
+    failed_crawls: int
+    credits_used: int
+    response_time: int
+    timestamp: str
+```
+
+## Search Parameters
+
+The `SearchParams` dataclass supports all search parameters:
+
+```python
+@dataclass
+class SearchParams:
+    # Required: search query
+    q: str
+
+    # Optional: Engine selection (defaults to 'auto')
+    engine: Optional[str] = 'auto'
+
+    # Optional: Search category (currently only 'web' supported)
+    category: Optional[str] = 'web'
+
+    # Optional: Time range filter
+    time_range: Optional[str] = 'all'
+
+    # Optional: Response format
+    format: Optional[str] = 'json'
+```
+
+## Supported Engines
+
+- **auto**: Automatically routes to the best available search engine
+- **google**: Google's primary search engine
+- **bing**: Microsoft's search engine
+- **duckduckgo**: Privacy-focused search engine
+- **brave**: Privacy-first search engine
+- **yahoo**: Yahoo search engine
+- **yandex**: Russian search engine
+
+## Response Format
+
+```python
+@dataclass
+class SearchResponse:
+    metadata: SearchMetadata
+    id: str
+    query: str
+    engines: List[str]
+    results: List[SearchResult]
+    answers: List[Any]
+    corrections: List[str]
+    infoboxes: List[Any]
+    suggestions: List[str]
+```
+
+## Error Handling
+
+The SDK raises `SerpApiException` for API errors:
+
+```python
+from serpex import SerpexClient, SerpApiException
+
+try:
+    results = client.search(SearchParams(q='test query'))
+except SerpApiException as e:
+    print(f"API error: {e}")
+    print(f"Status code: {e.status_code}")
+    print(f"Details: {e.details}")
+```
+
+## Examples
+
+### Basic Search
+```python
+results = client.search({
+    'q': 'coffee shops near me'
+})
+```
+
+### Advanced Search with Filters
+```python
+results = client.search({
+    'q': 'latest AI news',
+    'engine': 'google',
+    'time_range': 'day',
+    'category': 'web'
+})
+```
+
+### Using SearchParams Object
+```python
+from serpex import SearchParams
+
+params = SearchParams(
+    q='machine learning',
+    engine='auto',
+    time_range='month'
+)
+results = client.search(params)
+```
+
+### Extract Web Content to LLM-Ready Data
+
+#### Extract from a Single URL
+```python
+# Extract content from one website
+result = client.extract({
+    'urls': ['https://example.com']
+})
+
+if result.results[0].success:
+    print(f"✅ Extracted {len(result.results[0].markdown)} characters")
+    print("Markdown content:", result.results[0].markdown[:200] + "...")
+```
+
+#### Extract from Multiple URLs (up to 10 at once)
+```python
+# Extract content from multiple websites (up to 10 URLs)
+extract_results = client.extract({
+    'urls': [
+        'https://example.com',
+        'https://httpbin.org',
+        'https://github.com'
+    ]
+})
+
+print(f"Successfully extracted {extract_results.metadata.successful_crawls} pages")
+print(f"Total credits used: {extract_results.metadata.credits_used}")
+
+for result in extract_results.results:
+    if result.success:
+        print(f"✅ {result.url}: {len(result.markdown)} characters")
+        # Use result.markdown for LLM processing
+    else:
+        print(f"❌ {result.url}: {result.error}")
+```
+
+#### Sample Response
+```python
+# Example response structure
+{
+    'success': True,
+    'results': [
+        {
+            'url': 'https://example.com',
+            'success': True,
+            'markdown': '# Example Domain\n\nThis domain is for use in...',
+            'status_code': 200
+        }
+    ],
+    'metadata': {
+        'total_urls': 1,
+        'processed_urls': 1,
+        'successful_crawls': 1,
+        'failed_crawls': 0,
+        'credits_used': 3,
+        'response_time': 255,
+        'timestamp': '2025-11-13T10:30:00.000Z'
+    }
+}
+```
+
+### Using ExtractParams Object
+```python
+from serpex import ExtractParams
+
+params = ExtractParams(urls=[
+    'https://example.com',
+    'https://httpbin.org'
+])
+results = client.extract(params)
+```
+
+## Requirements
+
+- Python 3.8+
+- requests
+
+## License
+
+MIT

{serpex-2.0.2 → serpex-2.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "serpex"
-version = "2.0.2"
-description = "Official Python SDK for Serpex SERP API - Fetch search results in JSON format"
+version = "2.2.0"
+description = "Official Python SDK for Serpex Search API - Fetch search results in JSON format"
 authors = [
     {name = "Serpex Team", email = "support@serpex.dev"}
 ]
@@ -33,10 +33,10 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/divyeshradadiya/serp-frontend"
-Repository = "https://github.com/divyeshradadiya/serp-frontend"
-"Bug Reports" = "https://github.com/divyeshradadiya/serp-frontend/issues"
-Documentation = "https://github.com/divyeshradadiya/serp-frontend#readme"
+Homepage = "https://github.com/divyeshradadiya/serpex-sdk-python"
+Repository = "https://github.com/divyeshradadiya/serpex-sdk-python"
+"Bug Reports" = "https://github.com/divyeshradadiya/serpex-sdk-python/issues"
+Documentation = "https://github.com/divyeshradadiya/serpex-sdk-python#readme"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{serpex-2.0.2 → serpex-2.2.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="serpex",
-    version="2.0.2",
+    version="2.2.0",
     author="Serpex Team",
     author_email="support@serpex.dev",
     description="Official Python SDK for Serpex SERP API - Fetch search results in JSON format",