trendsapi (Python)

Official Python client for Trends API. Three methods. Decoded payloads. You never parse the HTTP body string.

HTTP contract and field tables: trendsapi-ai/trendsapi.

Authentication

pip install trendsapi
export TRENDSAPI_KEY=your_key

Key: trendsapi.ai/#get-key. Python 3.9+.

from trendsapi import TrendsAPI

client = TrendsAPI()                    # TRENDSAPI_KEY
# client = TrendsAPI(api_key="YOUR_KEY")

Methods

weekly = client.get_time_series(source="google search", keyword="solar battery")
growth = client.get_growth(source="amazon", keyword="solar battery", percent_growth=["3M", "12M"])
now = client.get_top_trends(type="Google Trends", limit=10)

source is lowercase (google search). type is exact (Google Trends). Mixing them is a 400.

get_time_series

points = client.get_time_series(source="google search", keyword="bitcoin")
print(points[-1].date, points[-1].value)

Python returns dataclasses. Use .date / .value, not ["date"].

Each point:

get_growth

g = client.get_growth(source="google search", keyword="nike", percent_growth=["12M", "3M", "YTD"])
print(g.results[0].growth, g.results[0].direction)

percent_growth default: ["12M"]. Presets: 7D 14D 30D 1M 2M 3M 6M 9M 12M/1Y 18M 24M/2Y 36M/3Y 48M 60M/5Y MTD QTD YTD. Custom: {"name": "Launch", "recent": "2024-06-01", "baseline": "2024-01-01"}.

Several windows still count as one request.

get_top_trends

chart = client.get_top_trends(type="TikTok Trending Hashtags", limit=10)
# chart.data == [[1, "matcha"], ...]

Optional offset=, category= (Amazon Best Sellers by Category, Top Websites only).

Keyword sources

Pass as source=. Full notes: hub README.

Live feeds

Pass as type= on get_top_trends. Exact strings: Google Trends, Google News Top News, TikTok Trending Hashtags, TikTok Trending Searches, TikTok Shop Hot Products, YouTube Trending, X (Twitter) Trending, Reddit Hot Posts, Reddit World News, Wikipedia Trending, Amazon Best Sellers Top Rated, Amazon Best Sellers by Category, App Store Top Free, App Store Top Paid, Google Play, Top Websites, Spotify Top Podcasts, Steam Most Played, GitHub Trending Repos, IMDb MOVIEmeter, Open Library Trending Books.

Async

import asyncio
from trendsapi import AsyncTrendsAPI

async def compare(term: str):
    c = AsyncTrendsAPI()
    return await asyncio.gather(
        c.get_time_series(source="google search", keyword=term),
        c.get_time_series(source="google shopping", keyword=term),
        c.get_time_series(source="wikipedia", keyword=term),
    )

asyncio.run(compare("solar battery"))

Each 200 is one billed request.

Pandas

from dataclasses import asdict
import pandas as pd
from trendsapi import TrendsAPI

df = pd.DataFrame(asdict(p) for p in TrendsAPI().get_time_series(source="google search", keyword="solar battery"))
df["date"] = pd.to_datetime(df["date"])
print(df.set_index("date")["value"].resample("ME").mean().tail())

Errors

Raw requests (second parse required): see hub, Raw HTTP.

License

MIT. See LICENSE.