REST API Reference

One POST endpoint. Set mode in the JSON body to choose time series, growth, or top trends.

Authentication

An account is required to connect — both for MCP and the REST API. Sign up for free with your email and we'll send your API key instantly (100 requests/month, no credit card). Every request must then include that API key in the Authorization header. The Bearer prefix is optional; the bare key works too. How calls are counted is defined below (same rules for REST and MCP).

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

import requests

res = requests.post(
    "https://api.trendsmcp.ai/api",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"mode": "get_time_series", "source": "google search", "keyword": "bitcoin"}
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.trendsmcp.ai/api", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ mode: "get_time_series", source: "google search", keyword: "bitcoin" })
});
const data = await res.json();

What counts as a request

Each successful hit against the data API uses one unit of your monthly quota. Failed requests are free: only successful (2xx) calls count.

Data Sources

Two types of sources are available, accessed via different operations. Keyword sources return a historical time series or growth metric for a specific keyword. Live feeds return the top-ranked items on a platform right now. No keyword needed.

Keyword sources (Get Trends & Get Growth)

Pass the source value below in your request body alongside keyword. On REST, set mode to "get_time_series" (time series) or "get_growth" (period-over-period %). For Get Growth, pass one source or a comma-separated list (e.g. amazon, tiktok, youtube). For Get Trends, pass one source per request. Scores are normalized to a 0–100 scale where the pipeline supports it.

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)
python	PyPI project downloads	Exact PyPI project name e.g. pandas, requests

Live feeds (Get Top Trends)

Pass the type value below with mode: "get_top_trends". No keyword needed. Returns the current ranked leaders on that platform (e.g. the top 25 trending hashtags on TikTok right now).

type	Platform / feed
Google Trends	Top trending search terms on Google right now
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
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
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

API modes

Every call is POST https://api.trendsmcp.ai/api with Authorization: Bearer <key> (the Bearer prefix is optional; the bare key works too). Pick the operation with the mode field in the JSON body.

Canonical mode names match the MCP tools. Aliases: get_trends, trends, time_series, and lookup all mean get_time_series; growth means get_growth; top_trends means get_top_trends. Prefer the canonical names in user-facing REST examples.

Copy-paste examples

// Time series
{ "mode": "get_time_series", "source": "google search", "keyword": "bitcoin" }

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

// Top trends
{ "mode": "get_top_trends", "type": "Google Trends", "limit": 10 }

// Top trends, biggest climbers this week (sort: "rank" is the default)
{ "mode": "get_top_trends", "type": "Amazon Best Sellers by Category", "category": "Toys Games", "sort": "rank_change", "window": "7d", "limit": 10 }

Quota: 1 request per source + keyword. History depth by plan: Free 90 days, Starter 1 year, Pro 2+ years, Business full history. Full rules

Request body

Response fields

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

[
  {
    "date":    "2026-03-21",
    "value":   47,
    "volume":  25853617,
    "keyword": "bitcoin",
    "source":  "google search"
  },
  // ... up to 261 weekly data points
]

Quota: 1 request per source + keyword (all percent_growth periods in that call). History depth by plan: Free 90 days, Starter 1 year, Pro 2+ years, Business full history. Full rules

Request body

Growth windows

Any whole number plus a D, W, M, or Y suffix works, up to 5 years (e.g. 7D, 17D, 45D, 3M, 18M, 2Y), plus MTD, QTD, and YTD. Common examples:

Custom date range object (REST only)

Custom date objects are REST-only; MCP accepts the string windows above.

Response fields

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

{
  "mode":    "get_growth",
  "source":  "amazon",
  "keyword": "nike",
  "percent_growth": [
    {
      "name":     "Last Year",
      "recent":   "2025-12-31",
      "baseline": "2024-12-31"
    }
  ]
}

{
  "search_term": "nike",
  "data_source": "google search",
  "results": [
    {
      "period":           "12M",
      "growth":           -12.31,
      "direction":        "decrease",
      "recent_date":      "2026-03-21",
      "baseline_date":    "2025-03-22",
      "recent_value":     57,
      "baseline_value":   65,
      "volume_available": true,
      "recent_volume":    24158298,
      "baseline_volume":  27548936,
      "volume_growth":    -12.31
    }
  ],
  "metadata": {
    "total_data_points":      261,
    "calculations_completed": 1,
    "all_successful":         true
  }
}

Quota: MCP is 1 credit per 10 requested rows (max 10 per call). REST is 1 per POST. Full rules

Request body

Available feeds

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

{
  "mode":     "get_top_trends",
  "type":     "Google Trends by Category",
  "category": "Games",
  "limit":    10
}

{
  "mode":     "get_top_trends",
  "type":     "Amazon Best Sellers by Category",
  "category": "Toys Games",
  "sort":     "rank_change",
  "window":   "7d",
  "limit":    10
}

{
  "as_of_ts": "2026-03-26T22:22:25Z",
  "type":     "Google Trends",
  "limit":    10,
  "count":    10,
  "data": [
    [1, "chuck norris"],
    [2, "project hail mary"],
    [3, "bachelorette cancelled"]
    // ... [rank, name] pairs
  ]
}

MCP / AI

AI Prompts

When using Trends MCP through an AI assistant (Claude, ChatGPT, Cursor, etc.), include "using TrendsMCP" or "via TrendsMCP" in your prompt so the AI routes to the MCP instead of a web search.

Errors

The REST transport always returns HTTP 200. The real outcome is in the payload envelope: {"statusCode": <int>, "body": "<json string>"}. Check statusCode, then parse body. Error bodies carry an error string (one of the codes below) and a message. On MCP, tool failures set isError=true on the tool result.

{
  "statusCode": 400,
  "body": "{\"error\":\"missing_parameter\",\"message\":\"The 'type' parameter is required\"}"
}