serpex 2.2.0__tar.gz → 2.3.0__tar.gz

{serpex-2.2.0/src/serpex.egg-info → serpex-2.3.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: serpex
-Version: 2.2.0
+Version: 2.3.0
 Summary: Official Python SDK for Serpex Search API - Fetch search results in JSON format
-Home-page: https://github.com/divyeshradadiya/serp-frontend
+Home-page: https://github.com/divyeshradadiya/serpex-sdk-python
 Author: Serpex Team
 Author-email: Serpex Team <support@serpex.dev>
 License: MIT
@@ -162,16 +162,34 @@ class SearchParams:
     # Optional: Engine selection (defaults to 'auto')
     engine: Optional[str] = 'auto'
 
-    # Optional: Search category (currently only 'web' supported)
-    category: Optional[str] = 'web'
+    # Optional: Search category ('web' for general search, 'news' for news articles - always returns latest news)
+    category: Optional[str] = 'web'  # Supports: 'web', 'news'
 
-    # Optional: Time range filter
+    # Optional: Time range filter (only applicable for 'web' category, ignored for 'news')
     time_range: Optional[str] = 'all'
 
     # Optional: Response format
     format: Optional[str] = 'json'
 ```
 
+### News Search Example
+
+News search always returns the latest news articles. The `time_range` parameter is ignored for news searches.
+
+```python
+# Search for latest news articles
+news_results = client.search({
+    'q': 'artificial intelligence',
+    'engine': 'google',
+    'category': 'news'  # Always returns latest news
+})
+
+print(news_results.results[0].title)
+print(news_results.results[0].published_date)
+```
+
+````
+
 ## Supported Engines
 
 - **auto**: Automatically routes to the best available search engine
@@ -196,7 +214,7 @@ class SearchResponse:
     corrections: List[str]
     infoboxes: List[Any]
     suggestions: List[str]
-```
+````
 
 ## Error Handling
 
@@ -216,6 +234,7 @@ except SerpApiException as e:
 ## Examples
 
 ### Basic Search
+
 ```python
 results = client.search({
     'q': 'coffee shops near me'
@@ -223,6 +242,7 @@ results = client.search({
 ```
 
 ### Advanced Search with Filters
+
 ```python
 results = client.search({
     'q': 'latest AI news',
@@ -233,6 +253,7 @@ results = client.search({
 ```
 
 ### Using SearchParams Object
+
 ```python
 from serpex import SearchParams
 
@@ -247,6 +268,7 @@ 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({
@@ -259,6 +281,7 @@ if result.results[0].success:
 ```
 
 #### Extract from Multiple URLs (up to 10 at once)
+
 ```python
 # Extract content from multiple websites (up to 10 URLs)
 extract_results = client.extract({
@@ -281,6 +304,7 @@ for result in extract_results.results:
 ```
 
 #### Sample Response
+
 ```python
 # Example response structure
 {
@@ -306,6 +330,7 @@ for result in extract_results.results:
 ```
 
 ### Using ExtractParams Object
+
 ```python
 from serpex import ExtractParams
 

{serpex-2.2.0 → serpex-2.3.0}/README.md

@@ -127,16 +127,34 @@ class SearchParams:
     # Optional: Engine selection (defaults to 'auto')
     engine: Optional[str] = 'auto'
 
-    # Optional: Search category (currently only 'web' supported)
-    category: Optional[str] = 'web'
+    # Optional: Search category ('web' for general search, 'news' for news articles - always returns latest news)
+    category: Optional[str] = 'web'  # Supports: 'web', 'news'
 
-    # Optional: Time range filter
+    # Optional: Time range filter (only applicable for 'web' category, ignored for 'news')
     time_range: Optional[str] = 'all'
 
     # Optional: Response format
     format: Optional[str] = 'json'
 ```
 
+### News Search Example
+
+News search always returns the latest news articles. The `time_range` parameter is ignored for news searches.
+
+```python
+# Search for latest news articles
+news_results = client.search({
+    'q': 'artificial intelligence',
+    'engine': 'google',
+    'category': 'news'  # Always returns latest news
+})
+
+print(news_results.results[0].title)
+print(news_results.results[0].published_date)
+```
+
+````
+
 ## Supported Engines
 
 - **auto**: Automatically routes to the best available search engine
@@ -161,7 +179,7 @@ class SearchResponse:
     corrections: List[str]
     infoboxes: List[Any]
     suggestions: List[str]
-```
+````
 
 ## Error Handling
 
@@ -181,6 +199,7 @@ except SerpApiException as e:
 ## Examples
 
 ### Basic Search
+
 ```python
 results = client.search({
     'q': 'coffee shops near me'
@@ -188,6 +207,7 @@ results = client.search({
 ```
 
 ### Advanced Search with Filters
+
 ```python
 results = client.search({
     'q': 'latest AI news',
@@ -198,6 +218,7 @@ results = client.search({
 ```
 
 ### Using SearchParams Object
+
 ```python
 from serpex import SearchParams
 
@@ -212,6 +233,7 @@ 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({
@@ -224,6 +246,7 @@ if result.results[0].success:
 ```
 
 #### Extract from Multiple URLs (up to 10 at once)
+
 ```python
 # Extract content from multiple websites (up to 10 URLs)
 extract_results = client.extract({
@@ -246,6 +269,7 @@ for result in extract_results.results:
 ```
 
 #### Sample Response
+
 ```python
 # Example response structure
 {
@@ -271,6 +295,7 @@ for result in extract_results.results:
 ```
 
 ### Using ExtractParams Object
+
 ```python
 from serpex import ExtractParams
 
@@ -288,4 +313,4 @@ results = client.extract(params)
 
 ## License
 
-MIT
+MIT

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "serpex"
-version = "2.2.0"
+version = "2.3.0"
 description = "Official Python SDK for Serpex Search API - Fetch search results in JSON format"
 authors = [
     {name = "Serpex Team", email = "support@serpex.dev"}

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

@@ -5,13 +5,13 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="serpex",
-    version="2.2.0",
+    version="2.3.0",
     author="Serpex Team",
     author_email="support@serpex.dev",
     description="Official Python SDK for Serpex SERP API - Fetch search results in JSON format",
     long_description=long_description,
     long_description_content_type="text/markdown",
-    url="https://github.com/divyeshradadiya/serp-frontend",
+    url="https://github.com/divyeshradadiya/serpex-sdk-python",
     packages=find_packages(where="src"),
     package_dir={"": "src"},
     classifiers=[
@@ -45,8 +45,8 @@ setup(
     },
     keywords="serp search api google search-results seo python sdk",
     project_urls={
-        "Bug Reports": "https://github.com/divyeshradadiya/serp-frontend/issues",
-        "Source": "https://github.com/divyeshradadiya/serp-frontend",
-        "Documentation": "https://github.com/divyeshradadiya/serp-frontend#readme",
+        "Bug Reports": "https://github.com/divyeshradadiya/serpex-sdk-python/issues",
+        "Source": "https://github.com/divyeshradadiya/serpex-sdk-python",
+        "Documentation": "https://github.com/divyeshradadiya/serpex-sdk-python#readme",
     },
-)
+)

{serpex-2.2.0 → serpex-2.3.0/src/serpex.egg-info}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: serpex
-Version: 2.2.0
+Version: 2.3.0
 Summary: Official Python SDK for Serpex Search API - Fetch search results in JSON format
-Home-page: https://github.com/divyeshradadiya/serp-frontend
+Home-page: https://github.com/divyeshradadiya/serpex-sdk-python
 Author: Serpex Team
 Author-email: Serpex Team <support@serpex.dev>
 License: MIT
@@ -162,16 +162,34 @@ class SearchParams:
     # Optional: Engine selection (defaults to 'auto')
     engine: Optional[str] = 'auto'
 
-    # Optional: Search category (currently only 'web' supported)
-    category: Optional[str] = 'web'
+    # Optional: Search category ('web' for general search, 'news' for news articles - always returns latest news)
+    category: Optional[str] = 'web'  # Supports: 'web', 'news'
 
-    # Optional: Time range filter
+    # Optional: Time range filter (only applicable for 'web' category, ignored for 'news')
     time_range: Optional[str] = 'all'
 
     # Optional: Response format
     format: Optional[str] = 'json'
 ```
 
+### News Search Example
+
+News search always returns the latest news articles. The `time_range` parameter is ignored for news searches.
+
+```python
+# Search for latest news articles
+news_results = client.search({
+    'q': 'artificial intelligence',
+    'engine': 'google',
+    'category': 'news'  # Always returns latest news
+})
+
+print(news_results.results[0].title)
+print(news_results.results[0].published_date)
+```
+
+````
+
 ## Supported Engines
 
 - **auto**: Automatically routes to the best available search engine
@@ -196,7 +214,7 @@ class SearchResponse:
     corrections: List[str]
     infoboxes: List[Any]
     suggestions: List[str]
-```
+````
 
 ## Error Handling
 
@@ -216,6 +234,7 @@ except SerpApiException as e:
 ## Examples
 
 ### Basic Search
+
 ```python
 results = client.search({
     'q': 'coffee shops near me'
@@ -223,6 +242,7 @@ results = client.search({
 ```
 
 ### Advanced Search with Filters
+
 ```python
 results = client.search({
     'q': 'latest AI news',
@@ -233,6 +253,7 @@ results = client.search({
 ```
 
 ### Using SearchParams Object
+
 ```python
 from serpex import SearchParams
 
@@ -247,6 +268,7 @@ 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({
@@ -259,6 +281,7 @@ if result.results[0].success:
 ```
 
 #### Extract from Multiple URLs (up to 10 at once)
+
 ```python
 # Extract content from multiple websites (up to 10 URLs)
 extract_results = client.extract({
@@ -281,6 +304,7 @@ for result in extract_results.results:
 ```
 
 #### Sample Response
+
 ```python
 # Example response structure
 {
@@ -306,6 +330,7 @@ for result in extract_results.results:
 ```
 
 ### Using ExtractParams Object
+
 ```python
 from serpex import ExtractParams
 

{serpex-2.2.0 → serpex-2.3.0}/src/serpex_sdk/client.py

@@ -6,7 +6,14 @@ import requests
 from typing import Optional, Dict, Any, Union
 from urllib.parse import urlencode
 
-from .types import SearchResponse, SearchParams, ExtractResponse, ExtractParams, ExtractResult, ExtractMetadata
+from .types import (
+    SearchResponse,
+    SearchParams,
+    ExtractResponse,
+    ExtractParams,
+    ExtractResult,
+    ExtractMetadata,
+)
 from .exceptions import SerpApiException
 
 
@@ -35,12 +42,16 @@ class SerpexClient:
         self.api_key = api_key
         self.base_url = base_url.rstrip("/")
         self.session = requests.Session()
-        self.session.headers.update({
-            "Authorization": f"Bearer {self.api_key}",
-            "Content-Type": "application/json",
-        })
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            }
+        )
 
-    def _make_request(self, params: Dict[str, Any], endpoint: str = "/api/search", method: str = "GET") -> Dict[str, Any]:
+    def _make_request(
+        self, params: Dict[str, Any], endpoint: str = "/api/search", method: str = "GET"
+    ) -> Dict[str, Any]:
         """
         Make an authenticated request to the API.
 
@@ -77,7 +88,7 @@ class SerpexClient:
                 query_string = urlencode(filtered_params, doseq=True)
                 final_url = f"{url}?{query_string}" if query_string else url
                 response = self.session.get(final_url, timeout=30)
-            
+
             return self._handle_response(response)
         except requests.RequestException as e:
             raise SerpApiException(f"Request failed: {str(e)}")
@@ -105,9 +116,7 @@ class SerpexClient:
             try:
                 data = response.json()
                 raise SerpApiException(
-                    data.get("error", "Validation error"),
-                    status_code=400,
-                    details=data
+                    data.get("error", "Validation error"), status_code=400, details=data
                 )
             except ValueError:
                 raise SerpApiException("Bad request", status_code=400)
@@ -117,12 +126,11 @@ class SerpexClient:
                 raise SerpApiException(
                     data.get("error", f"API error: {response.reason}"),
                     status_code=response.status_code,
-                    details=data
+                    details=data,
                 )
             except ValueError:
                 raise SerpApiException(
-                    f"API error: {response.reason}",
-                    status_code=response.status_code
+                    f"API error: {response.reason}", status_code=response.status_code
                 )
 
         try:
@@ -150,21 +158,30 @@ class SerpexClient:
 
         # Validate required parameters
         if not params.q or not isinstance(params.q, str) or not params.q.strip():
-            raise ValueError("Query parameter (q) is required and must be a non-empty string")
+            raise ValueError(
+                "Query parameter (q) is required and must be a non-empty string"
+            )
 
         if len(params.q) > 500:
             raise ValueError("Query too long (max 500 characters)")
 
+        # Determine endpoint based on category
+        category = params.category or "web"
+        endpoint = "/api/search/news" if category == "news" else "/api/search"
+
         # Prepare request parameters with only supported params
         request_params = {
-            'q': params.q,
-            'engine': params.engine or 'auto',
-            'category': params.category or 'web',
-            'time_range': params.time_range or 'all',
-            'format': params.format or 'json'
+            "q": params.q,
+            "engine": params.engine or "auto",
+            "format": params.format or "json",
         }
 
-        data = self._make_request(request_params)
+        # Add category for web search, omit for news (news endpoint doesn't need it)
+        if category == "web":
+            request_params["category"] = "web"
+            request_params["time_range"] = params.time_range or "all"
+
+        data = self._make_request(request_params, endpoint=endpoint)
 
         # Convert response to SearchResponse object
         from .types import SearchResult, SearchMetadata
@@ -178,10 +195,10 @@ class SerpexClient:
             query=data["query"],
             engines=data["engines"],
             results=results,
-            answers=data["answers"],
-            corrections=data["corrections"],
-            infoboxes=data["infoboxes"],
-            suggestions=data["suggestions"],
+            answers=data.get("answers", []),
+            corrections=data.get("corrections", []),
+            infoboxes=data.get("infoboxes", []),
+            suggestions=data.get("suggestions", []),
         )
 
     def extract(self, params: Union[ExtractParams, Dict[str, Any]]) -> ExtractResponse:
@@ -203,7 +220,11 @@ class SerpexClient:
             params = ExtractParams(**params)
 
         # Validate required parameters
-        if not params.urls or not isinstance(params.urls, list) or len(params.urls) == 0:
+        if (
+            not params.urls
+            or not isinstance(params.urls, list)
+            or len(params.urls) == 0
+        ):
             raise ValueError("URLs list is required and must contain at least one URL")
 
         if len(params.urls) > 10:
@@ -217,6 +238,7 @@ class SerpexClient:
                 continue
             try:
                 from urllib.parse import urlparse
+
                 parsed = urlparse(url)
                 if not parsed.scheme or not parsed.netloc:
                     invalid_urls.append(url)
@@ -227,11 +249,9 @@ class SerpexClient:
             raise ValueError(f"Invalid URLs provided: {invalid_urls}")
 
         # Prepare request parameters
-        request_params = {
-            'urls': params.urls
-        }
+        request_params = {"urls": params.urls}
 
-        data = self._make_request(request_params, endpoint='/api/crawl', method='POST')
+        data = self._make_request(request_params, endpoint="/api/crawl", method="POST")
 
         # Convert response to ExtractResponse object
         metadata = ExtractMetadata(**data["metadata"])
@@ -241,4 +261,4 @@ class SerpexClient:
             success=data["success"],
             results=results,
             metadata=metadata,
-        )
+        )

{serpex-2.2.0 → serpex-2.3.0}/src/serpex_sdk/types.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass
 @dataclass
 class SearchResult:
     """Represents a single search result."""
+
     title: str
     url: str
     snippet: str
@@ -23,15 +24,18 @@ class SearchResult:
 @dataclass
 class SearchMetadata:
     """Metadata for search results."""
+
     number_of_results: int
     response_time: int
     timestamp: str
     credits_used: int
+    category: Optional[str] = None  # Optional category field for news searches
 
 
 @dataclass
 class SearchResponse:
     """Complete search response."""
+
     metadata: SearchMetadata
     id: str
     query: str
@@ -46,6 +50,7 @@ class SearchResponse:
 @dataclass
 class ExtractResult:
     """Represents a single extraction result."""
+
     url: str
     success: bool
     markdown: Optional[str] = None
@@ -59,6 +64,7 @@ class ExtractResult:
 @dataclass
 class ExtractMetadata:
     """Metadata for extraction results."""
+
     total_urls: int
     processed_urls: int
     successful_crawls: int
@@ -71,6 +77,7 @@ class ExtractMetadata:
 @dataclass
 class ExtractResponse:
     """Complete extraction response."""
+
     success: bool
     results: List[ExtractResult]
     metadata: ExtractMetadata
@@ -79,6 +86,7 @@ class ExtractResponse:
 @dataclass
 class ExtractParams:
     """Parameters for extraction requests."""
+
     # Required: URLs to extract (max 10)
     urls: List[str]
 
@@ -86,17 +94,18 @@ class ExtractParams:
 @dataclass
 class SearchParams:
     """Parameters for search requests."""
+
     # Required: search query
     q: str
 
     # Optional: Engine selection (defaults to 'auto')
-    engine: Optional[str] = 'auto'
+    engine: Optional[str] = "auto"
 
-    # Optional: Search category (currently only 'web' supported)
-    category: Optional[str] = 'web'
+    # Optional: Search category ('web' for general search, 'news' for news articles - always returns latest news)
+    category: Optional[str] = "web"  # Supports: 'web', 'news'
 
-    # Optional: Time range filter
-    time_range: Optional[str] = 'all'
+    # Optional: Time range filter (only applicable for 'web' category, ignored for 'news')
+    time_range: Optional[str] = "all"
 
     # Optional: Response format
-    format: Optional[str] = 'json'
+    format: Optional[str] = "json"