Meta Agent Tools
PT

Back to the catalog

Google Trends API

Google Trends search interest over time with growth metrics. Free key at trendsapi.ai

Open source Repository Open in the app JSON README (API)

About

Google Trends search interest over time with growth metrics. Free key at trendsapi.ai

Details

Kind
MCP servers
Topic
Cloud & DevOps
Publisher
ai.trendsapi
Origin
official
Category
ferramentas
Transport
http
Version
1.0.1
Last push
2026-08-18T15:23:15Z
Repository state
ativo
Language
Python
License
MIT
Added
2026-08-29 03:00:42
Updated
2026-08-29 03:00:42
Origin id
ai.trendsapi/google-trends

README

# Google Trends API

Python client for Google Trends data via the Trends API. Normalized 0-100 scores, history + growth, free tier. Not a scraper.

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/google-trends-client.svg)](https://pypi.org/project/google-trends-client/)
[![Python](https://img.shields.io/badge/python-3.9%2B-yellow.svg)](https://trendsapi.ai)
[![npm](https://img.shields.io/npm/v/google-trends-js.svg)](https://www.npmjs.com/package/google-trends-js)

Key: [trendsapi.ai/#get-key](https://trendsapi.ai/#get-key). HTTP contract and every source: [trendsapi-ai/trendsapi](https://github.com/trendsapi-ai/trendsapi).

## Authentication

```bash
pip install google-trends-client
export TRENDSAPI_KEY=your_key
```

Python 3.9+. Same key as the HTTP API.

```python
from google_trends_client import TrendsAPI

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

Keyword helpers default to `source: "google search"`. Pass `source=` to hit any other platform with the same client. Official full client (every source, no preset): [`trendsapi`](https://pypi.org/project/trendsapi/).

## Methods

| Method | REST `mode` | Returns |
|---|---|---|
| `get_time_series(keyword, source=, data_mode=)` | `get_time_series` | `list[TrendsDataPoint]` |
| `get_growth(keyword, percent_growth=, source=, data_mode=)` | `get_growth` | `GetGrowthResponse` |
| `get_live(limit=, offset=, category=)` | `get_top_trends` | `GetTopTrendsResponse` |
| `get_top_trends(type=, ...)` | `get_top_trends` | `GetTopTrendsResponse` |

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

```python
from google_trends_client import TrendsAPI

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

series = client.get_time_series("heat pump")
print(series[-1].date, series[-1].value)

growth = client.get_growth("heat pump", percent_growth=["3M", "12M"])
print(growth.results[0].growth, growth.results[0].direction)

hot = client.get_live(limit=10)
print(hot.data)                         # [[1, "..."], ...]
```

## get_time_series

```python
points = client.get_time_series("heat pump")
```

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 |

Python returns `list[TrendsDataPoint]`. Use `.date` and `.value`, not `["date"]`.
JS returns the same fields as object properties.

## get_growth

```python
g = client.get_growth("heat pump", 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. Python: `growth.results[0].growth`. JS: `growth.results[0].growth`.


## get_live

```python
hot = client.get_live(limit=10)
```

| Field | Meaning |
|---|---|
| `as_of_ts` | Snapshot time |
| `type` | Feed name |
| `limit`, `offset`, `count` | Pagination |
| `data` | `[rank, label]` rows |

Python: `hot.data`. JS: `hot.data`. Optional `offset=` and `category=` (`Amazon Best Sellers by Category`, `Top Websites` only).


## Async

```python
import asyncio
from google_trends_client import AsyncTrendsAPI

async def main():
    c = AsyncTrendsAPI()
    return await asyncio.gather(
        c.get_time_series("heat pump"),
    )

asyncio.run(main())
```

Each 200 is one billed request.

## Pandas

```python
from dataclasses import asdict
import pandas as pd
from google_trends_client import TrendsAPI

df = pd.DataFrame(asdict(p) for p in TrendsAPI().get_time_series("heat pump"))
df["date"] = pd.to_datetime(df["date"])
print(df.set_index("date")["value"].resample("ME").mean().tail())
```

## JavaScript / TypeScript

```bash
npm install google-trends-js
```

Node 18+, Deno, Bun, Workers. Same API key. Field tables above apply.

Also published as [`google-trends-node`](https://www.npmjs.com/package/google-trends-node), [`google-trends-client`](https://www.npmjs.com/package/google-trends-client). Same client, different package name.

### Methods

| Method | REST `mode` | Returns |
|---|---|---|
| `getTimeSeries(keyword, { source, data_mode })` | `get_time_series` | weekly points |
| `getGrowth(keyword, { percent_growth, source, data_mode })` | `get_growth` | growth object |
| `getLive({ limit, offset, category })` | `get_top_trends` | live feed |
| `getTopTrends({ type, ... })` | `get_top_trends` | live feed |

```ts
import { TrendsAPI } from "google-trends-js";

const client = new TrendsAPI({ apiKey: process.env.TRENDSAPI_KEY! });
const series = await client.getTimeSeries("heat pump");
console.log(series.at(-1)?.date, series.at(-1)?.value);

const growth = await client.getGrowth("heat pump", {
  percent_growth: ["3M", "12M"],
});
console.log(growth.results[0].growth, growth.results[0].direction);

const live = await client.getLive({ limit: 10 });
console.log(live.data);                 // [[1, "..."], ...]
```

## Call (curl)

| Field | Value |
|---|---|
| Endpoint | `POST https://api.trendsapi.ai/api` |
| Auth | `Authorization: Bearer $TRENDSAPI_KEY` |
| History | `source: google search` with `get_time_series` or `get_growth` |
| Keyword | Any phrase, e.g. heat pump |
| Live `type` | Google Trends |

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

## Source notes

- Related sources (same endpoint, different `source`): `google images`, `google news`, `google shopping`.
- `value` is 0-100 for this term on Google web search, not Ads impressions.

## Errors

| HTTP | Client |
|---|---|
| 200 | Parsed payload. Python dataclasses / JS typed objects |
| 400 | Raises. Fix `source` or `type` spelling |
| 401 | Raises. Check `TRENDSAPI_KEY` |
| 404 | Raises. No series for that keyword. Do not retry |
| 429 | Raises. Quota |
| 5xx | Client retries, then raises |

The HTTP `body` field is a JSON string. SDKs decode it. Raw curl must parse `body` a second time.

Site: [https://trendsapi.ai/trends/google-trends](https://trendsapi.ai/trends/google-trends).

## License

MIT. See [LICENSE](LICENSE).

More