Skip to main content

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.

License: MIT PyPI Python

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

Method REST mode Required arguments Returns
get_time_series get_time_series source, keyword list[dict] of weekly points
get_growth get_growth source, keyword growth dict
get_top_trends get_top_trends type feed dict
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")

Each point:

Field Always Meaning
date yes YYYY-MM-DD
value yes 0-100 index for this series
keyword yes Echo
volume no Absolute volume when available
source or datatype no Pipeline label

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"}.

Field Meaning
search_term Keyword
data_source Source
results One object per window (period, growth, direction, dates, values)
metadata Counts / success flag

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"], ...]
Field Meaning
as_of_ts Snapshot time
type Feed name
limit, offset, count Pagination
data [rank, label] rows

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

Keyword sources

Pass as source=. Full notes: hub README.

source keyword
google search, google images, google news, google shopping Any phrase
youtube Any phrase
tiktok Hashtag or topic
reddit Subreddit, no r/
amazon Product phrase
wikipedia Article title
news volume, news sentiment Any phrase
app downloads, app rankings Android bundle ID (com.openai.chatgpt)
npm Exact package name
steam Game display name

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

import pandas as pd
from trendsapi import TrendsAPI

df = pd.DataFrame(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

Code Client
200 Returns parsed payload
400 Raises. Fix source / type
401 Raises. Check TRENDSAPI_KEY
404 Raises. No series. Do not retry
429 Raises. Quota
5xx Retries, then raises

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

License

MIT. See LICENSE.

Metadata

Release files for trendsapi 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trendsapi 1.0.1
File Size Uploaded Provenance Actions
trendsapi-1.0.1.tar.gz 7.9 kB Without provenance Details for trendsapi-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for trendsapi 1.0.1
File Interpreter ABI Platform Actions
trendsapi-1.0.1-py3-none-any.whl Python 3 none any Details for trendsapi-1.0.1-py3-none-any.whl

Total release size: 17.3 kB

Release files / trendsapi-1.0.1.tar.gz

Download URL trendsapi-1.0.1.tar.gz
Size 7.9 kB
Tags Source
SHA-256 checksum
How to use checksums
131f163212da57a4d08da403ed25163ea4076ed71e52e530806b9a716f79d5ce
BLAKE2b-256 checksum
How to use checksums
9251f18ab630bd4d48be970c19ee2ae2dda9e8b158ca0c1ff06fa785867d8b4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Release files / trendsapi-1.0.1-py3-none-any.whl

Download URL trendsapi-1.0.1-py3-none-any.whl
Size 9.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
86a70ea77052a409b5916d5af058156d66831df407d18d221fd0e6fa850519a8
BLAKE2b-256 checksum
How to use checksums
85b1f04f919cee85aed0c30484519b3348ded0197f8156bccb07b60c9c78a298
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Security for trendsapi 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page