### Get Growth Request and Response

Source: https://trendsmcp.ai/docs

Examples for requesting growth metrics using presets or custom date ranges, and the resulting response object.

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

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

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

--------------------------------

### Direct REST API Interaction Examples

Source: https://trendsmcp.ai/docs

Examples for querying the TrendsMCP API directly using cURL, Python, and JavaScript.

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

```python
import requests

res = requests.post("https://api.trendsmcp.ai/api",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"source": "google search", "keyword": "bitcoin"}).json()
print({r["date"]: r["value"] for r in __import__("json").loads(res["body"])})
```

```javascript
const { body } = 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" })
}).then(r => r.json());
console.log(Object.fromEntries(JSON.parse(body).map(r => [r.date, r.value])));
```

--------------------------------

### Get Trends Request and Response

Source: https://trendsmcp.ai/docs

Example request for trend data and the corresponding JSON response structure.

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

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

--------------------------------

### Available Feeds and Request/Response Example

Source: https://trendsmcp.ai/docs

This section details the available data feeds and provides an example of a request and its corresponding response for the 'Google Trends' feed.

```APIDOC
## Available Feeds

- Amazon Best Sellers by Category
- Amazon Best Sellers Top Rated
- App Store Top Free
- App Store Top Paid
- Google News Top News
- Google Play
- Google Trends
- Reddit Hot Posts
- Reddit World News
- Top Websites
- Spotify Top Podcasts
- TikTok Trending Hashtags
- Wikipedia Trending
- X (Twitter) Trending
- YouTube Trending

### Request Example (Google Trends)

```json
{
  "mode":  "top_trends",
  "type":  "Google Trends",
  "limit": 10
}
```

### Response Example (Google Trends)

```json
{
  "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
  ]
}
```
```

--------------------------------

### POST / (Get Growth)

Source: https://trendsmcp.ai/docs

Calculates point-to-point percentage growth for a keyword over one or more time windows using preset strings or custom date ranges.

```APIDOC
## POST /

### Description
Calculates point-to-point percentage growth for a keyword over one or more time windows. Supports preset strings or exact custom date pairs.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **source** (string) - Required - Data source.
- **keyword** (string) - Required - Keyword, brand, or topic.
- **percent_growth** (array) - Required - Array of preset strings or custom date objects.
- **data_mode** (string) - Optional - Applies where supported (often Google sources).

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

### Response
#### Success Response (200)
- **search_term** (string) - The keyword queried.
- **data_source** (string) - The source used.
- **results** (array) - One object per period requested.
- **metadata** (object) - Contains total_data_points, calculations_completed, and all_successful.
```

--------------------------------

### AI Prompting Guide for Trends MCP

Source: https://trendsmcp.ai/docs

To ensure your AI assistant routes requests to Trends MCP instead of performing a web search, include specific phrases like 'using TrendsMCP' or 'via TrendsMCP' in your prompt.

```APIDOC
## 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.

### Examples:
- **Get Trends Historical time series for a keyword**
  - "Using TrendsMCP, show me the Google Search trend for `nvidia` over the past 5 years."
  - "Via TrendsMCP, pull daily Google Search data for `ozempic` over the last month."
  - "Using TrendsMCP, show me the YouTube and TikTok trend history for `Stanley cup`."
  - "Via TrendsMCP, get the Wikipedia page view history for `Bitcoin` weekly."
  - "Using TrendsMCP, show me the Amazon search trend for `air fryer` over 5 years."
  - "Via TrendsMCP, pull the npm download trend for `langchain` weekly."
  - "Using TrendsMCP, show me Steam concurrent player data for `Elden Ring`."
  - "Via TrendsMCP, show the news volume trend for `Tesla` over the last year."
  - "Using TrendsMCP, show subscriber history for subreddit `wallstreetbets` on Reddit."

- **Get Growth Point-to-point growth & momentum**
  - "Using TrendsMCP, how has Google Search interest in `GLP-1` grown over the past 12 months?"
  - "Via TrendsMCP, show me 3M, 6M, and 1Y growth for `Anthropic` on Google Search."
  - "Using TrendsMCP, what's the YTD Google Search growth for `Duolingo`?"
  - "Via TrendsMCP, compare 6-month growth for `weight loss drugs` across Google, TikTok, and Amazon."
  - "Using TrendsMCP, how has news sentiment for `Meta` changed over the past 6 months?"
  - "Via TrendsMCP, show Google Search growth for `AI agents` from Jan 2025 to Jan 2026."
  - "Using TrendsMCP, what's the subscriber growth for subreddit `wallstreetbets` on Reddit over the last 30 days?"
  - "Via TrendsMCP, show me 12M Google Shopping growth for `running shoes`."

- **Get Top Trends Live leaderboards across platforms**
  - "Using TrendsMCP, what's trending on Google right now?"
  - "Via TrendsMCP, show me the top TikTok trending hashtags today."
  - "Using TrendsMCP, what are the hottest Reddit posts right now?"
  - "Via TrendsMCP, what are the top trending Wikipedia articles today?"
  - "Using TrendsMCP, show me what's trending on X right now."
  - "Via TrendsMCP, what apps are topping the App Store Free charts today?"
  - "Using TrendsMCP, what are the top-rated Amazon best sellers right now?"
  - "Via TrendsMCP, show Amazon best sellers for category `Electronics`."
  - "Via TrendsMCP, what's trending on YouTube right now?"
```

--------------------------------

### Request and Response for Trending Data

Source: https://trendsmcp.ai/docs

Example of a request to fetch top trends and the corresponding JSON response structure.

```json
{
  "mode":  "top_trends",
  "type":  "Google Trends",
  "limit": 10
}
```

