Metadata-Version: 2.4
Name: pytrends-reliable
Version: 0.1.0
Summary: Maintained drop-in replacement for pytrends (Google Trends API): same methods, automatic 429 handling, working trending searches, optional reliable backend.
Author: RT Solutions
License: Apache-2.0
Project-URL: Reliable backend, https://apify.com/rt-solutions/google-trends-scraper
Keywords: google trends,pytrends,pytrends alternative,google trends api,trends,seo,429
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.0
Requires-Dist: pandas>=0.25
Dynamic: license-file

# pytrends-reliable — maintained pytrends alternative (Google Trends API for Python)

**pytrends is archived** (last release April 2023) and many users now hit `TooManyRequestsError: The request failed: Google returned a response with code 429`, or find that `trending_searches()` no longer works.

`pytrends-reliable` keeps the **exact pytrends interface** — change one import and your code runs again:

```python
# before
from pytrends.request import TrendReq
# after
from pytrends_reliable.request import TrendReq

pytrends = TrendReq(hl='en-US', tz=360)
pytrends.build_payload(['coffee', 'tea'], timeframe='today 3-m', geo='US')

pytrends.interest_over_time()               # DataFrame: date index, one column per keyword, isPartial
pytrends.interest_by_region(resolution='REGION', inc_geo_code=True)
pytrends.related_queries()                  # {'coffee': {'top': df, 'rising': df}, 'tea': {...}}
pytrends.related_topics()
pytrends.trending_searches(pn='united_kingdom')   # works again
pytrends.suggestions('tesla')
```

```
pip install pytrends-reliable
```

## What's different from pytrends

| | pytrends 4.9.2 | pytrends-reliable |
|---|---|---|
| Maintained | ❌ archived | ✅ |
| HTTP 429 | raises immediately | retries with a fresh cookie and exponential backoff |
| `trending_searches`, `today_searches`, `realtime_trending_searches` | broken (Google removed the endpoints) | ✅ use Google's current "Trending now" endpoint |
| `trending_now(geo, hours)` | — | ✅ search volume, % increase, start time, related terms, categories |
| When Google keeps blocking your IP | stuck | optional reliable backend (below) |
| Same method names, parameters and DataFrames | ✅ | ✅ |

## Reliable backend

Free direct requests are fine for occasional use, but Google rate-limits IP addresses quickly — especially servers, notebooks in the cloud and scheduled jobs. When that happens you can route the **same calls** through a managed Google Trends scraper that rotates IP addresses:

```python
pytrends = TrendReq(backend='apify', apify_token='YOUR_APIFY_TOKEN')
# or: export APIFY_TOKEN=... and keep TrendReq() — it switches automatically after repeated 429s
```

- Same methods, same DataFrames.
- Uses the [Google Trends Scraper](https://apify.com/rt-solutions/google-trends-scraper) on Apify: about **$1.50 per 1,000 searches**; Apify's free plan includes monthly credits.
- Each `build_payload` + data calls = one search (the data is fetched once and cached).
- Slower per call (a cloud run takes ~20–40 s) but it does not get blocked.

> Disclosure: I built both this library and the Apify scraper. The direct backend is free and needs no account; the reliable backend is optional.

## Supported methods

| Method | Direct backend | Reliable backend |
|---|---|---|
| `build_payload(kw_list, cat, timeframe, geo, gprop)` | ✅ | ✅ (one timeframe for all keywords) |
| `interest_over_time()` | ✅ | ✅ |
| `interest_by_region(resolution, inc_low_vol, inc_geo_code)` | ✅ COUNTRY / REGION / CITY / DMA | ✅ |
| `related_queries()`, `related_topics()` | ✅ | ✅ |
| `trending_now(geo, hours)` | ✅ | ✅ |
| `trending_searches(pn)`, `today_searches(pn)`, `realtime_trending_searches(pn)` | ✅ | ✅ |
| `suggestions(keyword)`, `categories()` | ✅ | direct |
| `multirange_interest_over_time()` | ✅ | ❌ |
| `top_charts(date)` | as pytrends (Google may have retired it) | ❌ |

Timeframes are Google's: `'today 5-y'`, `'today 12-m'`, `'today 3-m'`, `'today 1-m'`, `'now 7-d'`, `'now 1-d'`, `'now 4-H'`, `'now 1-H'`, `'all'`, `'2024-01-01 2024-06-30'`, `'2024-01-01T10 2024-01-03T10'`.

## Tips against 429 with the direct backend

- Reuse one `TrendReq` object; avoid many parallel scripts on the same IP.
- Wait a few seconds between `build_payload` calls.
- `TrendReq(max_429_retries=6)` retries longer; `proxies=['https://...']` rotates your own proxies (same as pytrends).

## License

Apache 2.0. Keeps the public interface of [pytrends](https://github.com/GeneralMills/pytrends) (Apache 2.0, © General Mills). Independent project, not affiliated with Google or the pytrends maintainers.
