Metadata-Version: 2.4
Name: pangolinfo-serp
Version: 0.2.0
Summary: Pangolinfo SERP API SDK - AI Overview SERP and keyword trends data for e-commerce intelligence.
Project-URL: Homepage, https://www.pangolinfo.com/ai-overview-serp-api/
Project-URL: Documentation, https://docs.pangolinfo.com
Project-URL: Repository, https://github.com/Pangolin-spg/pangolinfo-serp
Project-URL: Free API Key, https://tool.pangolinfo.com
Author-email: "PANGOLIN INFO TECH PTE. LTD." <support@pangolinfo.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-overview,api,google-trends,keyword-trends,pangolinfo,sdk,seo,serp
Classifier: Development Status :: 4 - Beta
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

# pangolinfo-serp

Pangolinfo SERP API SDK — AI Overview SERP and keyword trends data for e-commerce intelligence.

> Built and maintained by [PANGOLIN INFO TECH PTE. LTD.](https://www.pangolinfo.com)

## Installation

```bash
pip install pangolinfo-serp
```

## Quick start

```python
from pangolinfo_serp import SerpClient

client = SerpClient(token="your_bearer_token")

# AI Overview for a Google search URL
result = client.ai_overview("https://www.google.com/search?q=how+java+work")
print(result["json"])

# Keyword trends comparison
trends = client.keyword_trends(["shoe", "hat"])
print(trends["json"])
```

## Authentication

Grab a free API key from [tool.pangolinfo.com](https://tool.pangolinfo.com),
then pass it as the `token` argument. It is sent as a `Bearer` token on every
request.

```python
client = SerpClient(token="YOUR_TOKEN")
```

## Methods

### `ai_overview(url, screenshot=False)`

Scrapes a Google search result page and returns the AI Overview, organic
results, related searches and references.

- `url` *(str, required)* — Target Google search URL, e.g.
  `"https://www.google.com/search?q=how+java+work"`.
- `screenshot` *(bool, optional)* — Capture a screenshot of the page.

Posts to `POST https://scrapeapi.pangolinfo.com/api/v2/scrape` with
`parserName="googleSearch"`.

Returns the `data` object:

```json
{
  "json": {
    "ai_overview": "...",
    "organic": ["..."],
    "related_searches": ["..."],
    "references": ["..."]
  },
  "screenshot": "https://...",
  "taskId": "abc123",
  "url": "https://www.google.com/search?q=..."
}
```

Example:

```python
with SerpClient(token="TOKEN") as client:
    data = client.ai_overview(
        "https://www.google.com/search?q=best+running+shoes",
        screenshot=True,
    )
    ai = data["json"].get("ai_overview")
    screenshot_url = data.get("screenshot")
```

### `keyword_trends(keywords, time_range="today 12-m", region="US", language="en-US")`

Returns Google Trends comparison data for one or more keywords.

- `keywords` *(str | list[str], required)* — A single keyword or a list of
  keywords, e.g. `"shoe"` or `["shoe", "hat"]`.
- `time_range` *(str, optional)* — Time range, e.g. `"today 12-m"` (default),
  `"today 3-m"`, `"today 1-m"`.
- `region` *(str, optional)* — Region code, e.g. `"US"` (default), `"GB"`.
- `language` *(str, optional)* — Language, e.g. `"en-US"` (default).

Posts to `POST https://scrapeapi.pangolinfo.com/api/v1/google/trends`.

Returns the `data` object:

```json
{
  "json": {
    "keywordsGeoData": {"..."},
    "keywordsRankData": {"..."},
    "timelineData": ["..."],
    "geoMapData": {"..."}
  },
  "taskId": "abc123",
  "url": "https://trends.google.com/..."
}
```

Example:

```python
with SerpClient(token="TOKEN") as client:
    data = client.keyword_trends(
        ["shoe", "hat"],
        time_range="today 3-m",
        region="US",
        language="en-US",
    )
    timeline = data["json"]["timelineData"]
```

## Configuration

`SerpClient` accepts optional configuration:

```python
client = SerpClient(
    token="YOUR_TOKEN",
    base_url="https://scrapeapi.pangolinfo.com",  # default
    timeout=120,  # seconds, AI Overview can take 30s+
)
```

Use it as a context manager to ensure the underlying HTTP connection is
closed:

```python
with SerpClient(token="TOKEN") as client:
    ...
```

## Errors

All errors derive from `pangolinfo_serp.SerpError`:

| Exception              | When                                            |
| ---------------------- | ----------------------------------------------- |
| `AuthenticationError`  | HTTP 401 / 403 — bad or missing token.          |
| `APIError`             | API returns `code != 0` or an HTTP error.       |
| `TimeoutError`         | Request times out.                              |

```python
from pangolinfo_serp import SerpClient, APIError, AuthenticationError

try:
    client.ai_overview("https://www.google.com/search?q=java")
except AuthenticationError:
    print("check your token")
except APIError as exc:
    print(f"API error code={exc.code}: {exc}")
```

## Links

- **Product page:** [pangolinfo.com/ai-overview-serp-api](https://www.pangolinfo.com/ai-overview-serp-api/)
- **Documentation:** [docs.pangolinfo.com](https://docs.pangolinfo.com)
- **Get a free API key:** [tool.pangolinfo.com](https://tool.pangolinfo.com)
- **Source code:** [github.com/Pangolin-spg/pangolinfo-serp](https://github.com/Pangolin-spg/pangolinfo-serp)

## License

MIT — © PANGOLIN INFO TECH PTE. LTD.
