Metadata-Version: 2.4
Name: google-ai-mode-scraper-api
Version: 0.0.2
Summary: Python client for scraping Google AI Mode answers and citations using the ScrapingBee web scraping API
Author: wordstotech
License: MIT
Project-URL: Homepage, https://www.scrapingbee.com/scrapers/google-ai-mode-api/
Keywords: google ai mode scraper,google ai mode api,google ai mode scraper api,ai mode scraper,google ai overview scraper,scrapingbee
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# Google AI Mode Scraper API (Python)

A Python client for pulling structured data out of Google AI Mode, built on the [ScrapingBee web scraping API](https://www.scrapingbee.com/features/ai-web-scraping-api/). Hand it a prompt, and it returns the AI-generated answer, the sources it cited, and the follow-up queries Google suggests, all as a plain dictionary.

## Install

```bash
pip install google-ai-mode-scraper-api
```

## Quickstart

```python
from google_ai_mode_scraper_api import GoogleAiModeScraper

scraper = GoogleAiModeScraper(api_key="YOUR_SCRAPINGBEE_API_KEY")

result = scraper.search("best noise cancelling headphones under $200")
print(result["ai_overviews"])
```

New accounts get 1,000 free credits at [ScrapingBee](https://www.scrapingbee.com/), no card needed.

## Returned data

`search()` returns the parsed JSON from ScrapingBee's [Google Search API](https://www.scrapingbee.com/documentation/google-api/). The generated answer sits in `ai_overviews`; the rest of the response carries the standard SERP fields:

```json
{
  "ai_overviews": {},
  "organic_results": [],
  "related_queries": [],
  "related_searches": [],
  "questions": [],
  "meta_data": {}
}
```

`organic_results` lists the pages ranking alongside the AI Mode answer, and `related_queries` gives you the next prompts Google is suggesting, which is useful for mapping out how a topic branches inside AI Mode.

## Method reference

**`search(query, country_code="us", language="en", device="desktop", light_request=True, **extra)`**

| Argument | Default | Notes |
|---|---|---|
| `query` | required | The prompt, capped at 400 characters (raises `ValueError` if longer) |
| `country_code` | `"us"` | ISO 3166-1 |
| `language` | `"en"` | |
| `device` | `"desktop"` | `"desktop"` or `"mobile"` |
| `light_request` | `True` | `True` costs 10 credits; `False` renders the fuller page for 15 |
| `**extra` | | Any extra ScrapingBee parameter, passed straight through |

## The 400-character limit

Google caps the AI Mode input box at 400 characters, and ScrapingBee's `search_type=ai_mode` request enforces the same limit. This client checks the length client-side and raises before spending a credit on a query that would be rejected:

```python
scraper.search("a" * 500)  # raises ValueError, no request sent
```

## Credit cost

`light_request=True` (the default) runs at 10 ScrapingBee credits. Set `light_request=False` for the fuller render at 15 credits. This is a dedicated endpoint, so there's no separate proxy or rendering flag to configure, unlike the general-purpose HTML API. Full breakdown on [ScrapingBee pricing](https://www.scrapingbee.com/pricing).

## Requirements and scope

Python 3.8 or newer and a ScrapingBee API key. This is an independent wrapper on the public ScrapingBee API, not affiliated with Google, and it targets Google's publicly accessible AI Mode responses only.

## Links

- [ScrapingBee's Google AI Mode scraper](https://www.scrapingbee.com/scrapers/google-ai-mode-api/)
- [ScrapingBee Google API documentation](https://www.scrapingbee.com/documentation/google-api/)
- [ScrapingBee pricing](https://www.scrapingbee.com/pricing)

## License

MIT
