pytrends-ng 0.1.0__tar.gz

pytrends_ng-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+.secrets/
+__pycache__/

pytrends_ng-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: pytrends-ng
+Version: 0.1.0
+Summary: Drop-in replacement for the archived pytrends: Google Trends without 429 errors, unlimited keywords on one scale.
+Project-URL: Google Trends actor, https://apify.com/githubanassk/google-trends-scraper
+License-Expression: MIT
+Keywords: google trends,google trends api,keyword research,pytrends,seo,trends
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Requires-Dist: pandas>=1.1
+Requires-Dist: requests>=2.20
+Description-Content-Type: text/markdown
+
+# pytrends-ng: pytrends without the 429 errors
+
+[pytrends](https://github.com/GeneralMills/pytrends) was archived in April 2025 and its last release is from 2023. Google answers it with `429 Too Many Requests` most of the time. `pytrends-ng` keeps the same calls, so your code works again after changing one import:
+
+```python
+# from pytrends.request import TrendReq
+from pytrends_ng import TrendReq
+
+pytrends = TrendReq()  # reads APIFY_TOKEN from the environment
+pytrends.build_payload(["chatgpt", "claude", "gemini"], timeframe="today 3-m", geo="US")
+
+pytrends.interest_over_time()        # DataFrame: date index, one column per keyword, isPartial
+pytrends.interest_by_region()        # DataFrame: one row per region
+pytrends.related_queries()           # {keyword: {"top": DataFrame, "rising": DataFrame}}
+pytrends.trending_searches(pn="united_states")
+```
+
+## How it works
+
+The requests run on a hosted [Google Trends actor](https://apify.com/githubanassk/google-trends-scraper) on Apify, which rotates IPs and retries rate limits for you. No proxies to buy, no sleep loops.
+
+1. Create a free Apify account. It includes $5 of usage every month.
+2. Copy your API token from [Settings > Integrations](https://console.apify.com/settings/integrations).
+3. `pip install pytrends-ng` and `export APIFY_TOKEN=...`
+
+Pricing is $2 per 1,000 results, where one result is one keyword in one country with its full timeline, regions and related queries. A 5-keyword payload costs $0.01, so the free credit covers about 2,500 keywords a month.
+
+## Better than the original
+
+- **More than 5 keywords.** `build_payload` takes any number of keywords and puts them all on one shared 0-100 scale. Google's own limit is 5.
+- **Small keywords stay accurate.** Keywords far smaller than the biggest one keep decimal values instead of rounding to 0.
+- **One request per payload.** `interest_over_time`, `interest_by_region` and `related_queries` all read from the same run.
+
+## Supported calls
+
+| pytrends call | Status |
+|---|---|
+| `build_payload(kw_list, cat, timeframe, geo, gprop)` | Yes |
+| `interest_over_time()` | Yes |
+| `interest_by_region(resolution, inc_low_vol, inc_geo_code)` | COUNTRY, REGION, DMA (not CITY) |
+| `related_queries()` | Yes. `value` is numeric; `formattedValue` keeps Google's text such as `Breakout` |
+| `trending_searches(pn)`, `today_searches(pn)`, `realtime_trending_searches(pn)` | Yes |
+| `related_topics()`, `suggestions()` | Not yet |
+
+Constructor arguments such as `hl`, `tz`, `proxies` and `retries` are accepted and ignored, so existing code does not break.
+
+## License
+
+MIT. Not affiliated with Google or the original pytrends authors.

pytrends_ng-0.1.0/README.md

@@ -0,0 +1,49 @@
+# pytrends-ng: pytrends without the 429 errors
+
+[pytrends](https://github.com/GeneralMills/pytrends) was archived in April 2025 and its last release is from 2023. Google answers it with `429 Too Many Requests` most of the time. `pytrends-ng` keeps the same calls, so your code works again after changing one import:
+
+```python
+# from pytrends.request import TrendReq
+from pytrends_ng import TrendReq
+
+pytrends = TrendReq()  # reads APIFY_TOKEN from the environment
+pytrends.build_payload(["chatgpt", "claude", "gemini"], timeframe="today 3-m", geo="US")
+
+pytrends.interest_over_time()        # DataFrame: date index, one column per keyword, isPartial
+pytrends.interest_by_region()        # DataFrame: one row per region
+pytrends.related_queries()           # {keyword: {"top": DataFrame, "rising": DataFrame}}
+pytrends.trending_searches(pn="united_states")
+```
+
+## How it works
+
+The requests run on a hosted [Google Trends actor](https://apify.com/githubanassk/google-trends-scraper) on Apify, which rotates IPs and retries rate limits for you. No proxies to buy, no sleep loops.
+
+1. Create a free Apify account. It includes $5 of usage every month.
+2. Copy your API token from [Settings > Integrations](https://console.apify.com/settings/integrations).
+3. `pip install pytrends-ng` and `export APIFY_TOKEN=...`
+
+Pricing is $2 per 1,000 results, where one result is one keyword in one country with its full timeline, regions and related queries. A 5-keyword payload costs $0.01, so the free credit covers about 2,500 keywords a month.
+
+## Better than the original
+
+- **More than 5 keywords.** `build_payload` takes any number of keywords and puts them all on one shared 0-100 scale. Google's own limit is 5.
+- **Small keywords stay accurate.** Keywords far smaller than the biggest one keep decimal values instead of rounding to 0.
+- **One request per payload.** `interest_over_time`, `interest_by_region` and `related_queries` all read from the same run.
+
+## Supported calls
+
+| pytrends call | Status |
+|---|---|
+| `build_payload(kw_list, cat, timeframe, geo, gprop)` | Yes |
+| `interest_over_time()` | Yes |
+| `interest_by_region(resolution, inc_low_vol, inc_geo_code)` | COUNTRY, REGION, DMA (not CITY) |
+| `related_queries()` | Yes. `value` is numeric; `formattedValue` keeps Google's text such as `Breakout` |
+| `trending_searches(pn)`, `today_searches(pn)`, `realtime_trending_searches(pn)` | Yes |
+| `related_topics()`, `suggestions()` | Not yet |
+
+Constructor arguments such as `hl`, `tz`, `proxies` and `retries` are accepted and ignored, so existing code does not break.
+
+## License
+
+MIT. Not affiliated with Google or the original pytrends authors.

pytrends_ng-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytrends-ng"
+dynamic = ["version"]
+description = "Drop-in replacement for the archived pytrends: Google Trends without 429 errors, unlimited keywords on one scale."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+dependencies = ["pandas>=1.1", "requests>=2.20"]
+keywords = ["pytrends", "google trends", "google trends api", "trends", "seo", "keyword research"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Internet :: WWW/HTTP", "Intended Audience :: Developers"]
+
+[project.urls]
+"Google Trends actor" = "https://apify.com/githubanassk/google-trends-scraper"
+
+[tool.hatch.version]
+path = "pytrends_ng/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pytrends_ng"]

pytrends_ng-0.1.0/pytrends_ng/__init__.py

@@ -0,0 +1,155 @@
+"""Drop-in replacement for the archived pytrends library.
+
+Same calls as pytrends (TrendReq, build_payload, interest_over_time, ...), but the
+data comes from a hosted Google Trends actor on Apify, so there are no 429 errors
+to handle on your side. Needs an Apify API token (free account, $5 monthly credit).
+"""
+import os
+import re
+
+import pandas as pd
+import requests
+
+__version__ = "0.1.0"
+__all__ = ["TrendReq", "TrendsError"]
+
+ACTOR = "githubanassk~google-trends-scraper"
+API = "https://api.apify.com/v2/acts/{actor}/run-sync-get-dataset-items"
+
+# pytrends' trending_searches(pn=...) takes country names; the actor takes ISO codes.
+# ponytail: common countries only; any two-letter code also works.
+COUNTRY_CODES = {
+    "united_states": "US", "united_kingdom": "GB", "canada": "CA", "australia": "AU",
+    "india": "IN", "germany": "DE", "france": "FR", "japan": "JP", "brazil": "BR",
+    "mexico": "MX", "spain": "ES", "italy": "IT", "netherlands": "NL", "south_korea": "KR",
+    "indonesia": "ID", "turkey": "TR", "poland": "PL", "south_africa": "ZA", "nigeria": "NG",
+    "philippines": "PH", "singapore": "SG", "sweden": "SE", "argentina": "AR",
+}
+GPROP = {"": "", "images": "images", "news": "news", "youtube": "youtube", "froogle": "froogle"}
+
+
+class TrendsError(Exception):
+    pass
+
+
+def _number(formatted):
+    """'+3,800%' -> 3800, '100' -> 100, 'Breakout' -> None (see formattedValue)."""
+    digits = re.sub(r"[^\d]", "", str(formatted))
+    return int(digits) if digits else None
+
+
+class TrendReq:
+    def __init__(self, hl="en-US", tz=360, geo="", timeout=None, proxies=None, retries=0,
+                 backoff_factor=0, requests_args=None, apify_token=None, actor=ACTOR):
+        # hl, tz, timeout, proxies, retries, backoff_factor and requests_args are
+        # accepted for pytrends compatibility; the actor handles proxies and retries.
+        token = apify_token or os.environ.get("APIFY_TOKEN")
+        if not token:
+            raise TrendsError("Set APIFY_TOKEN or pass apify_token=... "
+                              "(free at https://console.apify.com/settings/integrations).")
+        self._token, self._url = token, API.format(actor=actor.replace("/", "~"))
+        self._timeout = timeout if isinstance(timeout, (int, float)) else 300
+        self.geo = geo
+        self.kw_list, self.cat, self.timeframe, self.gprop = [], 0, "today 5-y", ""
+        self._runs = {}
+
+    def build_payload(self, kw_list, cat=0, timeframe="today 5-y", geo="", gprop=""):
+        if gprop not in GPROP:
+            raise ValueError("gprop must be empty or one of images, news, youtube, froogle")
+        self.kw_list, self.cat, self.timeframe, self.gprop = list(kw_list), cat, timeframe, gprop
+        self.geo = geo or self.geo
+        self._runs = {}  # new payload, new data
+
+    def _run(self, run_input):
+        """One HTTP call: start the actor, wait for it, return its rows."""
+        resp = requests.post(self._url, json=run_input, timeout=self._timeout,
+                             headers={"Authorization": f"Bearer {self._token}"})
+        if resp.status_code >= 300:
+            try:
+                msg = resp.json()["error"]["message"]
+            except (ValueError, KeyError, TypeError):
+                msg = resp.text[:300]
+            raise TrendsError(f"Google Trends request failed ({resp.status_code}): {msg}")
+        return resp.json()
+
+    def _keywords(self, region_level=""):
+        """One actor run per payload (and per region level); every method reads from it."""
+        if not self.kw_list:
+            raise TrendsError("Call build_payload(kw_list=[...]) first.")
+        if region_level not in self._runs:
+            rows = self._run({
+                "keywords": self.kw_list, "geos": [self.geo] if self.geo else [],
+                "timeframe": self.timeframe, "category": self.cat,
+                "searchProperty": self.gprop, "regionLevel": region_level,
+                "includeRelatedQueries": True,
+            })
+            self._runs[region_level] = {r["keyword"]: r for r in rows if r.get("type") == "keyword"}
+        return self._runs[region_level]
+
+    def interest_over_time(self):
+        """DataFrame indexed by date, one column per keyword (shared 0-100 scale), plus isPartial."""
+        rows = self._keywords()
+        df = pd.DataFrame({
+            kw: pd.Series({pd.Timestamp(p["date"]).tz_localize(None): p["value"] for p in rows[kw]["timeline"]})
+            for kw in self.kw_list if kw in rows
+        })
+        if df.empty:
+            return df
+        df.index.name = "date"
+        df["isPartial"] = False
+        return df
+
+    def interest_by_region(self, resolution="COUNTRY", inc_low_vol=True, inc_geo_code=False):
+        # Worldwide + COUNTRY is the actor's automatic level; a country geo needs an explicit level.
+        level = "" if resolution == "COUNTRY" and not self.geo else resolution.upper()
+        if level == "CITY":
+            raise TrendsError("City resolution is not supported; use REGION or DMA.")
+        rows = self._keywords(level)
+        frames = {}
+        for kw in self.kw_list:
+            regions = (rows.get(kw) or {}).get("interestByRegion") or []
+            frames[kw] = pd.Series({r["geoName"]: r["value"] for r in regions})
+        df = pd.DataFrame(frames)
+        df.index.name = "geoName"
+        if not inc_low_vol:
+            df = df[(df.fillna(0) > 0).any(axis=1)]
+        if inc_geo_code:
+            codes = {r["geoName"]: r["geoCode"] for kw in self.kw_list
+                     for r in (rows.get(kw) or {}).get("interestByRegion") or []}
+            df.insert(0, "geoCode", df.index.map(codes))
+        return df
+
+    def related_queries(self):
+        """{keyword: {"top": DataFrame, "rising": DataFrame}} like pytrends."""
+        rows = self._keywords()
+        out = {}
+        for kw in self.kw_list:
+            r = rows.get(kw) or {}
+            out[kw] = {}
+            for key, field in (("top", "relatedQueriesTop"), ("rising", "relatedQueriesRising")):
+                items = r.get(field) or []
+                out[kw][key] = pd.DataFrame(
+                    [{"query": q["query"], "value": _number(q["value"]), "formattedValue": q["value"]} for q in items],
+                    columns=["query", "value", "formattedValue"],
+                ) if items else None
+        return out
+
+    def trending_searches(self, pn="united_states"):
+        """DataFrame with one column (0) of trending search titles, like pytrends."""
+        df = self.realtime_trending_searches(pn)
+        return pd.DataFrame({0: df["title"]}) if not df.empty else pd.DataFrame({0: []})
+
+    def realtime_trending_searches(self, pn="US", cat="all", count=300):
+        code = pn.upper() if len(pn) == 2 else COUNTRY_CODES.get(pn.lower())
+        if not code:
+            raise ValueError(f"Unknown country '{pn}'. Use a two-letter code such as US or GB.")
+        rows = [r for r in self._run({"trendingNowGeos": [code]}) if r.get("type") == "trendingNow"]
+        return pd.DataFrame(rows[:count])
+
+    today_searches = trending_searches
+
+    def related_topics(self):
+        raise TrendsError("related_topics is not available yet; related_queries is.")
+
+    def suggestions(self, keyword):
+        raise TrendsError("suggestions is not available yet.")

pytrends_ng-0.1.0/test_pytrends_ng.py

@@ -0,0 +1,58 @@
+"""Offline check: fake actor rows in, pytrends-shaped DataFrames out."""
+import pytrends_ng
+from pytrends_ng import TrendReq, _number
+
+ROWS = [
+    {"type": "keyword", "keyword": "claude",
+     "timeline": [{"date": "2026-07-10T00:00:00Z", "value": 23}, {"date": "2026-07-11T00:00:00Z", "value": 20.5}],
+     "interestByRegion": [{"geoCode": "US-CA", "geoName": "California", "value": 100},
+                          {"geoCode": "US-TX", "geoName": "Texas", "value": 0}],
+     "relatedQueriesTop": [{"query": "claude ai", "value": "100"}],
+     "relatedQueriesRising": [{"query": "claude 5", "value": "+3,800%"}, {"query": "claude code", "value": "Breakout"}]},
+    {"type": "keyword", "keyword": "gemini",
+     "timeline": [{"date": "2026-07-10T00:00:00Z", "value": 40}, {"date": "2026-07-11T00:00:00Z", "value": 37}],
+     "interestByRegion": [{"geoCode": "US-CA", "geoName": "California", "value": 80}],
+     "relatedQueriesTop": [], "relatedQueriesRising": []},
+    {"type": "trendingNow", "geo": "US", "title": "chicago marathon", "approxTraffic": "2000+"},
+]
+
+
+def make(calls):
+    t = TrendReq(apify_token="x")
+
+    def fake_run(run_input):
+        calls.append(run_input)
+        return ROWS
+    t._run = fake_run
+    return t
+
+
+def test_pytrends_shapes():
+    calls = []
+    t = make(calls)
+    t.build_payload(["claude", "gemini"], timeframe="today 3-m", geo="US")
+
+    iot = t.interest_over_time()
+    assert list(iot.columns) == ["claude", "gemini", "isPartial"]
+    assert iot.index.name == "date" and iot["claude"].iloc[1] == 20.5
+
+    rq = t.related_queries()
+    assert rq["claude"]["rising"]["value"].tolist()[0] == 3800
+    assert rq["claude"]["rising"]["formattedValue"].tolist()[1] == "Breakout"
+    assert rq["gemini"]["top"] is None
+    assert len(calls) == 1  # one run serves every method for the same payload
+
+    ibr = t.interest_by_region(resolution="REGION", inc_low_vol=False, inc_geo_code=True)
+    assert calls[-1]["regionLevel"] == "REGION" and len(calls) == 2
+    assert list(ibr.index) == ["California"] and ibr.loc["California", "geoCode"] == "US-CA"
+
+    assert t.trending_searches(pn="united_states")[0].tolist() == ["chicago marathon"]
+    assert calls[-1] == {"trendingNowGeos": ["US"]}
+
+
+def test_number():
+    assert _number("+1,650%") == 1650 and _number("Breakout") is None and _number("81") == 81
+
+
+if __name__ == "__main__":
+    test_pytrends_shapes(); test_number(); print("ok", pytrends_ng.__version__)