```json
{
  "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
  ]
}
```

--------------------------------

### POST / (Get Top Trends)

Source: https://trendsmcp.ai/docs

Returns ranked items from live platform feeds. Supports pagination and filtering by feed type.

```APIDOC
## POST /

### Description
Returns ranked items from live platform feeds stored for Trends MCP.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **mode** (string) - Required - Set to "top_trends".
- **type** (string) - Optional - REST: omit for all feeds. MCP: required (one feed per tool call).
- **limit** (integer) - Optional - Max items per feed (up to 200, default 25).
- **offset** (integer) - Optional - REST: skip this many rows per feed for pagination.
```

--------------------------------

### POST / - Trends MCP API Endpoint

Source: https://trendsmcp.ai/docs

This is the primary endpoint for interacting with the Trends MCP API. The specific operation (Get Trends, Get Growth, or Get Top Trends) is determined by the fields included in the request body.

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

Operation| Required fields  
---|---  
Get Trends | `source` + `keyword` (no `percent_growth`)  
Get Growth | `source` + `keyword` + `percent_growth`  
Get Top Trends | `mode: "top_trends"`  

# POST /

## Get Trends
Returns a full historical time series for a keyword from a single source. For **Google Search** (and other Google verticals where the backend supports it), the default is long-range weekly data; `data_mode: "daily"` requests a recent daily window (typically about the last 30 days). Many other sources use a fixed cadence or ignore `data_mode`. Always interpret the returned dates as source-native.

Quota: 1 request per `source` + `keyword`. Full rules

### Request body
Field| Type| Required| Description  
---|---|---|---  
`source` | string | Required | Data source. See Data Sources.  
`keyword` | string | Required | Keyword, brand, product, or topic.  
`data_mode` | string | Optional | REST only: `"weekly"` or `"daily"` where the source supports Google-style modes; otherwise ignored or N/A. MCP tool schemas do not expose this field; omit it when using MCP.  
```

--------------------------------

### Configure TrendsMCP for Claude Desktop

Source: https://trendsmcp.ai/docs

JSON configuration for Claude Desktop using npx command execution.

```json
"trends-mcp": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://api.trendsmcp.ai/mcp",
    "--header",
    "Authorization:${AUTH_HEADER}"
  ],
  "env": {
    "AUTH_HEADER": "Bearer YOUR_API_KEY"
  }
}
```

--------------------------------

### Configure TrendsMCP for Cursor and Windsurf

Source: https://trendsmcp.ai/docs

JSON configuration for MCP clients using HTTP transport.

```json
"trends-mcp": {
  "url": "https://api.trendsmcp.ai/mcp",
  "transport": "http",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
```

--------------------------------

### Configure TrendsMCP for VS Code

Source: https://trendsmcp.ai/docs

JSON configuration for the VS Code MCP extension.

```json
"trends-mcp": {
  "type": "http",
  "url": "https://api.trendsmcp.ai/mcp",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
```

--------------------------------

### Add TrendsMCP via Claude Code CLI

Source: https://trendsmcp.ai/docs

Command line instruction to add the MCP server to Claude Code.

```bash
claude mcp add --transport http trends-mcp https://api.trendsmcp.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Authentication and API Request Patterns

Source: https://trendsmcp.ai/docs

Standardized request patterns for cURL, Python, and JavaScript with error handling.

```bash
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"}'
```

```python
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()
```

```javascript
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();
```

--------------------------------

### MCP API - Query Behavioral Trends

Source: https://trendsmcp.ai/docs

Use the MCP REST API to programmatically query behavioral trend data. Authentication is required using a Bearer token.

```APIDOC
## POST /api

### Description
Queries behavioral trend data across search, social, and commerce platforms.

### Method
POST

### Endpoint
https://api.trendsmcp.ai/api

### Parameters
#### Request Body
- **query** (string) - Required - The natural language query for the AI assistant (e.g., Claude or ChatGPT).

### Request Example
```json
{
  "query": "What are the top trending fashion items this week?"
}
```

### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Authorization: Bearer <key>`
- **Content-Type** (string) - Required - `application/json`

### Response
#### Success Response (200)
- **results** (array) - Contains the trend data.
- **source** (string) - The platform the data was sourced from.

#### Response Example
```json
{
  "results": [
    {
      "trend": "Sustainable Denim",
      "platform": "commerce",
      "score": 0.95
    },
    {
      "trend": "Vintage Style Revival",
      "platform": "social",
      "score": 0.88
    }
  ]
}
```
```

--------------------------------

### Error Response Format

Source: https://trendsmcp.ai/docs

Standard JSON structure returned when an API request fails.

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

--------------------------------

### Error Handling

Source: https://trendsmcp.ai/docs

Details on the error codes and messages returned by the API, including common HTTP status codes and their meanings.

```APIDOC
## Errors

Errors return JSON with an `error` string and `message`.

| Status | Error code       | Meaning                                                                                                |
|--------|------------------|--------------------------------------------------------------------------------------------------------|
| 400    | `missing_parameter`| Required field missing from request body                                                               |
| 400    | `invalid_source` | Unrecognized `source` value (message may list allowed values)                                          |
| 401    |                  | Missing or invalid API key                                                                             |
| 404    | `not_found`      | No series or entity matched this keyword/source (when the pipeline classifies it that way)             |
| varies | `data_unavailable`| Pipeline could not return data (temporary gap, unsupported query, or empty upstream). Read `message`. |
| 429    | `rate_limited`   | Monthly request limit reached. Upgrade for more.                                                       |
| 500    | `internal_error` | Unexpected server error                                                                                |

### 400 Response Example

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.