Metadata-Version: 2.4
Name: trendsapi
Version: 1.0.0
Summary: Official Python client for the Trends API. Normalized 0-100 trend scores across Google, TikTok, Amazon, Reddit, YouTube, Steam, npm and 30+ sources. Sync + async, typed responses, free tier.
Project-URL: Homepage, https://trendsapi.ai
Project-URL: Documentation, https://trendsapi.ai/#quickstart
Project-URL: Repository, https://github.com/trendsapi/trendsapi-py
Project-URL: Bug Tracker, https://github.com/trendsapi/trendsapi-py/issues
Project-URL: Get API key, https://trendsapi.ai/#get-key
Author-email: Trends API <hello@trendsapi.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: alternative-data,amazon-trends,google-trends,keyword-research,market-research,mcp,pytrends,pytrends-alternative,reddit-trends,seo,tiktok-trends,trends,trends-api,youtube-trends
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

﻿# Trends API - official Python client

[![PyPI](https://img.shields.io/pypi/v/trendsapi.svg)](https://pypi.org/project/trendsapi/)
[![Python](https://img.shields.io/pypi/pyversions/trendsapi.svg)](https://pypi.org/project/trendsapi/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![API v1](https://img.shields.io/badge/API-v1-blue.svg)](https://trendsapi.ai)
[![Free tier](https://img.shields.io/badge/free%20tier-100%20req%2Fmo-orange.svg)](https://trendsapi.ai/#pricing)

> **One score. Every platform.** Official Python client for the [Trends API](https://trendsapi.ai) - Google, TikTok, Amazon, Reddit, YouTube, Steam, npm and 30+ sources normalized to a single 0-100 trend score.

**[Get a free API key →](https://trendsapi.ai/#get-key)** · **[Quickstart →](https://trendsapi.ai/#quickstart)** · **[llms.txt →](https://trendsapi.ai/llms.txt)**

---

## Why Trends API (not scrapers, not a SERP swiss-army knife)

| # | Selling point | What that means for you |
| -: | --- | --- |
| 1 | **Managed, not scraped** | Stable JSON. No browser automation, no proxy pool, no Google/TikTok anti-bot 429 babysitting. |
| 2 | **30+ sources, one key, one schema** | 15 keyword sources + 21 live feeds. Swap `source` / `type` - response shape stays the same. |
| 3 | **Normalized 0-100 across platforms** | Compare TikTok vs Amazon vs Google on the same scale. No unit gymnastics. |
| 4 | **History + growth + live top trends** | Three modes: time series, period growth (`3M` / `12M` / `5Y`), and “what’s hot now” feeds. |
| 5 | **Built for agents** | Hosted MCP + [`llms.txt`](https://trendsapi.ai/llms.txt). Same key as the REST API. |

Also: **failed requests do not burn quota** - only successful `200`s count. Plan limits are predictable; you are not fighting upstream rate limits to get a single series.

> Replacing archived **pytrends**? Same job (Google interest over time), without the breakage - and you also get TikTok, Amazon, Reddit, YouTube, live feeds, and growth windows.

---

## Install

```bash
pip install trendsapi
```

Python 3.9+. Only dependency: `httpx`.

## Quickstart

Cross-platform compare in a few lines:

```python
from trendsapi import TrendsAPI

client = TrendsAPI(api_key="YOUR_API_KEY")  # or export TRENDSAPI_KEY=...

keyword = "creatine gummies"

# 1) Growth on three platforms - same keyword, comparable scores
for source in ("google search", "tiktok", "amazon"):
    g = client.get_growth(source=source, keyword=keyword, percent_growth=["12M"])
    r = g.results[0]
    print(source, r.growth, r.direction)

# 2) ~5 years of weekly history
series = client.get_time_series(source="google search", keyword=keyword)
print("latest", series[-1].date, series[-1].value)

# 3) What’s trending right now (no keyword)
hot = client.get_top_trends(type="TikTok Trending Hashtags", limit=5)
print(hot.data)
```

## Async (fan out sources)

```python
import asyncio
from trendsapi import AsyncTrendsAPI

async def main():
    client = AsyncTrendsAPI()  # reads TRENDSAPI_KEY
    google, tiktok, amazon = await asyncio.gather(
        client.get_time_series(source="google search", keyword="air fryer"),
        client.get_time_series(source="tiktok", keyword="air fryer"),
        client.get_time_series(source="amazon", keyword="air fryer"),
    )
    print(len(google), len(tiktok), len(amazon))

asyncio.run(main())
```

## Auth & quota

1. Free key in ~60 seconds: [trendsapi.ai/#get-key](https://trendsapi.ai/#get-key) (100 requests/month).
2. Pass `TrendsAPI(api_key=...)` **or** set `TRENDSAPI_KEY`.
3. **Only successful `200` responses count.** 4xx/5xx are free.
4. Plan tiers scale when you need more volume - see [pricing](https://trendsapi.ai/#pricing).

This is the opposite of scraper life: you don’t burn hours on IP bans; you burn a clear monthly lookup budget.

## Three modes

| Method | Use when you need | Notes |
| --- | --- | --- |
| `get_time_series` | History / charts | Default ~5y weekly; `data_mode="daily"` for recent daily |
| `get_growth` | Momentum | Presets like `3M`, `12M`, `5Y`, `YTD`; multi-period in one call |
| `get_top_trends` | Live leaderboards | No keyword. TikTok hashtags, Google Trends, Amazon best sellers, … |

Full source and feed lists: [trendsapi.ai/llms.txt](https://trendsapi.ai/llms.txt)

## Keyword sources

`google search` · `google images` · `google news` · `google shopping` · `youtube` · `tiktok` · `reddit` · `amazon` · `wikipedia` · `news volume` · `news sentiment` · `app downloads` · `app rankings` · `npm` · `steam`

```python
from trendsapi import KEYWORD_SOURCES, LIVE_FEEDS
```

## MCP (Claude, Cursor, VS Code, ChatGPT)

```json
{
  "mcpServers": {
    "trendsapi": {
      "url": "https://api.trendsapi.ai/mcp",
      "transport": "http",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Then ask: *“Compare 12-month growth of creatine gummies on Google, TikTok, and Amazon.”*

## Errors

```python
from trendsapi import TrendsAPI, TrendsAPIError

try:
    TrendsAPI(api_key="bad").get_growth(source="google search", keyword="x")
except TrendsAPIError as e:
    print(e.status, e.code, e.message)
```

If a growth preset is longer than available history for that keyword (common on new TikTok tags), the API may still return HTTP 200 with a per-row `status="error"`. Those rows parse with `growth=None` and `error` / `message` set.

## Links

- Product: [https://trendsapi.ai](https://trendsapi.ai)
- Quickstart: [https://trendsapi.ai/#quickstart](https://trendsapi.ai/#quickstart)
- API for agents: [https://trendsapi.ai/llms.txt](https://trendsapi.ai/llms.txt)
- All sources: [https://trendsapi.ai/trends](https://trendsapi.ai/trends)
- GitHub: [https://github.com/trendsapi/trendsapi-py](https://github.com/trendsapi/trendsapi-py)

## License

MIT. Data access follows your Trends API plan limits.
