# Google Trends API — interest over time (with multi-keyword compare), related and rising queries, related topics, interest by region, trending-now, realtime story-clusters, keyword suggest and the category taxonomy

> Search-interest timeline (0-100) for a keyword or up to 5 compared keywords, by geo+timeframe
> ReefAPI engine `google-trends` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/google-trends/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /google-trends/v1/interest_over_time — 1 credit
Search-interest timeline (0-100) for a keyword or up to 5 compared keywords, by geo+timeframe

**Parameters:**
- `keyword` (string, required) — The search term to analyze (e.g. 'bitcoin'). For multi-term compare use 'keywords'.
- `keywords` (array, optional) — Up to 5 terms to compare (array, or a comma-separated string). When given, overrides 'keyword'; extras beyond 5 are dropped.
- `geo` (string, optional) — Geography filter: empty = Worldwide; a country code (US, GB, DE) or a sub-region code (US-CA, GB-ENG). Country names and US-state names (e.g. 'United Kingdom', 'Texas', 'Austin, TX') are auto-mapped to codes. Omit for worldwide.
- `timeframe` (string, optional, default "today 12-m") — Date range in Google Trends syntax, e.g. 'today 12-m', 'today 5-y', 'now 7-d', 'all', or an explicit 'YYYY-MM-DD YYYY-MM-DD'.
- `category` (integer, optional, default 0) — Google Trends category id to narrow the topic (0 = All categories). e.g. 7=Finance, 5=Computers & Electronics.
- `property` (enum, optional) — Which Google property's search interest to measure. Empty = web search. [one of: , images, news, youtube, froogle]

**Returns:** keywords[], geo, timeframe, timeline[] (date/value 0-100; per-keyword `values` when comparing)

**Example request body:**
```json
{
  "keyword": "bitcoin",
  "geo": "US",
  "timeframe": "today 12-m"
}
```

### POST /google-trends/v1/related_queries — 1 credit
Top + rising related search queries for a keyword (rising shows Breakout / +%)

**Parameters:**
- `keyword` (string, required) — The search term to analyze (e.g. 'bitcoin'). For multi-term compare use 'keywords'.
- `geo` (string, optional) — Geography filter: empty = Worldwide; a country code (US, GB, DE) or a sub-region code (US-CA, GB-ENG). Country names and US-state names (e.g. 'United Kingdom', 'Texas', 'Austin, TX') are auto-mapped to codes. Omit for worldwide.
- `timeframe` (string, optional, default "today 12-m") — Date range in Google Trends syntax, e.g. 'today 12-m', 'today 5-y', 'now 7-d', 'all', or an explicit 'YYYY-MM-DD YYYY-MM-DD'.
- `category` (integer, optional, default 0) — Google Trends category id to narrow the topic (0 = All categories). e.g. 7=Finance, 5=Computers & Electronics.
- `property` (enum, optional) — Which Google property's search interest to measure. Empty = web search. [one of: , images, news, youtube, froogle]

**Returns:** keyword, geo, timeframe, top[] (query/value/link), rising[] (query/value=Breakout or +%/link)

**Example request body:**
```json
{
  "keyword": "bitcoin",
  "geo": "US",
  "timeframe": "today 12-m"
}
```

### POST /google-trends/v1/related_topics — 1 credit
Top and rising related topics (entity name and type) from Google Trends. Note: Google currently returns empty results for this widget — use related_queries for keyword data instead.

**Parameters:**
- `keyword` (string, required) — The search term to analyze (e.g. 'bitcoin'). For multi-term compare use 'keywords'.
- `geo` (string, optional) — Geography filter: empty = Worldwide; a country code (US, GB, DE) or a sub-region code (US-CA, GB-ENG). Country names and US-state names (e.g. 'United Kingdom', 'Texas', 'Austin, TX') are auto-mapped to codes. Omit for worldwide.
- `timeframe` (string, optional, default "today 12-m") — Date range in Google Trends syntax, e.g. 'today 12-m', 'today 5-y', 'now 7-d', 'all', or an explicit 'YYYY-MM-DD YYYY-MM-DD'.
- `category` (integer, optional, default 0) — Google Trends category id to narrow the topic (0 = All categories). e.g. 7=Finance, 5=Computers & Electronics.
- `property` (enum, optional) — Which Google property's search interest to measure. Empty = web search. [one of: , images, news, youtube, froogle]

**Returns:** keyword, geo, timeframe, top[] + rising[] (topic_title/topic_mid/topic_type/value) — currently [] while Google throttles this widget

