Metadata-Version: 2.4
Name: google-trends-scraper-api
Version: 0.1.0
Summary: Google Trends scraper in Python. Scrape Google Trends trending searches with traffic estimates and related news as structured data.
Author: wordstotech
License: MIT
Project-URL: Homepage, https://www.scrapingbee.com/scrapers/google-trends-scraper/
Project-URL: Documentation, https://www.scrapingbee.com/documentation/
Project-URL: Repository, https://github.com/ScrapingBee/google-trends-scraper
Keywords: google-trends-scraper,google-trends-api,scrape-google-trends,trending-searches,trends-api,keyword-research,web-scraping-api,scraping-api,data-extraction,scrapingbee
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# google-trends-scraper-api

A **Google Trends scraper** for Python. Pulls the currently trending searches for a country,
each with an approximate traffic figure and the news stories Google attached to it, through
ScrapingBee's [Google Trends scraper](https://www.scrapingbee.com/scrapers/google-trends-scraper/).

Verified against the live API on 2026-08-25: 10 trends returned for `US`, 15 credits charged.

## Install

```bash
pip install google-trends-scraper-api
```

## Scrape Google Trends

```python
from google_trends_scraper_api import GoogleTrendsScraper

scraper = GoogleTrendsScraper("YOUR-API-KEY")

for trend in scraper.trending("US"):
    print(trend.traffic, trend.title)
```

```
500+ john f kennedy center for the performing arts
200+ policía
200+ aura farming
```

Key from [app.scrapingbee.com](https://app.scrapingbee.com/), 1,000 credits free.

## The `custom_google` requirement

Google properties are not fetched like ordinary pages. Send a `trends.google.com` URL through the
HTML API without the right flag and the request is refused outright:

```json
{"errors": {"query": {"custom_google": ["If you wish to scrape Google, use the custom_google=True parameter!"]}}}
```

This client sets `custom_google=true` on every call, so you never hit that error. It is also why
a trends call costs 15 credits rather than the 1 to 5 a plain page would.

## What a Trend carries

| Attribute | Value |
| --- | --- |
| `title` | The trending query |
| `traffic` | Google's bucket, as a string such as `"500+"` |
| `traffic_value` | `500`, parsed from the bucket so you can sort and filter |
| `published` | RFC 822 timestamp from the feed |
| `link` | Google Trends URL for the query |
| `picture` | Representative image |
| `news` | List of `{title, url, source, picture}` stories |

`traffic` is deliberately imprecise on Google's side. It reports a floor, not a count, which is
why `traffic_value` is named a value rather than a volume.

## Filtering to what matters

Ten trends a country is a small feed, and most of it is noise for any given business. Threshold
on the bucket floor:

```python
trends = scraper.trending("GB")
big = GoogleTrendsScraper.above(trends, 500)

for trend in big:
    print(trend.title, trend.traffic)
    for story in trend.news[:2]:
        print("   ", story["source"], story["title"])
```

## Several markets at once

```python
snapshot = {}
for market in ["US", "GB", "DE", "JP"]:
    snapshot[market] = [t.title for t in scraper.trending(market)]

print(snapshot["US"][:3], snapshot["JP"][:3])
```

Four markets is 60 credits. Hourly across four markets is 1,440 a day, so check the balance before
scheduling:

```python
print(scraper.usage())
```

That call is free and capped at 6 per minute.

## Cost

| Call | Credits |
| --- | --- |
| One trending feed | 15 observed |
| `usage()` | 0 |
| HTTP 500 | 0 |

Failures are not charged, so retrying costs nothing. Tiers on the
[pricing page](https://www.scrapingbee.com/pricing/).

## Scope of this client

This wraps the trending-searches feed, which is the surface that returns reliable structured data
today. Google's interest-over-time and comparison widgets sit behind an internal token exchange
and are not covered here.

For search-demand work that needs numbers rather than a live feed, the
[Google search API](https://www.scrapingbee.com/features/google/) with
[related searches](https://www.scrapingbee.com/scrapers/google-related-searches-api/) and
[related questions](https://www.scrapingbee.com/scrapers/google-related-questions-api/) is the
more dependable route, and
[Google News](https://www.scrapingbee.com/scrapers/google-news-scraper-api/) covers the coverage
side of a spike.

## Arbitrary Google URLs

`fetch` exposes the underlying call if you want a different Google surface with the flag already
set:

```python
response = scraper.fetch("https://trends.google.com/trending/rss?geo=FR")
print(response.headers["Spb-cost"], len(response.text))
```

## Scope

Public, pre-login content only. Scraping behind login credentials is prohibited by the
[ScrapingBee terms](https://www.scrapingbee.com/terms-and-conditions/). Keep API keys out of AI
coding assistants.

MIT licensed. [Repository](https://github.com/ScrapingBee/google-trends-scraper)
