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 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 '{"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.

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.

Live feeds (Get Top Trends)

Pass the type value below with mode: "get_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).

API modes

Every call is POST https://api.trendsmcp.ai/api with Authorization: Bearer <key>. Pick the operation with the mode field in the JSON body.

get_trends is accepted as an alias for get_time_series (same handler). Prefer get_time_series 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 }

Quota: 1 request per source + keyword. 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). Full rules

Request body

Growth period presets

Custom date range object

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: per feed (type) and per page (limit / offset). Full rules

Request body

Available feeds

{
  "mode":  "get_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."
}