pytrends-next 0.1.0__tar.gz

pytrends_next-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ctrio Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytrends_next-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

pytrends_next-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: pytrends-next
+Version: 0.1.0
+Summary: Maintained drop-in replacement for pytrends (archived): Google Trends with the TrendReq API, standard library only, optional hosted fallback on HTTP 429.
+Author-email: Ctrio Lab <myhouse9600@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ctriolab/google-trends-python
+Project-URL: Issues, https://github.com/ctriolab/google-trends-python/issues
+Project-URL: Hosted fallback, https://apify.com/ctriolab/google-trends-scraper
+Keywords: google trends,pytrends,trends,seo,keyword research,429
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == "pandas"
+Dynamic: license-file
+
+# pytrends-next
+
+A maintained drop-in replacement for [pytrends](https://github.com/GeneralMills/pytrends), which was archived
+(read-only) in April 2025. Same `TrendReq` API, same DataFrames, talks to Google Trends directly.
+
+- Standard library only. pandas is optional: with pandas you get the same DataFrames as pytrends,
+  without it you get lists of dicts.
+- Python 3.9+.
+- Built-in handling of HTTP 429: new cookie session and exponential backoff with jitter.
+- Optional, paid, off by default: route a call through a hosted scraper when Google keeps answering 429.
+
+```bash
+pip install "pytrends-next[pandas]"     # or: pip install pytrends-next   (no pandas)
+```
+
+```python
+from pytrends_next.request import TrendReq   # was: from pytrends.request import TrendReq
+
+pytrends = TrendReq(hl="en-US", tz=360)
+pytrends.build_payload(["coffee", "tea"], timeframe="today 3-m", geo="US")
+print(pytrends.interest_over_time().head(3))
+#             coffee  tea  isPartial
+# date
+# 2026-07-23      75   35      False
+# 2026-07-24      81   38      False
+# 2026-07-25      94   40      False
+```
+
+For most code the migration is one search and replace: `pytrends.` to `pytrends_next.` in imports.
+`pytrends_next.exceptions` has the same `ResponseError` and `TooManyRequestsError`.
+
+## Moving from pytrends
+
+| pytrends 4.9.2 | pytrends-next | Notes |
+|---|---|---|
+| `TrendReq(hl, tz, geo, timeout, proxies, retries, backoff_factor, requests_args)` | same | `timeout` tuple: the larger value is used (urllib has one timeout). `requests_args`: `headers`, `proxies` and `verify` are used, other keys are ignored with a warning. `retries` defaults to 3 (pytrends: 0). |
+| `build_payload(kw_list, cat, timeframe, geo, gprop)` | same | Lists of geos and timeframes work as in pytrends. |
+| `interest_over_time()` | same | Index `date`, one int column per keyword, `isPartial`. MultiIndex columns for several geos. |
+| `interest_by_region(resolution, inc_low_vol, inc_geo_code)` | same | pytrends' check meant to apply `resolution` worldwide and for sub-levels never matched; here it does. |
+| `related_queries()` | same | `{kw: {"top": DataFrame[query, value] or None, "rising": ...}}` |
+| `related_topics()` | same | Google now returns topics only for single-term requests, so each term is asked alone. Often empty, see Limits. |
+| `trending_searches(pn="united_states")` | same | The old endpoint is gone. Now served from Google's "Trending now" list. `pn` takes the pytrends country name or an ISO code (`"US"`). |
+| `today_searches(pn="US")` | same | Series of titles, past 24 hours. |
+| `realtime_trending_searches(pn, cat, count)` | same | Trends started in the past 4 hours, columns `entityNames`, `title`. `cat` is ignored. |
+| `suggestions(keyword)` | same | |
+| `categories()` | same | |
+| `top_charts()` | raises `NotImplementedError` | Google removed the endpoint. |
+| `multirange_interest_over_time()` | raises `NotImplementedError` | Not ported yet. |
+| (none) | `trending_now(geo="US", hours=24)` | New. Rows with `title`, `volume`, `increase_percentage`, `started`, `ended`, `active`, `categories`, `related_queries`. `hours`: 4, 24, 48 or 168. Falls back to the Trending RSS feed if the main endpoint changes. |
+
+## HTTP 429 (TooManyRequestsError)
+
+Google Trends has no public API. It rate-limits by IP and by session, and a laptop or a single
+server often gets HTTP 429 after a few dozen requests. pytrends raised `TooManyRequestsError` at once.
+
+pytrends-next does what our hosted scraper does on every request:
+
+1. Visits trends.google.com first to get the `NID` cookie a browser visitor has (cookieless clients are limited sooner).
+2. On 429, 403 or 5xx: drops the session, takes the next proxy from `proxies=[...]` if you gave any,
+   waits about 0.75 s, 1.5 s, 3 s ... (capped at 30 s, with jitter) and tries again, `retries` times.
+3. 400 and 404 are not retried (bad geo, category or timeframe).
+
+If you still get `TooManyRequestsError`: send fewer requests (batch up to 5 terms per `build_payload`),
+wait a few minutes, use your own proxies, or use the hosted fallback below.
+
+## Hosted fallback (optional, paid)
+
+```python
+pytrends = TrendReq(fallback="apify", apify_token="apify_api_...")   # or set APIFY_TOKEN
+```
+
+When Google still answers 429 after the local retries, the same call is sent to the
+[Google Trends Scraper Actor on Apify](https://apify.com/ctriolab/google-trends-scraper?utm_source=github&utm_medium=readme&utm_campaign=pytrends-next),
+which rotates IPs on Apify's proxy network. The result comes back in the same shape.
+
+- **It costs money.** The Actor is billed per result to your own Apify account (about $1.50 per 1,000
+  results; one result is one term's timeline, one term's region list, one term's related list or one trending topic).
+  Apify's free plan includes a small monthly credit.
+- It is never on by default. Setting `APIFY_TOKEN` alone does nothing; you must pass `fallback="apify"`.
+- A warning is logged (logger `pytrends_next`) every time a call goes to the Actor.
+- If `build_payload` itself gets 429, every method on that payload goes to the Actor.
+- Supported: `interest_over_time`, `interest_by_region`, `related_queries`, `related_topics`, `trending_now`
+  and the pytrends trending methods. Not supported: several geos or timeframes in one payload,
+  commas inside a keyword, `suggestions`, `categories`.
+- Difference: in hosted mode each term's region map is scaled on its own (locally, the terms share one scale).
+- Timeframes: the named ranges (`now 1-H` to `today 5-y`, `all`) and `YYYY-MM-DD YYYY-MM-DD`. Others are rejected before a run starts.
+
+Disclosure: Ctrio Lab maintains this library and also builds and sells that Actor. The library is MIT
+licensed and fully works without it.
+
+## Limits
+
+- Values are relative (0 to 100) within one payload, as on trends.google.com. Separate calls are not on the same scale.
+- Related topics are usually empty: Google hides them from clients it classifies as automated. Empty lists come back as `None`, like pytrends.
+- Very small search volumes come back as all zeros (Google's own behaviour).
+- This is an unofficial client for undocumented endpoints. Google can change them at any time.
+
+## Legacy single-file client
+
+`gtrends.py` (the earlier version of this repo) is still here and unchanged. It calls the hosted Actor for
+every request. New code should use `pytrends_next.request.TrendReq`: `gtrends.interest_over_time_df(terms, ...)`
+becomes `build_payload(terms, ...)` plus `interest_over_time()`.
+
+## Development
+
+```bash
+python -m unittest discover -s tests     # no network, recorded responses in tests/fixtures
+python tests/live_smoke.py               # about 12 live requests to Google
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pytrends_next-0.1.0/README.md

@@ -0,0 +1,113 @@
+# pytrends-next
+
+A maintained drop-in replacement for [pytrends](https://github.com/GeneralMills/pytrends), which was archived
+(read-only) in April 2025. Same `TrendReq` API, same DataFrames, talks to Google Trends directly.
+
+- Standard library only. pandas is optional: with pandas you get the same DataFrames as pytrends,
+  without it you get lists of dicts.
+- Python 3.9+.
+- Built-in handling of HTTP 429: new cookie session and exponential backoff with jitter.
+- Optional, paid, off by default: route a call through a hosted scraper when Google keeps answering 429.
+
+```bash
+pip install "pytrends-next[pandas]"     # or: pip install pytrends-next   (no pandas)
+```
+
+```python
+from pytrends_next.request import TrendReq   # was: from pytrends.request import TrendReq
+
+pytrends = TrendReq(hl="en-US", tz=360)
+pytrends.build_payload(["coffee", "tea"], timeframe="today 3-m", geo="US")
+print(pytrends.interest_over_time().head(3))
+#             coffee  tea  isPartial
+# date
+# 2026-07-23      75   35      False
+# 2026-07-24      81   38      False
+# 2026-07-25      94   40      False
+```
+
+For most code the migration is one search and replace: `pytrends.` to `pytrends_next.` in imports.
+`pytrends_next.exceptions` has the same `ResponseError` and `TooManyRequestsError`.
+
+## Moving from pytrends
+
+| pytrends 4.9.2 | pytrends-next | Notes |
+|---|---|---|
+| `TrendReq(hl, tz, geo, timeout, proxies, retries, backoff_factor, requests_args)` | same | `timeout` tuple: the larger value is used (urllib has one timeout). `requests_args`: `headers`, `proxies` and `verify` are used, other keys are ignored with a warning. `retries` defaults to 3 (pytrends: 0). |
+| `build_payload(kw_list, cat, timeframe, geo, gprop)` | same | Lists of geos and timeframes work as in pytrends. |
+| `interest_over_time()` | same | Index `date`, one int column per keyword, `isPartial`. MultiIndex columns for several geos. |
+| `interest_by_region(resolution, inc_low_vol, inc_geo_code)` | same | pytrends' check meant to apply `resolution` worldwide and for sub-levels never matched; here it does. |
+| `related_queries()` | same | `{kw: {"top": DataFrame[query, value] or None, "rising": ...}}` |
+| `related_topics()` | same | Google now returns topics only for single-term requests, so each term is asked alone. Often empty, see Limits. |
+| `trending_searches(pn="united_states")` | same | The old endpoint is gone. Now served from Google's "Trending now" list. `pn` takes the pytrends country name or an ISO code (`"US"`). |
+| `today_searches(pn="US")` | same | Series of titles, past 24 hours. |
+| `realtime_trending_searches(pn, cat, count)` | same | Trends started in the past 4 hours, columns `entityNames`, `title`. `cat` is ignored. |
+| `suggestions(keyword)` | same | |
+| `categories()` | same | |
+| `top_charts()` | raises `NotImplementedError` | Google removed the endpoint. |
+| `multirange_interest_over_time()` | raises `NotImplementedError` | Not ported yet. |
+| (none) | `trending_now(geo="US", hours=24)` | New. Rows with `title`, `volume`, `increase_percentage`, `started`, `ended`, `active`, `categories`, `related_queries`. `hours`: 4, 24, 48 or 168. Falls back to the Trending RSS feed if the main endpoint changes. |
+
+## HTTP 429 (TooManyRequestsError)
+
+Google Trends has no public API. It rate-limits by IP and by session, and a laptop or a single
+server often gets HTTP 429 after a few dozen requests. pytrends raised `TooManyRequestsError` at once.
+
+pytrends-next does what our hosted scraper does on every request:
+
+1. Visits trends.google.com first to get the `NID` cookie a browser visitor has (cookieless clients are limited sooner).
+2. On 429, 403 or 5xx: drops the session, takes the next proxy from `proxies=[...]` if you gave any,
+   waits about 0.75 s, 1.5 s, 3 s ... (capped at 30 s, with jitter) and tries again, `retries` times.
+3. 400 and 404 are not retried (bad geo, category or timeframe).
+
+If you still get `TooManyRequestsError`: send fewer requests (batch up to 5 terms per `build_payload`),
+wait a few minutes, use your own proxies, or use the hosted fallback below.
+
+## Hosted fallback (optional, paid)
+
+```python
+pytrends = TrendReq(fallback="apify", apify_token="apify_api_...")   # or set APIFY_TOKEN
+```
+
+When Google still answers 429 after the local retries, the same call is sent to the
+[Google Trends Scraper Actor on Apify](https://apify.com/ctriolab/google-trends-scraper?utm_source=github&utm_medium=readme&utm_campaign=pytrends-next),
+which rotates IPs on Apify's proxy network. The result comes back in the same shape.
+
+- **It costs money.** The Actor is billed per result to your own Apify account (about $1.50 per 1,000
+  results; one result is one term's timeline, one term's region list, one term's related list or one trending topic).
+  Apify's free plan includes a small monthly credit.
+- It is never on by default. Setting `APIFY_TOKEN` alone does nothing; you must pass `fallback="apify"`.
+- A warning is logged (logger `pytrends_next`) every time a call goes to the Actor.
+- If `build_payload` itself gets 429, every method on that payload goes to the Actor.
+- Supported: `interest_over_time`, `interest_by_region`, `related_queries`, `related_topics`, `trending_now`
+  and the pytrends trending methods. Not supported: several geos or timeframes in one payload,
+  commas inside a keyword, `suggestions`, `categories`.
+- Difference: in hosted mode each term's region map is scaled on its own (locally, the terms share one scale).
+- Timeframes: the named ranges (`now 1-H` to `today 5-y`, `all`) and `YYYY-MM-DD YYYY-MM-DD`. Others are rejected before a run starts.
+
+Disclosure: Ctrio Lab maintains this library and also builds and sells that Actor. The library is MIT
+licensed and fully works without it.
+
+## Limits
+
+- Values are relative (0 to 100) within one payload, as on trends.google.com. Separate calls are not on the same scale.
+- Related topics are usually empty: Google hides them from clients it classifies as automated. Empty lists come back as `None`, like pytrends.
+- Very small search volumes come back as all zeros (Google's own behaviour).
+- This is an unofficial client for undocumented endpoints. Google can change them at any time.
+
+## Legacy single-file client
+
+`gtrends.py` (the earlier version of this repo) is still here and unchanged. It calls the hosted Actor for
+every request. New code should use `pytrends_next.request.TrendReq`: `gtrends.interest_over_time_df(terms, ...)`
+becomes `build_payload(terms, ...)` plus `interest_over_time()`.
+
+## Development
+
+```bash
+python -m unittest discover -s tests     # no network, recorded responses in tests/fixtures
+python tests/live_smoke.py               # about 12 live requests to Google
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pytrends_next-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytrends-next"
+version = "0.1.0"
+description = "Maintained drop-in replacement for pytrends (archived): Google Trends with the TrendReq API, standard library only, optional hosted fallback on HTTP 429."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ctrio Lab", email = "myhouse9600@gmail.com" }]
+keywords = ["google trends", "pytrends", "trends", "seo", "keyword research", "429"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.3"]
+
+[project.urls]
+Homepage = "https://github.com/ctriolab/google-trends-python"
+Issues = "https://github.com/ctriolab/google-trends-python/issues"
+"Hosted fallback" = "https://apify.com/ctriolab/google-trends-scraper"

pytrends_next-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pytrends_next-0.1.0/src/pytrends_next/__init__.py

@@ -0,0 +1,6 @@
+"""Maintained drop-in replacement for pytrends: `from pytrends_next.request import TrendReq`."""
+from .exceptions import ResponseError, TooManyRequestsError
+from .request import TrendReq
+
+__version__ = "0.1.0"
+__all__ = ["TrendReq", "ResponseError", "TooManyRequestsError"]

pytrends_next-0.1.0/src/pytrends_next/exceptions.py

@@ -0,0 +1,17 @@
+"""Same exception names as pytrends.exceptions, so existing `except` blocks keep working."""
+
+
+class ResponseError(Exception):
+    """Google (or the hosted fallback) answered with an error. `response` has status_code, text and url."""
+
+    def __init__(self, message, response=None):
+        super().__init__(message)
+        self.response = response
+
+    @classmethod
+    def from_response(cls, response):
+        return cls(f"The request failed: Google returned a response with code {response.status_code}", response)
+
+
+class TooManyRequestsError(ResponseError):
+    """HTTP 429: Google rate-limited this IP or session."""

pytrends_next-0.1.0/src/pytrends_next/hosted.py

@@ -0,0 +1,48 @@
+"""Opt-in hosted fallback: the Ctrio Lab "Google Trends Scraper" Actor on Apify.
+
+This is a PAID service billed per result to the caller's own Apify account (APIFY_TOKEN).
+It is only used when TrendReq(fallback="apify") is set and Google answered HTTP 429.
+Disclosure: Ctrio Lab builds both this library and the Actor.
+"""
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from types import SimpleNamespace
+
+from .exceptions import ResponseError
+
+ACTOR = "ctriolab~google-trends-scraper"
+API = f"https://api.apify.com/v2/acts/{ACTOR}/run-sync-get-dataset-items"
+ACTOR_URL = "https://apify.com/ctriolab/google-trends-scraper"
+TIMEFRAMES = {"now 1-H", "now 4-H", "now 1-d", "now 7-d", "today 1-m", "today 3-m", "today 12-m", "today 5-y", "all"}
+_CUSTOM = re.compile(r"^\d{4}-\d{2}-\d{2}(T\d{2})? \d{4}-\d{2}-\d{2}(T\d{2})?$")
+
+
+def timeframe(tf: str) -> dict:
+    """pytrends timeframe -> Actor input fields. Rejects what the Actor would reject, before a paid run."""
+    if tf in TIMEFRAMES:
+        return {"timeframe": tf}
+    if isinstance(tf, str) and _CUSTOM.match(tf.strip()):
+        return {"timeframe": "custom", "customTimeRange": tf.strip()}
+    raise ValueError(f'The hosted fallback does not support timeframe "{tf}". '
+                     f'Use one of {sorted(TIMEFRAMES)} or "YYYY-MM-DD YYYY-MM-DD".')
+
+
+def run(actor_input: dict, token: str, timeout: int = 300) -> list:
+    """Run the Actor synchronously and return its dataset items."""
+    req = urllib.request.Request(
+        f"{API}?timeout={timeout}",
+        data=json.dumps(actor_input).encode("utf-8"),
+        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout + 30) as res:
+            return json.loads(res.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", "replace")[:500]
+        raise ResponseError(f"Apify API returned HTTP {e.code}: {body}",
+                            SimpleNamespace(status_code=e.code, text=body, url=API)) from None

pytrends_next-0.1.0/src/pytrends_next/request.py

@@ -0,0 +1,526 @@
+"""TrendReq: the pytrends API, talking to Google Trends directly with the standard library.
+
+Differences from pytrends 4.9.2 are listed in README.md ("Moving from pytrends").
+"""
+from __future__ import annotations
+
+import http.cookiejar
+import json
+import logging
+import os
+import random
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import warnings
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from itertools import product
+from types import SimpleNamespace
+
+from . import hosted
+from .exceptions import ResponseError, TooManyRequestsError
+
+try:
+    import pandas as pd
+except ImportError:  # pandas is optional: without it, methods return lists of dicts
+    pd = None
+
+log = logging.getLogger("pytrends_next")
+
+BASE = "https://trends.google.com"
+BASE_TRENDS_URL = f"{BASE}/trends"
+USER_AGENT = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+              "(KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36")
+
+TRENDING_CATEGORIES = {
+    1: "Autos and Vehicles", 2: "Beauty and Fashion", 3: "Business and Finance", 4: "Entertainment",
+    5: "Food and Drink", 6: "Games", 7: "Health", 8: "Hobbies and Leisure", 9: "Jobs and Education",
+    10: "Law and Government", 11: "Other", 13: "Pets and Animals", 14: "Politics", 15: "Science",
+    16: "Shopping", 17: "Sports", 18: "Technology", 19: "Travel and Transportation", 20: "Climate",
+}
+
+# pytrends trending_searches(pn=...) used country names; Trending now uses ISO codes.
+PN_GEO = {
+    "argentina": "AR", "australia": "AU", "austria": "AT", "belgium": "BE", "brazil": "BR", "canada": "CA",
+    "chile": "CL", "colombia": "CO", "czech_republic": "CZ", "denmark": "DK", "egypt": "EG", "finland": "FI",
+    "france": "FR", "germany": "DE", "greece": "GR", "hong_kong": "HK", "hungary": "HU", "india": "IN",
+    "indonesia": "ID", "ireland": "IE", "israel": "IL", "italy": "IT", "japan": "JP", "kenya": "KE",
+    "malaysia": "MY", "mexico": "MX", "netherlands": "NL", "new_zealand": "NZ", "nigeria": "NG", "norway": "NO",
+    "peru": "PE", "philippines": "PH", "poland": "PL", "portugal": "PT", "romania": "RO", "russia": "RU",
+    "saudi_arabia": "SA", "singapore": "SG", "south_africa": "ZA", "south_korea": "KR", "spain": "ES",
+    "sweden": "SE", "switzerland": "CH", "taiwan": "TW", "thailand": "TH", "turkey": "TR", "ukraine": "UA",
+    "united_kingdom": "GB", "united_states": "US", "vietnam": "VN",
+}
+
+
+def _json(text):
+    """Google prefixes JSON with )]}' to stop JSON hijacking; drop everything before the first brace."""
+    i = text.find("{")
+    if i < 0:
+        raise ValueError("no JSON in response")
+    return json.loads(text[i:])
+
+
+def _ts(seconds):
+    return datetime.fromtimestamp(int(seconds), timezone.utc).replace(tzinfo=None)
+
+
+def _iso(s):
+    return datetime.fromisoformat(s.replace("Z", "+00:00")).replace(tzinfo=None) if s else None
+
+
+def _frame(rows, index=None):
+    """DataFrame like pytrends when pandas is installed, else the rows themselves."""
+    if pd is None:
+        return rows
+    df = pd.DataFrame(rows)
+    if index and not df.empty:
+        df = df.set_index(index).sort_index()
+    return df
+
+
+def _flat(d, prefix=""):
+    """pd.json_normalize(sep='_') for one dict, without pandas."""
+    out = {}
+    for k, v in d.items():
+        if isinstance(v, dict):
+            out.update(_flat(v, f"{prefix}{k}_"))
+        else:
+            out[f"{prefix}{k}"] = v
+    return out
+
+
+def _ranked(data, i, flat):
+    """rankedList[i] (0 = top, 1 = rising) as pytrends returns it: None when Google sent no list."""
+    try:
+        rows = data["rankedList"][i]["rankedKeyword"]
+    except (KeyError, IndexError, TypeError):
+        return None
+    if flat:
+        return _frame([_flat(r) for r in rows])
+    if not rows:
+        return None  # pytrends: empty DataFrame[['query','value']] raised KeyError -> None
+    return _frame([{"query": r.get("query"), "value": r.get("value")} for r in rows])
+
+
+class TrendReq:
+    """Google Trends client with the pytrends TrendReq interface.
+
+    fallback="apify": when Google answers HTTP 429 after `retries`, run the same request through the
+    hosted Google Trends Scraper Actor on Apify. Paid per result on your own Apify account
+    (apify_token=... or the APIFY_TOKEN environment variable). Off by default.
+    """
+
+    GENERAL_URL = f"{BASE_TRENDS_URL}/api/explore"
+    INTEREST_OVER_TIME_URL = f"{BASE_TRENDS_URL}/api/widgetdata/multiline"
+    INTEREST_BY_REGION_URL = f"{BASE_TRENDS_URL}/api/widgetdata/comparedgeo"
+    RELATED_QUERIES_URL = f"{BASE_TRENDS_URL}/api/widgetdata/relatedsearches"
+    SUGGESTIONS_URL = f"{BASE_TRENDS_URL}/api/autocomplete/"
+    CATEGORIES_URL = f"{BASE_TRENDS_URL}/api/explore/pickers/category"
+    TRENDING_NOW_URL = f"{BASE}/_/TrendsUi/data/batchexecute"
+    TRENDING_RSS_URL = f"{BASE}/trending/rss"
+
+    def __init__(self, hl="en-US", tz=360, geo="", timeout=(2, 5), proxies="", retries=3, backoff_factor=0,
+                 requests_args=None, fallback=None, apify_token=None):
+        if fallback not in (None, "apify"):
+            raise ValueError('fallback must be None or "apify"')
+        self.hl = hl
+        self.tz = tz
+        self.geo = geo
+        self.kw_list = []
+        # urllib has one timeout; pytrends passed (connect, read) to requests.
+        self.timeout = max(timeout) if isinstance(timeout, (tuple, list)) else timeout
+        self.proxies = list(proxies) if proxies else []
+        self.proxy_index = 0
+        self.retries = retries
+        self.backoff_factor = backoff_factor
+        args = dict(requests_args or {})
+        self.headers = {"accept-language": hl, "user-agent": USER_AGENT}
+        self.headers.update(args.pop("headers", {}))
+        self._proxy_map = args.pop("proxies", None)
+        self._ssl = None if args.pop("verify", True) else ssl._create_unverified_context()
+        if args:
+            warnings.warn(f"pytrends_next ignores these requests_args: {sorted(args)}")
+        self.fallback = fallback
+        self.apify_token = apify_token or os.environ.get("APIFY_TOKEN")
+        if fallback and not self.apify_token:
+            raise ValueError('fallback="apify" needs apify_token=... or the APIFY_TOKEN environment variable')
+        self.cookies = {}
+        self._opener = None
+        self._hosted = False
+        self._query = {}
+        self.token_payload = {}
+        self.interest_over_time_widget = {}
+        self.interest_by_region_widget = {}
+        self.related_topics_widget_list = []
+        self.related_queries_widget_list = []
+
+    # HTTP -------------------------------------------------------------------------------------------
+
+    def _fetch(self, url, data=None, headers=None):
+        """One HTTP request, returns (status, text). Unit tests replace this method."""
+        req = urllib.request.Request(url, data=data, headers={**self.headers, **(headers or {})})
+        try:
+            with self._opener.open(req, timeout=self.timeout) as res:
+                return res.status, res.read().decode("utf-8", "replace")
+        except urllib.error.HTTPError as e:
+            return e.code, e.read().decode("utf-8", "replace")
+
+    def _new_session(self):
+        """Fresh cookie jar (and the next proxy), then fetch the NID cookie a browser visitor would have.
+        Google rate-limits cookieless clients much sooner."""
+        jar = http.cookiejar.CookieJar()
+        handlers = [urllib.request.HTTPCookieProcessor(jar), urllib.request.HTTPSHandler(context=self._ssl)]
+        proxy = self._proxy_map or ({"https": self.proxies[self.proxy_index]} if self.proxies else None)
+        if proxy:
+            handlers.append(urllib.request.ProxyHandler(proxy))
+        if self.proxies:
+            self.proxy_index = (self.proxy_index + 1) % len(self.proxies)
+        self._opener = urllib.request.build_opener(*handlers)
+        for url in (f"{BASE_TRENDS_URL}/explore?geo={self.hl[-2:]}&hl={self.hl}", "https://www.google.com/?hl=en"):
+            try:
+                self._fetch(url)
+            except OSError:
+                pass  # best effort
+            if any(c.name == "NID" for c in jar):
+                break
+        self.cookies = {c.name: c.value for c in jar if c.name == "NID"}
+
+    def _backoff(self, attempt):
+        base = self.backoff_factor * 2 ** attempt if self.backoff_factor else min(30.0, 1.5 * 2 ** attempt)
+        return base / 2 + random.random() * base / 2
+
+    def _get_data(self, url, params=None, parse=_json, data=None, headers=None):
+        """Request with retries. 429, 403 and 5xx: new session, exponential backoff with jitter.
+        400 and 404 mean bad input and are raised at once."""
+        if params:
+            url = f"{url}?{urllib.parse.urlencode(params)}"
+        err, parse_fails = None, 0
+        for attempt in range(self.retries + 1):
+            if self._opener is None:
+                self._new_session()
+            try:
+                status, text = self._fetch(url, data=data, headers=headers)
+            except OSError as e:
+                err = ResponseError(f"Network error: {e}")
+            else:
+                resp = SimpleNamespace(status_code=status, text=text[:2000], url=url)
+                if status == 200:
+                    try:
+                        return parse(text)
+                    except (ValueError, KeyError, IndexError, TypeError) as e:
+                        # A 200 without data is usually deterministic (bad geo, unsupported country).
+                        err = ResponseError(f"Unexpected response from Google: {e}", resp)
+                        parse_fails += 1
+                        if parse_fails >= 3:
+                            raise err from None
+                elif status in (400, 404):
+                    raise ResponseError.from_response(resp)
+                elif status == 429:
+                    err = TooManyRequestsError.from_response(resp)
+                else:
+                    err = ResponseError.from_response(resp)
+            if attempt < self.retries:
+                wait = self._backoff(attempt)
+                log.debug("%s; new session, retry in %.1fs", err, wait)
+                self._opener = None
+                time.sleep(wait)
+        raise err
+
+    def _widget(self, url, widget):
+        return self._get_data(url, {"hl": self.hl, "tz": self.tz, "req": json.dumps(widget["request"]),
+                                    "token": widget["token"]})["default"]
+
+    def _either(self, local, remote):
+        """Run locally; on HTTP 429 use the hosted Actor if fallback="apify"."""
+        if not self._hosted:
+            try:
+                return local()
+            except TooManyRequestsError:
+                if not self.fallback:
+                    raise
+        log.warning("Google rate-limited this client (HTTP 429). Using the hosted Apify Actor %s "
+                    "(billed per result to your Apify account).", hosted.ACTOR_URL)
+        return remote()
+
+    # Explore ----------------------------------------------------------------------------------------
+
+    def build_payload(self, kw_list, cat=0, timeframe="today 5-y", geo="", gprop=""):
+        """Create the payload for interest over time, by region and related queries/topics."""
+        if gprop not in ("", "images", "news", "youtube", "froogle"):
+            raise ValueError("gprop must be empty (to indicate web), images, news, youtube, or froogle")
+        self.kw_list = [kw_list] if isinstance(kw_list, str) else list(kw_list)
+        self.geo = geo or self.geo
+        if not isinstance(self.geo, list):
+            self.geo = [self.geo]
+        self._query = {"cat": cat, "timeframe": timeframe, "gprop": gprop}
+        self.token_payload = self._payload(self.kw_list)
+        self._hosted = False
+        try:
+            self._tokens(self._get_data(self.GENERAL_URL, self.token_payload)["widgets"])
+        except TooManyRequestsError:
+            if not self.fallback:
+                raise
+            self._hosted = True  # every call on this payload goes to the hosted Actor
+
+    def _payload(self, kws):
+        q = self._query
+        times = q["timeframe"] if isinstance(q["timeframe"], list) else None
+        items = [{"keyword": kw, "time": times[i] if times else q["timeframe"], "geo": g}
+                 for i, (kw, g) in enumerate(product(kws, self.geo))]
+        return {"hl": self.hl, "tz": self.tz,
+                "req": json.dumps({"comparisonItem": items, "category": q["cat"], "property": q["gprop"]})}
+
+    def _tokens(self, widgets):
+        self.interest_over_time_widget = {}
+        self.interest_by_region_widget = {}
+        self.related_queries_widget_list = []
+        self.related_topics_widget_list = []
+        for w in widgets:
+            if w["id"] == "TIMESERIES":
+                self.interest_over_time_widget = w
+            if w["id"] == "GEO_MAP" and not self.interest_by_region_widget:
+                self.interest_by_region_widget = w
+            if "RELATED_TOPICS" in w["id"]:
+                self.related_topics_widget_list.append(w)
+            if "RELATED_QUERIES" in w["id"]:
+                self.related_queries_widget_list.append(w)
+
+    def _columns(self):
+        return [kw if len(self.geo) == 1 else (kw, g) for kw, g in product(self.kw_list, self.geo)]
+
+    def interest_over_time(self):
+        """DataFrame indexed by date: one int column per keyword (0-100) and isPartial."""
+        def local():
+            data = self._widget(self.INTEREST_OVER_TIME_URL, self.interest_over_time_widget)
+            cols = self._columns()
+            rows = [{"date": _ts(p["time"]), **{c: int(v) for c, v in zip(cols, p["value"])},
+                     "isPartial": bool(p.get("isPartial", False))} for p in data["timelineData"]]
+            return self._over_time_frame(rows)
+
+        def remote():
+            points = {}
+            for item in self._hosted_items("interest_over_time", includeInterestOverTime=True):
+                for p in item.get("timeline", []):
+                    row = points.setdefault(p["timestamp"], {"date": _ts(p["timestamp"])})
+                    row[item["term"]] = int(p["value"])
+                    row["isPartial"] = bool(p.get("isPartial", False))
+            rows = [{"date": r["date"], **{k: r.get(k, 0) for k in self.kw_list}, "isPartial": r["isPartial"]}
+                    for _, r in sorted(points.items())]
+            return self._over_time_frame(rows)
+
+        return self._either(local, remote)
+
+    def _over_time_frame(self, rows):
+        df = _frame(rows, "date")
+        if pd is not None and len(self.geo) > 1 and not df.empty:
+            df.columns = pd.MultiIndex.from_tuples([c if isinstance(c, tuple) else (c,) for c in df],
+                                                   names=["keyword", "region"])
+        return df
+
+    def _region_resolution(self, resolution):
+        # pytrends meant to apply `resolution` only worldwide or for US sub-levels (its check never matched).
+        geo = self.geo[0] if self.geo else ""
+        return resolution if (not geo or resolution != "COUNTRY") else None
+
+    def interest_by_region(self, resolution="COUNTRY", inc_low_vol=False, inc_geo_code=False):
+        """DataFrame indexed by geoName: one int column per keyword (plus geoCode if inc_geo_code)."""
+        res = self._region_resolution(resolution)
+
+        def local():
+            w = self.interest_by_region_widget
+            req = {**w["request"], "includeLowSearchVolumeGeos": inc_low_vol, **({"resolution": res} if res else {})}
+            data = self._widget(self.INTEREST_BY_REGION_URL, {"request": req, "token": w["token"]})
+            rows = []
+            for g in data["geoMapData"]:
+                row = {"geoName": g["geoName"]}
+                if inc_geo_code:
+                    row["geoCode"] = g.get("geoCode", g.get("coordinates"))
+                row.update({kw: int(v) for kw, v in zip(self.kw_list, g["value"])})
+                rows.append(row)
+            return _frame(rows, "geoName")
+
+        def remote():
+            # ponytail: the Actor scales each term on its own map; locally pytrends' shared scale is used.
+            merged = {}
+            items = self._hosted_items("interest_by_region", includeInterestByRegion=True,
+                                       regionResolution=res or "auto", includeLowVolumeRegions=inc_low_vol)
+            for item in items:
+                for g in item.get("regions", []):
+                    row = merged.setdefault(g["geoName"], {"geoName": g["geoName"],
+                                                           **({"geoCode": g.get("geoCode")} if inc_geo_code else {}),
+                                                           **{kw: 0 for kw in self.kw_list}})
+                    row[item["term"]] = int(g.get("value", 0))
+            return _frame(list(merged.values()), "geoName")
+
+        return self._either(local, remote)
+
+    def _related(self, widgets, flat):
+        by_kw = {}
+        for w in widgets:
+            try:
+                by_kw[w["request"]["restriction"]["complexKeywordsRestriction"]["keyword"][0]["value"]] = w
+            except (KeyError, IndexError):
+                by_kw[""] = w
+        prefix = "RELATED_TOPICS" if flat else "RELATED_QUERIES"
+        for kw in self.kw_list:
+            if kw not in by_kw and len(self.geo) == 1:
+                # Google now sends related topics only for single-term explores: ask for this term alone.
+                widgets = self._get_data(self.GENERAL_URL, self._payload([kw]))["widgets"]
+                w = next((x for x in widgets if x["id"] == prefix), None)
+                if w:
+                    by_kw[kw] = w
+        result = {}
+        for kw, w in by_kw.items():
+            data = self._widget(self.RELATED_QUERIES_URL, w)
+            result[kw] = {"top": _ranked(data, 0, flat), "rising": _ranked(data, 1, flat)}
+        return result
+
+    def related_queries(self):
+        """{keyword: {'top': DataFrame[query, value] or None, 'rising': ...}}"""
+        def remote():
+            out = {kw: {"top": None, "rising": None} for kw in self.kw_list}
+            for item in self._hosted_items("related_queries", includeRelatedQueries=True):
+                out[item["term"]] = {k: _frame([{"query": r["query"], "value": r["value"]} for r in item.get(k, [])])
+                                     if item.get(k) else None for k in ("top", "rising")}
+            return out
+
+        return self._either(lambda: self._related(self.related_queries_widget_list, False), remote)
+
+    def related_topics(self):
+        """{keyword: {'top': DataFrame or None, 'rising': ...}}. Google often hides topics from scripts."""
+        def remote():
+            out = {kw: {"top": None, "rising": None} for kw in self.kw_list}
+            for item in self._hosted_items("related_topics", includeRelatedTopics=True):
+                out[item["term"]] = {k: _frame([{"value": r.get("value"), "formattedValue": r.get("formattedValue"),
+                                                 "link": r.get("link"), "topic_mid": r.get("topicId"),
+                                                 "topic_title": r.get("topic"), "topic_type": r.get("topicType")}
+                                                for r in item.get(k, [])]) for k in ("top", "rising")}
+            return out
+
+        return self._either(lambda: self._related(self.related_topics_widget_list, True), remote)
+
+    def _hosted_items(self, kind, **flags):
+        if len(self.geo) != 1 or isinstance(self._query.get("timeframe"), list):
+            raise ValueError("The hosted fallback supports one geo and one timeframe per build_payload")
+        if any("," in kw for kw in self.kw_list):
+            raise ValueError("The hosted fallback does not support commas inside a keyword")
+        actor_input = {"searchTerms": [", ".join(self.kw_list)], "geo": self.geo[0],
+                       **hosted.timeframe(self._query["timeframe"]), "category": self._query["cat"],
+                       "gprop": self._query["gprop"] or "web", "language": self.hl, "timezoneOffset": self.tz,
+                       "includeInterestOverTime": False, **flags}
+        return [i for i in hosted.run(actor_input, self.apify_token) if i.get("type") == kind]
+
+    # Trending now -----------------------------------------------------------------------------------
+
+    def trending_now(self, geo="US", hours=24):
+        """Google Trends 'Trending now' for one country (hours: 4, 24, 48 or 168).
+        Rows: title, volume, increase_percentage, started, ended, active, categories, related_queries.
+        Falls back to the RSS feed (24 hours, with news) when the main endpoint changes shape."""
+        def local():
+            try:
+                return self._trending_batch(geo, hours)
+            except TooManyRequestsError:
+                raise
+            except ResponseError as e:
+                log.info("Trending now endpoint failed (%s); using the RSS feed", e)
+                return self._trending_rss(geo)
+
+        def remote():
+            items = hosted.run({"searchTerms": [], "trendingNowCountries": [geo], "trendingNowHours": str(hours),
+                                "language": self.hl}, self.apify_token)
+            return [{"title": t["title"], "volume": t.get("searchVolume"),
+                     "increase_percentage": t.get("increasePercentage"), "started": _iso(t.get("startedAt")),
+                     "ended": _iso(t.get("endedAt")), "active": t.get("active"), "categories": t.get("categories", []),
+                     "related_queries": t.get("relatedQueries", [])} for t in items if t.get("type") == "trending_now"]
+
+        return self._either(local, remote)
+
+    def _trending_batch(self, geo, hours):
+        f_req = json.dumps([[["i0OFE", json.dumps([None, None, geo, 0, self.hl, hours, 1]), None, "generic"]]])
+
+        def parse(text):
+            line = next(ln for ln in text.split("\n") if ln.startswith('[["wrb.fr"'))
+            trends = json.loads(json.loads(line)[0][2])[1]
+            if not isinstance(trends, list):
+                raise ValueError("no trends list")
+            return trends
+
+        url = f"{self.TRENDING_NOW_URL}?rpcids=i0OFE&source-path=%2Ftrending&hl={self.hl}&rt=c"
+        rows = self._get_data(url, parse=lambda t: _guard(parse, t),
+                              data=urllib.parse.urlencode({"f.req": f_req}).encode(),
+                              headers={"content-type": "application/x-www-form-urlencoded;charset=UTF-8"})
+        return [{"title": t[0], "volume": t[6], "increase_percentage": t[8],
+                 "started": _ts(t[3][0]) if t[3] else None, "ended": _ts(t[4][0]) if t[4] else None,
+                 "active": not t[4], "categories": [TRENDING_CATEGORIES.get(c, str(c)) for c in (t[10] or [])],
+                 "related_queries": t[9] if isinstance(t[9], list) else []} for t in rows]
+
+    def _trending_rss(self, geo):
+        def parse(text):
+            rows = []
+            for it in ET.fromstring(text).iter("item"):
+                traffic = it.findtext("{*}approx_traffic") or ""
+                pub = it.findtext("pubDate")
+                rows.append({"title": it.findtext("title"), "volume": int("".join(filter(str.isdigit, traffic)) or 0) or None,
+                             "increase_percentage": None,
+                             "started": parsedate_to_datetime(pub).astimezone(timezone.utc).replace(tzinfo=None) if pub else None,
+                             "ended": None, "active": None, "categories": [], "related_queries": [],
+                             "news": [{"title": n.findtext("{*}news_item_title"), "url": n.findtext("{*}news_item_url"),
+                                       "source": n.findtext("{*}news_item_source")} for n in it.iter("{*}news_item")]})
+            return rows
+
+        return self._get_data(self.TRENDING_RSS_URL, {"geo": geo}, parse=lambda t: _guard(parse, t))
+
+    def _trending(self, pn, hours=24):
+        geo = PN_GEO.get(pn, pn).upper()
+        return [t["title"] for t in self.trending_now(geo, hours)]
+
+    def trending_searches(self, pn="united_states"):
+        """DataFrame with one column (0) of trending titles. pn: pytrends country name or ISO code."""
+        titles = self._trending(pn)
+        return pd.DataFrame(titles) if pd is not None else titles
+
+    def today_searches(self, pn="US"):
+        """Series of today's trending titles (past 24 hours)."""
+        titles = self._trending(pn)
+        return pd.Series(titles) if pd is not None else titles
+
+    def realtime_trending_searches(self, pn="US", cat="all", count=300):
+        """DataFrame[entityNames, title]: trends started in the past 4 hours. `cat` is not supported."""
+        if cat != "all":
+            warnings.warn("realtime_trending_searches(cat=...) is ignored: Trending now has no category filter")
+        rows = self.trending_now(PN_GEO.get(pn, pn).upper(), 4)[:count]
+        return _frame([{"entityNames": t["related_queries"], "title": t["title"]} for t in rows])
+
+    # Other ------------------------------------------------------------------------------------------
+
+    def suggestions(self, keyword):
+        """Google's keyword suggestions: list of {'mid', 'title', 'type'}."""
+        return self._get_data(self.SUGGESTIONS_URL + urllib.parse.quote(keyword), {"hl": self.hl})["default"]["topics"]
+
+    def categories(self):
+        """Category tree: {'name', 'id', 'children': [...]}"""
+        return self._get_data(self.CATEGORIES_URL, {"hl": self.hl})
+
+    def multirange_interest_over_time(self):
+        raise NotImplementedError("multirange_interest_over_time is not ported yet. Call build_payload once per range.")
+
+    def top_charts(self, *args, **kwargs):
+        raise NotImplementedError("Google removed the Top Charts endpoint. Use trending_now() for current trends.")
+
+    def get_historical_interest(self, *args, **kwargs):
+        raise NotImplementedError("Removed in pytrends for incorrectness (pytrends PR #542).")
+
+
+def _guard(parse, text):
+    """Turn StopIteration from a missing line into the ValueError _get_data retries on."""
+    try:
+        return parse(text)
+    except StopIteration:
+        raise ValueError("payload not found") from None
+    except ET.ParseError as e:
+        raise ValueError(f"not RSS: {e}") from None

pytrends_next-0.1.0/src/pytrends_next.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: pytrends-next
+Version: 0.1.0
+Summary: Maintained drop-in replacement for pytrends (archived): Google Trends with the TrendReq API, standard library only, optional hosted fallback on HTTP 429.
+Author-email: Ctrio Lab <myhouse9600@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ctriolab/google-trends-python
+Project-URL: Issues, https://github.com/ctriolab/google-trends-python/issues
+Project-URL: Hosted fallback, https://apify.com/ctriolab/google-trends-scraper
+Keywords: google trends,pytrends,trends,seo,keyword research,429
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == "pandas"
+Dynamic: license-file
+
+# pytrends-next
+
+A maintained drop-in replacement for [pytrends](https://github.com/GeneralMills/pytrends), which was archived
+(read-only) in April 2025. Same `TrendReq` API, same DataFrames, talks to Google Trends directly.
+
+- Standard library only. pandas is optional: with pandas you get the same DataFrames as pytrends,
+  without it you get lists of dicts.
+- Python 3.9+.
+- Built-in handling of HTTP 429: new cookie session and exponential backoff with jitter.
+- Optional, paid, off by default: route a call through a hosted scraper when Google keeps answering 429.
+
+```bash
+pip install "pytrends-next[pandas]"     # or: pip install pytrends-next   (no pandas)
+```
+
+```python
+from pytrends_next.request import TrendReq   # was: from pytrends.request import TrendReq
+
+pytrends = TrendReq(hl="en-US", tz=360)
+pytrends.build_payload(["coffee", "tea"], timeframe="today 3-m", geo="US")
+print(pytrends.interest_over_time().head(3))
+#             coffee  tea  isPartial
+# date
+# 2026-07-23      75   35      False
+# 2026-07-24      81   38      False
+# 2026-07-25      94   40      False
+```
+
+For most code the migration is one search and replace: `pytrends.` to `pytrends_next.` in imports.
+`pytrends_next.exceptions` has the same `ResponseError` and `TooManyRequestsError`.
+
+## Moving from pytrends
+
+| pytrends 4.9.2 | pytrends-next | Notes |
+|---|---|---|
+| `TrendReq(hl, tz, geo, timeout, proxies, retries, backoff_factor, requests_args)` | same | `timeout` tuple: the larger value is used (urllib has one timeout). `requests_args`: `headers`, `proxies` and `verify` are used, other keys are ignored with a warning. `retries` defaults to 3 (pytrends: 0). |
+| `build_payload(kw_list, cat, timeframe, geo, gprop)` | same | Lists of geos and timeframes work as in pytrends. |
+| `interest_over_time()` | same | Index `date`, one int column per keyword, `isPartial`. MultiIndex columns for several geos. |
+| `interest_by_region(resolution, inc_low_vol, inc_geo_code)` | same | pytrends' check meant to apply `resolution` worldwide and for sub-levels never matched; here it does. |
+| `related_queries()` | same | `{kw: {"top": DataFrame[query, value] or None, "rising": ...}}` |
+| `related_topics()` | same | Google now returns topics only for single-term requests, so each term is asked alone. Often empty, see Limits. |
+| `trending_searches(pn="united_states")` | same | The old endpoint is gone. Now served from Google's "Trending now" list. `pn` takes the pytrends country name or an ISO code (`"US"`). |
+| `today_searches(pn="US")` | same | Series of titles, past 24 hours. |
+| `realtime_trending_searches(pn, cat, count)` | same | Trends started in the past 4 hours, columns `entityNames`, `title`. `cat` is ignored. |
+| `suggestions(keyword)` | same | |
+| `categories()` | same | |
+| `top_charts()` | raises `NotImplementedError` | Google removed the endpoint. |
+| `multirange_interest_over_time()` | raises `NotImplementedError` | Not ported yet. |
+| (none) | `trending_now(geo="US", hours=24)` | New. Rows with `title`, `volume`, `increase_percentage`, `started`, `ended`, `active`, `categories`, `related_queries`. `hours`: 4, 24, 48 or 168. Falls back to the Trending RSS feed if the main endpoint changes. |
+
+## HTTP 429 (TooManyRequestsError)
+
+Google Trends has no public API. It rate-limits by IP and by session, and a laptop or a single
+server often gets HTTP 429 after a few dozen requests. pytrends raised `TooManyRequestsError` at once.
+
+pytrends-next does what our hosted scraper does on every request:
+
+1. Visits trends.google.com first to get the `NID` cookie a browser visitor has (cookieless clients are limited sooner).
+2. On 429, 403 or 5xx: drops the session, takes the next proxy from `proxies=[...]` if you gave any,
+   waits about 0.75 s, 1.5 s, 3 s ... (capped at 30 s, with jitter) and tries again, `retries` times.
+3. 400 and 404 are not retried (bad geo, category or timeframe).
+
+If you still get `TooManyRequestsError`: send fewer requests (batch up to 5 terms per `build_payload`),
+wait a few minutes, use your own proxies, or use the hosted fallback below.
+
+## Hosted fallback (optional, paid)
+
+```python
+pytrends = TrendReq(fallback="apify", apify_token="apify_api_...")   # or set APIFY_TOKEN
+```
+
+When Google still answers 429 after the local retries, the same call is sent to the
+[Google Trends Scraper Actor on Apify](https://apify.com/ctriolab/google-trends-scraper?utm_source=github&utm_medium=readme&utm_campaign=pytrends-next),
+which rotates IPs on Apify's proxy network. The result comes back in the same shape.
+
+- **It costs money.** The Actor is billed per result to your own Apify account (about $1.50 per 1,000
+  results; one result is one term's timeline, one term's region list, one term's related list or one trending topic).
+  Apify's free plan includes a small monthly credit.
+- It is never on by default. Setting `APIFY_TOKEN` alone does nothing; you must pass `fallback="apify"`.
+- A warning is logged (logger `pytrends_next`) every time a call goes to the Actor.
+- If `build_payload` itself gets 429, every method on that payload goes to the Actor.
+- Supported: `interest_over_time`, `interest_by_region`, `related_queries`, `related_topics`, `trending_now`
+  and the pytrends trending methods. Not supported: several geos or timeframes in one payload,
+  commas inside a keyword, `suggestions`, `categories`.
+- Difference: in hosted mode each term's region map is scaled on its own (locally, the terms share one scale).
+- Timeframes: the named ranges (`now 1-H` to `today 5-y`, `all`) and `YYYY-MM-DD YYYY-MM-DD`. Others are rejected before a run starts.
+
+Disclosure: Ctrio Lab maintains this library and also builds and sells that Actor. The library is MIT
+licensed and fully works without it.
+
+## Limits
+
+- Values are relative (0 to 100) within one payload, as on trends.google.com. Separate calls are not on the same scale.
+- Related topics are usually empty: Google hides them from clients it classifies as automated. Empty lists come back as `None`, like pytrends.
+- Very small search volumes come back as all zeros (Google's own behaviour).
+- This is an unofficial client for undocumented endpoints. Google can change them at any time.
+
+## Legacy single-file client
+
+`gtrends.py` (the earlier version of this repo) is still here and unchanged. It calls the hosted Actor for
+every request. New code should use `pytrends_next.request.TrendReq`: `gtrends.interest_over_time_df(terms, ...)`
+becomes `build_payload(terms, ...)` plus `interest_over_time()`.
+
+## Development
+
+```bash
+python -m unittest discover -s tests     # no network, recorded responses in tests/fixtures
+python tests/live_smoke.py               # about 12 live requests to Google
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pytrends_next-0.1.0/src/pytrends_next.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/pytrends_next/__init__.py
+src/pytrends_next/exceptions.py
+src/pytrends_next/hosted.py
+src/pytrends_next/request.py
+src/pytrends_next.egg-info/PKG-INFO
+src/pytrends_next.egg-info/SOURCES.txt
+src/pytrends_next.egg-info/dependency_links.txt
+src/pytrends_next.egg-info/requires.txt
+src/pytrends_next.egg-info/top_level.txt

pytrends_next-0.1.0/src/pytrends_next.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pytrends_next-0.1.0/src/pytrends_next.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[pandas]
+pandas>=1.3

pytrends_next-0.1.0/src/pytrends_next.egg-info/top_level.txt

@@ -0,0 +1 @@
+pytrends_next