MCP & API Reference

Query behavioral trend data across search, social, and commerce platforms. Use MCP to query via an AI assistant like Claude or ChatGPT, or the REST API to integrate directly into your code.

Base URL

https://api.trendsmcp.ai/api

Method

POST /

Auth

Authorization: Bearer <key>

Format

application/json

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 as a Bearer token in the Authorization header. 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 '{"source":"google search","keyword":"bitcoin"}'

import requests

res = requests.post(
    "https://api.trendsmcp.ai/api",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"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({ 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.

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. 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.

Live feeds (Get Top Trends)

Pass the type value below with mode: "top_trends". No keyword needed. Optional category filter for Amazon Best Sellers by Category and Top Websites. Returns the current ranked leaders on that platform (e.g. the top 25 trending hashtags on TikTok right now).

Routing

All requests go to a single POST / endpoint. The operation is selected by the fields you include in the request body.

Returns a full historical time series for a keyword from a single source. Approximately 5 years of weekly data. Values normalized to 0–100 where the pipeline supports it. Specify one source per request.

Quota: 1 request per source + keyword. Full rules

Request body

Response fields

{
  "source":    "google search",
  "keyword":   "bitcoin",
  "data_mode": "weekly"
}

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

Calculates point-to-point percentage growth for a keyword over one or more time windows. Supports preset strings ("12M", "YTD", etc.) or exact custom date pairs. Pass one source or a comma-separated list (e.g. amazon, tiktok, youtube) for multi-source comparison.

Quota: 1 request per source + keyword (all percent_growth periods in that call). Full rules

Request body

Growth period presets

Custom date range object

Response fields

{
  "source":         "google search",
  "keyword":        "nike",
  "percent_growth": ["12M", "3M", "YTD"]
}

{
  "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
  }
}

Returns ranked items from live platform feeds stored for Trends MCP. On the REST API, omit type to aggregate every feed in one response (same semantics the handler uses internally). On MCP, the get_top_trends tool requires an explicit type per call. There is no single MCP invocation that returns all feeds at once.

Quota: per feed (type) and per page (limit / offset). Full rules

Request body

Available feeds

{
  "mode":  "top_trends",
  "type":  "Google Trends",
  "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

Errors return JSON with an error string and message. HTTP status may be 4xx/5xx depending on the failure; some upstream gaps are reported as data_unavailable (or similar) with a generic message rather than not_found.

Additional codes can appear as the data layer evolves; treat message as the operator-facing detail.

{
  "error":   "missing_parameter",
  "message": "The 'keyword' parameter is required."
}