Metadata-Version: 2.4
Name: youtube-trends-api
Version: 1.0.0
Summary: YouTube has no public trends API. This package gives you YouTube search interest data over time via a single call. Weekly series, growth percentages, and live trending searches. No scraping. Powered by trendsmcp.ai
Project-URL: Homepage, https://trendsmcp.ai
Project-URL: Documentation, https://trendsmcp.ai/docs
Project-URL: Repository, https://github.com/trendsmcp/youtube-trends-api
Project-URL: Get API Key, https://trendsmcp.ai
Author-email: Trends MCP <hello@trendsmcp.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: analytics,growth-rate,keyword-research,search-interest,seo,trend-data,trendsmcp,youtube,youtube-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.8
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
Requires-Python: >=3.8
Requires-Dist: trendsmcp>=1.0.0
Description-Content-Type: text/markdown

# youtube-trends-api

[![PyPI version](https://img.shields.io/pypi/v/youtube-trends-api.svg)](https://pypi.org/project/youtube-trends-api/)
[![Python versions](https://img.shields.io/pypi/pyversions/youtube-trends-api.svg)](https://pypi.org/project/youtube-trends-api/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/trendsmcp/youtube-trends-api/blob/main/LICENSE)

The number one Python package for YouTube trend data. YouTube has no public trends API. This package gives you YouTube search interest over time via a single REST call. Weekly series, growth percentages, and live trending searches. No scraping, no YouTube API key, no OAuth.

Works as a **Python API client** in any script, notebook, or pipeline. Also works as an **MCP tool** — plug it directly into Claude, Cursor, VS Code Copilot, or any MCP-compatible AI host.

Powered by [trendsmcp.ai](https://trendsmcp.ai).

**[Get a free API key](https://trendsmcp.ai)** — 100 requests/month, no credit card.

**[Full API docs](https://trendsmcp.ai/docs)**

---

## Requirements

Python 3.8 or later. Depends on `trendsmcp`.

---

## Install

```bash
pip install youtube-trends-api
```

---

## Connect

Store your API key in an environment variable:

```bash
export TRENDSMCP_API_KEY="your-api-key"
```

```python
import os
from youtube_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key=os.environ["TRENDSMCP_API_KEY"])
```

`SOURCE` is pre-set to `"youtube"`. Pass it directly to any method.

---

## get_trends

Returns a weekly time series for a YouTube keyword. Default is 5 years of weekly data.

```python
import os
from youtube_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key=os.environ["TRENDSMCP_API_KEY"])

series = client.get_trends(source=SOURCE, keyword="asmr")

print(series[0])
# TrendsDataPoint(date='2021-01-03', value=54, keyword='asmr', source='youtube')

print(series[-1])
# TrendsDataPoint(date='2026-03-23', value=72, keyword='asmr', source='youtube')

# Daily granularity (last 30 days)
series = client.get_trends(source=SOURCE, keyword="asmr", data_mode="daily")
```

**Parameters**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `source` | str | Yes | Use `SOURCE` or pass any supported source string |
| `keyword` | str | Yes | Keyword to query |
| `data_mode` | str | No | `"weekly"` (default) or `"daily"` |

**Response fields**

| Field | Type | Description |
|---|---|---|
| `date` | str | ISO date string |
| `value` | float | Normalized value 0 to 100 |
| `volume` | float or None | Absolute volume estimate where available |
| `keyword` | str | The keyword queried |
| `source` | str | The data source |

---

## get_growth

Returns period-over-period growth percentages for a keyword.

```python
growth = client.get_growth(
    source=SOURCE,
    keyword="asmr",
    percent_growth=["3M", "12M", "YTD"],
)

for r in growth.results:
    print(f"{r.period}: {r.growth:+.1f}% ({r.direction})")
# 3M: +8.2% (increase)
# 12M: +14.5% (increase)
# YTD: +5.1% (increase)
```

**Growth presets:** `7D` `14D` `30D` `1M` `2M` `3M` `6M` `9M` `12M` `1Y` `18M` `24M` `2Y` `36M` `3Y` `48M` `60M` `5Y` `MTD` `QTD` `YTD`

Custom date ranges:

```python
from youtube_trends_api import TrendsMcpClient, SOURCE, CustomGrowthPeriod
import os

client = TrendsMcpClient(api_key=os.environ["TRENDSMCP_API_KEY"])

growth = client.get_growth(
    source=SOURCE,
    keyword="asmr",
    percent_growth=[
        CustomGrowthPeriod(name="last quarter", recent="2026-03-31", baseline="2026-01-01")
    ],
)
```

---

## get_top_trends

Returns today's live trending YouTube searches.

```python
trending = client.get_top_trends(type="YouTube", limit=10)
print(trending.data)
# [[1, 'topic one'], [2, 'topic two'], ...]
```

---

## Async

All three methods are available on `AsyncTrendsMcpClient`:

```python
import asyncio
import os
from youtube_trends_api import AsyncTrendsMcpClient, SOURCE

async def main():
    client = AsyncTrendsMcpClient(api_key=os.environ["TRENDSMCP_API_KEY"])
    series = await client.get_trends(source=SOURCE, keyword="asmr")
    print(series[-1])

asyncio.run(main())
```

---

## Error handling

```python
from youtube_trends_api import TrendsMcpClient, TrendsMcpError, SOURCE
import os

client = TrendsMcpClient(api_key=os.environ["TRENDSMCP_API_KEY"])

try:
    series = client.get_trends(source=SOURCE, keyword="asmr")
except TrendsMcpError as e:
    print(e.status)   # HTTP status code, e.g. 429
    print(e.code)     # e.g. "rate_limited"
    print(e.message)
```

---

## Supported sources

This package defaults to `"youtube"` but the client supports all sources.

| source | What it measures |
|---|---|
| `"google search"` | Google Search volume |
| `"google images"` | Google Images search volume |
| `"google news"` | Google News search volume |
| `"google shopping"` | Google Shopping purchase intent |
| `"youtube"` | YouTube search volume |
| `"tiktok"` | TikTok hashtag volume |
| `"reddit"` | Reddit mention and discussion volume |
| `"amazon"` | Amazon product search volume |
| `"wikipedia"` | Wikipedia page views |
| `"news volume"` | News article mention count |
| `"news sentiment"` | News sentiment score (positive / negative) |
| `"npm"` | npm package weekly downloads |
| `"steam"` | Steam concurrent player count |

See [trendsmcp.ai/docs](https://trendsmcp.ai/docs) for the full and always up-to-date source list.

---

## Related packages

- [trendsmcp](https://pypi.org/project/trendsmcp/) - core package, all sources
- [youtube-trends-mcp](https://pypi.org/project/youtube-trends-mcp/) - MCP variant of this package
- [reddit-trends-api](https://pypi.org/project/reddit-trends-api/) / [reddit-trends-mcp](https://pypi.org/project/reddit-trends-mcp/)
- [google-search-trends-api](https://pypi.org/project/google-search-trends-api/) / [google-search-trends-mcp](https://pypi.org/project/google-search-trends-mcp/)
- [amazon-trends-api](https://pypi.org/project/amazon-trends-api/) / [amazon-trends-mcp](https://pypi.org/project/amazon-trends-mcp/)
- [tiktok-trends-api](https://pypi.org/project/tiktok-trends-api/) / [tiktok-trends-mcp](https://pypi.org/project/tiktok-trends-mcp/)
- [wikipedia-trends-api](https://pypi.org/project/wikipedia-trends-api/) / [wikipedia-trends-mcp](https://pypi.org/project/wikipedia-trends-mcp/)
- [npm-trends-api](https://pypi.org/project/npm-trends-api/) / [npm-trends-mcp](https://pypi.org/project/npm-trends-mcp/)
- [steam-trends-api](https://pypi.org/project/steam-trends-api/) / [steam-trends-mcp](https://pypi.org/project/steam-trends-mcp/)
- [app-store-trends-api](https://pypi.org/project/app-store-trends-api/) / [app-store-trends-mcp](https://pypi.org/project/app-store-trends-mcp/)
- [news-volume-api](https://pypi.org/project/news-volume-api/) / [news-volume-mcp](https://pypi.org/project/news-volume-mcp/)
- [news-sentiment-api](https://pypi.org/project/news-sentiment-api/) / [news-sentiment-mcp](https://pypi.org/project/news-sentiment-mcp/)

---

## License

MIT