**Example request body:**
```json
{
  "keyword": "bitcoin"
}
```

### POST /google-trends/v1/interest_by_region — 1 credit
Search interest by sub-region (states/countries), 0-100 normalized — single keyword; multiple keywords returns the compared breakdown by region (per-keyword %-share)

**Parameters:**
- `keyword` (string, required) — The search term to analyze (e.g. 'bitcoin'). For multi-term compare use 'keywords'.
- `keywords` (array, optional) — Up to 5 terms to compare (array, or a comma-separated string). When given, overrides 'keyword'; extras beyond 5 are dropped.
- `geo` (string, optional) — Geography filter: empty = Worldwide; a country code (US, GB, DE) or a sub-region code (US-CA, GB-ENG). Country names and US-state names (e.g. 'United Kingdom', 'Texas', 'Austin, TX') are auto-mapped to codes. Omit for worldwide.
- `timeframe` (string, optional, default "today 12-m") — Date range in Google Trends syntax, e.g. 'today 12-m', 'today 5-y', 'now 7-d', 'all', or an explicit 'YYYY-MM-DD YYYY-MM-DD'.
- `resolution` (enum, optional) — interest_by_region granularity. Defaults to the geo's natural level; an unrecognized value is ignored. [one of: COUNTRY, REGION, CITY, DMA]
- `category` (integer, optional, default 0) — Google Trends category id to narrow the topic (0 = All categories). e.g. 7=Finance, 5=Computers & Electronics.
- `property` (enum, optional) — Which Google property's search interest to measure. Empty = web search. [one of: , images, news, youtube, froogle]

**Returns:** keywords[], geo, timeframe, compared(bool), resolution, regions[] (geo_code/geo_name/value 0-100; per-keyword `values` when comparing)

**Example request body:**
```json
{
  "keyword": "bitcoin",
  "geo": "US",
  "timeframe": "today 12-m"
}
```

### POST /google-trends/v1/trending_now — 1 credit
Currently trending searches for a geo (title + approx traffic + news articles)

**Parameters:**
- `geo` (string, optional, default "US") — Country code for the trending feed (e.g. US, GB, JP). Required by the RSS feed; defaults to US.

**Returns:** geo, trends[] (title/traffic/approx_traffic/link/articles[] with title/url/source)

**Example request body:**
```json
{
  "geo": "US"
}
```

### POST /google-trends/v1/suggest — 1 credit
Keyword autocomplete — candidate topics/entities (the Google Trends suggestion list) so you can pick the right entity (e.g. the 'Apple Inc. — Technology company' topic mid vs the fruit) before querying interest_over_time/related.

**Parameters:**
- `keyword` (string, required) — The term to autocomplete into Trends topics/entities.
- `hl` (string, optional, default "en-US") — UI language for suggestion titles (e.g. en-US, tr, de).

**Returns:** keyword, suggestions[]{mid, title, type}

**Example request body:**
```json
{
  "keyword": "bitcoin"
}
```

### POST /google-trends/v1/categories — 1 credit
List the Google Trends category taxonomy (id + name, hierarchical) so you can find the right `category` id to narrow interest_over_time / related_queries / interest_by_region (e.g. 7=Finance, 5=Computers & Electronics). Optionally filter by a name substring.

**Parameters:**
- `query` (string, optional) — Optional case-insensitive substring to filter category names (e.g. 'finance', 'sports'). Omit to list the full taxonomy.

**Returns:** query, total (full taxonomy size), categories[]{id, name, parent_id, parent_name, depth} — pass an `id` as the `category` param of other actions

### POST /google-trends/v1/realtime_trending — 2 credits
Realtime trending story-clusters for a country (richer than trending_now): each cluster has a title, approximate search-traffic volume, the FULL related-query set, category ids, and an article count. Best for 'what is breaking right now' research.

**Parameters:**
- `geo` (string, optional, default "US") — Country code for the realtime feed (e.g. US, GB, JP, TR). Country-level only (sub-region suffixes are dropped). Country/US-state names are auto-mapped. Defaults to US.
- `hours` (enum, optional, default 24) — Trailing time window for the realtime feed. Defaults to 24h. [one of: 4, 24, 48, 168]
- `limit` (integer, optional, default 50) — Max story-clusters to return (1-300; Google returns the most trending first). Defaults to 50.

**Returns:** geo, hours_window, stories[]{title, traffic, started/started_date, ended, active, category_ids[], related_queries[], article_count}

**Example request body:**
```json
{
  "geo": "US"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=google-trends
- Human docs page: https://reefapi.com/docs/google-trends
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt