# Trends API reference

> Markdown mirror of [https://trendsapi.ai/docs](https://trendsapi.ai/docs).
> Also: [llms.txt](https://trendsapi.ai/llms.txt)

Base URL: `POST https://api.trendsapi.ai/api`
Auth: `Authorization: Bearer <api_key>`
Content-Type: `application/json`

Get a key: https://trendsapi.ai/#get-key (100 free requests/month).

If the payload is `{"statusCode": int, "body": string}`, parse `body` once more.

## First request

```bash
curl -X POST https://api.trendsapi.ai/api \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"get_time_series","source":"google search","keyword":"bitcoin"}'
```

```python
import json, requests

res = requests.post(
    "https://api.trendsapi.ai/api",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"mode": "get_time_series", "source": "google search", "keyword": "bitcoin"},
)
payload = res.json()
data = json.loads(payload["body"]) if isinstance(payload.get("body"), str) else payload
```

## Modes

| mode | Returns | Required |
| --- | --- | --- |
| `get_time_series` | ~5 years of weekly 0-100 points | `source`, `keyword` |
| `get_growth` | % change over one or more periods | `source`, `keyword` (`percent_growth` optional, default `["12M"]`) |
| `get_top_trends` | Live ranked feed | `type` optional on REST (omit for all feeds) |

`get_trends` is an alias of `get_time_series`.

### Time series

```json
{"mode":"get_time_series","source":"google search","keyword":"bitcoin"}
```

Response: array of `{date, value, volume, keyword, source}`.

### Growth

Presets: 7D, 14D, 30D, 1M, 2M, 3M, 6M, 9M, 12M, 1Y, 18M, 24M, 2Y, 36M, 3Y, 48M, 60M, 5Y, MTD, QTD, YTD.

Custom range object: `{"name":"Last Year","recent":"2025-12-31","baseline":"2024-12-31"}`.

```json
{"mode":"get_growth","source":"google search","keyword":"bitcoin","percent_growth":["12M"]}
```

### Top trends

`type` must match a feed label exactly. `limit` default 25, max 200. `offset` default 0.

```json
{"mode":"get_top_trends","type":"Google Trends","limit":10}
```

Response: `{as_of_ts, type, limit, count, data:[[rank, label], ...]}`.

## Keyword sources

| source | Description | Keyword format |
| --- | --- | --- |
| `google search` | Google search volume | Any keyword or phrase |
| `google images` | Google image search volume | Any keyword or phrase |
| `google news` | Google News search volume | Any keyword or phrase |
| `google shopping` | Google Shopping search volume | Any keyword or phrase |
| `youtube` | YouTube search volume | Any keyword or phrase |
| `tiktok` | TikTok hashtag volume | Hashtag or topic |
| `reddit` | Subreddit subscribers | Subreddit name only, no r/ prefix |
| `amazon` | Amazon product search volume | Product name or category |
| `wikipedia` | Wikipedia page views | Article title or topic |
| `news volume` | News article mention volume | Any keyword or phrase |
| `news sentiment` | News sentiment score (positive / negative) | Any keyword or phrase |
| `app downloads` | Android app downloads | Android bundle ID e.g. com.openai.chatgpt |
| `app rankings` | Android app store ranking charts | Android bundle ID e.g. com.himshers.hims |
| `npm` | npm package weekly downloads | Exact package name, case-sensitive e.g. react, @babel/core |
| `steam` | Steam concurrent players (monthly) | Game display name e.g. Elden Ring (first Steam search result) |

## Live feeds

| type | Feed |
| --- | --- |
| `Google Trends` | Top trending search terms on Google right now |
| `Google Trends by Category` | Google trending searches split by topic board |
| `Google News Top News` | Top news stories from Google News |
| `TikTok Trending Hashtags` | Top trending hashtags on TikTok |
| `TikTok Trending Searches` | Top trending search terms on TikTok |
| `YouTube Trending` | Top trending videos on YouTube |
| `X (Twitter) Trending` | Top trending topics on X |
| `Reddit Hot Posts` | Hottest posts on Reddit's front page |
| `Reddit World News` | Top posts in r/worldnews |
| `Wikipedia Trending` | Most-viewed Wikipedia articles today |
| `Amazon Best Sellers Top Rated` | Amazon top-rated best sellers across all categories |
| `Amazon Best Sellers by Category` | Amazon best sellers filtered by product category |
| `App Store Top Free` | Top free apps on the iOS App Store |
| `App Store Top Paid` | Top paid apps on the iOS App Store |
| `Google Play` | Top apps on Google Play |
| `Top Websites` | Most-visited websites globally by traffic rank |
| `Spotify Top Podcasts` | Top podcasts on Spotify |
| `Steam Most Played` | Top games by concurrent live players |
| `Substack` | Top Substack newsletters overall |
| `Substack by Category` | Top Substack newsletters by category |
| `GitHub` | Daily trending repositories across all languages |
| `IMDb MOVIEmeter` | Top 100 most-popular movies by user activity |
| `Open Library Trending Books` | Daily trending books from Open Library |

## Usage

One successful POST is one quota unit. 4xx/5xx are free. Quotas reset on the first of the month.

## Errors

| Status | Code | Fix |
| --- | --- | --- |
| 400 | `missing_parameter` | Add the field named in `message` |
| 400 | `invalid_source` | Use a source from the table above |
| 401 | | Send `Authorization: Bearer <key>` |
| 404 | `not_found` | Check keyword/source |
| varies | `data_unavailable` | Retry or change the query |
| 429 | `rate_limited` | Upgrade or wait for monthly reset |
| 500 | `internal_error` | Retry, then email hello@trendsapi.ai |

## MCP

Endpoint: `https://api.trendsapi.ai/mcp`

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

- HTML: https://trendsapi.ai/docs
- Markdown: https://trendsapi.ai/docs.md
- llms.txt: https://trendsapi.ai/llms.txt