# 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
##### `search(params: SearchParams | Dict[str, Any]) -> SearchResponse`
Search using the SERP API with flexible parameters. Accepts either a SearchParams object or a dictionary.
```python
# Using dictionary (simple approach)
results = client.search({
'q': 'javascript frameworks',
'engine': 'google',
'category': 'web',
'time_range': 'week'
})
# Using SearchParams object (type-safe approach)
from serpex import SearchParams
params = SearchParams(
q='javascript frameworks',
engine='google',
category='web',
time_range='week'
)
results = client.search(params)
```
## 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)
```
### Using Different Engines
```python
# Auto-routing (recommended)
auto_results = client.search({
'q': 'python programming',
'engine': 'auto'
})
# Specific engine
google_results = client.search({
'q': 'python programming',
'engine': 'google'
})
# Privacy-focused search
ddg_results = client.search({
'q': 'python programming',
'engine': 'duckduckgo'
})
```
## Requirements
- Python 3.8+
- requests
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/divyeshradadiya/serp-frontend",
"name": "serpex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "serp, search, api, google, search-results, seo, python, sdk",
"author": "Serpex Team",
"author_email": "Serpex Team <support@serpex.dev>",
"download_url": "https://files.pythonhosted.org/packages/7e/2e/d4e8694b7662781e3ea45d4e7621ff652b31c7ce27543c0c2394744fba84/serpex-2.1.0.tar.gz",
"platform": null,
"description": "# serpex\n\nOfficial Python SDK for the Serpex SERP API - Fetch search results in JSON format.\n\n## Installation\n\n```bash\npip install serpex\n```\n\nOr with poetry:\n\n```bash\npoetry add serpex\n```\n\n## Quick Start\n\n```python\nfrom serpex import SerpexClient\n\n# Initialize the client with your API key\nclient = SerpexClient('your-api-key-here')\n\n# Search with auto-routing (recommended for simple use cases)\nresults = client.search({\n 'q': 'python tutorial',\n 'engine': 'auto'\n})\n\n# Or using SearchParams object for type safety\nfrom serpex import SearchParams\n\nparams = SearchParams(q='python tutorial', engine='auto')\nresults = client.search(params)\n\nprint(results.results[0].title)\n```\n\n## API Reference\n\n### SerpexClient\n\n#### Constructor\n\n```python\nSerpexClient(api_key: str, base_url: str = \"https://api.serpex.dev\")\n```\n\n- `api_key`: Your API key from the Serpex dashboard\n- `base_url`: Optional base URL (defaults to 'https://api.serpex.dev')\n\n#### Methods\n\n##### `search(params: SearchParams | Dict[str, Any]) -> SearchResponse`\n\nSearch using the SERP API with flexible parameters. Accepts either a SearchParams object or a dictionary.\n\n```python\n# Using dictionary (simple approach)\nresults = client.search({\n 'q': 'javascript frameworks',\n 'engine': 'google',\n 'category': 'web',\n 'time_range': 'week'\n})\n\n# Using SearchParams object (type-safe approach)\nfrom serpex import SearchParams\n\nparams = SearchParams(\n q='javascript frameworks',\n engine='google',\n category='web',\n time_range='week'\n)\nresults = client.search(params)\n```\n\n## Search Parameters\n\nThe `SearchParams` dataclass supports all search parameters:\n\n```python\n@dataclass\nclass SearchParams:\n # Required: search query\n q: str\n\n # Optional: Engine selection (defaults to 'auto')\n engine: Optional[str] = 'auto'\n\n # Optional: Search category (currently only 'web' supported)\n category: Optional[str] = 'web'\n\n # Optional: Time range filter\n time_range: Optional[str] = 'all'\n\n # Optional: Response format\n format: Optional[str] = 'json'\n```\n\n## Supported Engines\n\n- **auto**: Automatically routes to the best available search engine\n- **google**: Google's primary search engine\n- **bing**: Microsoft's search engine\n- **duckduckgo**: Privacy-focused search engine\n- **brave**: Privacy-first search engine\n- **yahoo**: Yahoo search engine\n- **yandex**: Russian search engine\n\n## Response Format\n\n```python\n@dataclass\nclass SearchResponse:\n metadata: SearchMetadata\n id: str\n query: str\n engines: List[str]\n results: List[SearchResult]\n answers: List[Any]\n corrections: List[str]\n infoboxes: List[Any]\n suggestions: List[str]\n```\n\n## Error Handling\n\nThe SDK raises `SerpApiException` for API errors:\n\n```python\nfrom serpex import SerpexClient, SerpApiException\n\ntry:\n results = client.search(SearchParams(q='test query'))\nexcept SerpApiException as e:\n print(f\"API error: {e}\")\n print(f\"Status code: {e.status_code}\")\n print(f\"Details: {e.details}\")\n```\n\n## Examples\n\n### Basic Search\n```python\nresults = client.search({\n 'q': 'coffee shops near me'\n})\n```\n\n### Advanced Search with Filters\n```python\nresults = client.search({\n 'q': 'latest AI news',\n 'engine': 'google',\n 'time_range': 'day',\n 'category': 'web'\n})\n```\n\n### Using SearchParams Object\n```python\nfrom serpex import SearchParams\n\nparams = SearchParams(\n q='machine learning',\n engine='auto',\n time_range='month'\n)\nresults = client.search(params)\n```\n\n### Using Different Engines\n```python\n# Auto-routing (recommended)\nauto_results = client.search({\n 'q': 'python programming',\n 'engine': 'auto'\n})\n\n# Specific engine\ngoogle_results = client.search({\n 'q': 'python programming',\n 'engine': 'google'\n})\n\n# Privacy-focused search\nddg_results = client.search({\n 'q': 'python programming',\n 'engine': 'duckduckgo'\n})\n```\n\n## Requirements\n\n- Python 3.8+\n- requests\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Official Python SDK for Serpex SERP API - Fetch search results in JSON format",
"version": "2.1.0",
"project_urls": {
"Bug Reports": "https://github.com/divyeshradadiya/serp-frontend/issues",
"Documentation": "https://github.com/divyeshradadiya/serp-frontend#readme",
"Homepage": "https://github.com/divyeshradadiya/serp-frontend",
"Repository": "https://github.com/divyeshradadiya/serp-frontend"
},
"split_keywords": [
"serp",
" search",
" api",
" google",
" search-results",
" seo",
" python",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c494d182b53f869173d22cdc47743ed3d3b3448d607d866dbb48ff771c505a07",
"md5": "41f9a15500698de8452ac076e9a0faef",
"sha256": "4699476a155a4249e6aeb805664921b28669480a997c4b99d4d956ed111780c2"
},
"downloads": -1,
"filename": "serpex-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "41f9a15500698de8452ac076e9a0faef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7158,
"upload_time": "2025-10-21T05:16:19",
"upload_time_iso_8601": "2025-10-21T05:16:19.099105Z",
"url": "https://files.pythonhosted.org/packages/c4/94/d182b53f869173d22cdc47743ed3d3b3448d607d866dbb48ff771c505a07/serpex-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7e2ed4e8694b7662781e3ea45d4e7621ff652b31c7ce27543c0c2394744fba84",
"md5": "48bdebfb944783fc2d6d19a8683a506a",
"sha256": "8db75f4460ba769ff988e32d43a34c536c980528d94962a69c8a4bfc7f9c0e55"
},
"downloads": -1,
"filename": "serpex-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "48bdebfb944783fc2d6d19a8683a506a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6533,
"upload_time": "2025-10-21T05:16:20",
"upload_time_iso_8601": "2025-10-21T05:16:20.319442Z",
"url": "https://files.pythonhosted.org/packages/7e/2e/d4e8694b7662781e3ea45d4e7621ff652b31c7ce27543c0c2394744fba84/serpex-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 05:16:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "divyeshradadiya",
"github_project": "serp-frontend",
"github_not_found": true,
"lcname": "serpex"
}
JSON
