Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
contact:
email: '[email protected]'
name: TrendsMCP API Support
url: https://www.trendsmcp.ai
description: 'One POST endpoint for trend data: historical time series, point-to-point growth windows, and live trending feeds across Google, Google Images, Google News, Google Shopping, YouTube, Wikipedia, TikTok, Amazon, npm, PyPI, Steam, Google Play, App Store, GitHub, Google Trends, IMDb, Open Library, Reddit, Web, Spotify, Substack, X, Instagram, Bluesky, Hacker News, Polymarket. Scores use a 0-100 index with absolute volume where available. Pick the operation with the `mode` field in the JSON body. The same operations are also available as MCP tools at `https://api.trendsmcp.ai/mcp`. Free API key (100 requests/month): https://www.trendsmcp.ai/account'
license:
name: Terms of Service
url: https://www.trendsmcp.ai/terms
summary: Live trend data across search, social, commerce, news, and developer platforms
title: TrendsMCP Trends API
version: 1.0.0
x-mcp-server: https://api.trendsmcp.ai/mcp
servers:
- description: Production
url: https://api.trendsmcp.ai
security:
- bearerAuth: []
tags:
- description: Trend data operations
name: Trends
paths:
/api:
post:
description: 'Run one tool, picked by the `mode` field: `get_time_series` (full history for one topic, 1 request per call); `get_growth` (how fast something is rising, 1 request per call, every window included); `get_top_trends` (what''s moving right now, MCP: 1 request per 10 rows, at most 10 per call. REST: 1 request per call); `get_context` (what people are saying, MCP: 1 request per source, at most 5 per call. REST: one source per call, 1 request); `get_top_posts` (top posts for one hashtag, 1 request per call).'
operationId: queryTrends
requestBody:
content:
application/json:
examples:
growth:
summary: Growth over several windows
value:
keyword: nike
mode: get_growth
percent_growth:
- 12M
- 3M
- YTD
source: google search
movers:
summary: Biggest climbers in a category this week
value:
category: Toys Games
limit: 10
mode: get_top_trends
sort: rank_change
type: Amazon Best Sellers by Category
window: 7d
timeSeries:
summary: Weekly Google Search series for a keyword
value:
keyword: bitcoin
mode: get_time_series
source: Google Search
topTrends:
summary: Live Google Trends board
value:
limit: 10
mode: get_top_trends
type: Google Trends
schema:
discriminator:
mapping:
get_context: '#/components/schemas/GetContextRequest'
get_growth: '#/components/schemas/GetGrowthRequest'
get_time_series: '#/components/schemas/GetTimeSeriesRequest'
get_top_posts: '#/components/schemas/GetTopPostsRequest'
get_top_trends: '#/components/schemas/GetTopTrendsRequest'
propertyName: mode
oneOf:
- $ref: '#/components/schemas/GetTimeSeriesRequest'
- $ref: '#/components/schemas/GetGrowthRequest'
- $ref: '#/components/schemas/GetTopTrendsRequest'
- $ref: '#/components/schemas/GetTopPostsRequest'
- $ref: '#/components/schemas/GetContextRequest'
required: true
responses:
'200':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TimeSeriesResponse'
- $ref: '#/components/schemas/GrowthResponse'
- $ref: '#/components/schemas/TopTrendsResponse'
description: 'Always HTTP 200 at the transport level, including for errors. The payload is an envelope: {"statusCode": <int>, "body": <json string>}. A 2xx statusCode means success; parse `body` as one of the schemas below (shape depends on `mode`: an array of points for get_time_series, a growth report for get_growth, a ranked board for get_top_trends). Any other statusCode means `body` parses to the Error schema.'
security:
- bearerAuth: []
summary: Query trend data
tags:
- Trends
components:
schemas:
TimeSeriesPoint:
properties:
date:
format: date
type: string
keyword:
type: string
source:
type: string
value:
description: Trend score on a 0-100 index.
maximum: 100
minimum: 0
type: number
volume:
description: Absolute volume where available.
type:
- number
- 'null'
type: object
GrowthResult:
properties:
baseline_date:
format: date
type: string
baseline_value:
type: number
baseline_volume:
type:
- number
- 'null'
direction:
description: '''increase'' or ''decrease''.'
type: string
growth:
description: Percentage change, e.g. -12.31.
type: number
period:
type: string
recent_date:
format: date
type: string
recent_value:
type: number
recent_volume:
type:
- number
- 'null'
volume_available:
type: boolean
volume_growth:
type:
- number
- 'null'
type: object
TopTrendsResponse:
properties:
as_of_ts:
format: date-time
type: string
baseline_ts:
description: Present only when sort is 'rank_change'.
format: date-time
type: string
category:
type: string
count:
type: integer
data:
items:
oneOf:
- description: '[rank, keyword] for sort=''rank''.'
prefixItems:
- description: Current rank.
type: integer
- description: Keyword or item name.
type: string
type: array
- description: Mover row for sort='rank_change'.
properties:
category_path:
type: string
keyword:
type: string
prev_rank:
type: integer
rank:
type: integer
rank_change:
description: Positions climbed.
type: integer
type: object
type: array
limit:
type: integer
note:
description: Present when count is 0 to explain why and what to do next.
type: string
sort:
type: string
type:
type: string
window:
type: string
type: object
TimeSeriesResponse:
description: ~5 years of weekly data points, oldest to newest.
items:
$ref: '#/components/schemas/TimeSeriesPoint'
type: array
GetTopPostsRequest:
description: Live top posts for one hashtag, fetched on every call. Business plan.
properties:
keyword:
description: 'The hashtag, with or without #.'
type: string
limit:
default: 20
maximum: 20
minimum: 1
type: integer
mode:
const: get_top_posts
description: Canonical name (matches the MCP tool).
type: string
source:
description: One platform.
enum:
- TikTok
- Instagram
type: string
required:
- mode
- source
- keyword
type: object
GetTimeSeriesRequest:
properties:
country:
description: 'ISO 3166-1 alpha-2 country code (US, GB, JP). Boards and TikTok default to US; Google time series and growth default to worldwide. Only for: Google Search, Google Images, Google News, Google Shopping, YouTube, TikTok.'
type: string
keyword:
description: 'What to look up. The string format is required by source. Google Search, Google Images, Google News, Google Shopping, YouTube, Wikipedia, TikTok, Amazon: any name or phrase, e.g. ''nike''. npm: Exact npmjs.com package name, case-sensitive. Right: ''react'', ''@babel/core''. Wrong: ''React'', ''React.js''. Python: Exact PyPI project name. Right: ''pandas'', ''requests''. Wrong: ''Pandas''. Steam: Game display name in plain English, not a Steam App ID. Right: ''Elden Ring'', ''CS2''. First Steam store search result wins, so use an unambiguous name. App Downloads: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART. App Rankings: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART.'
type: string
language:
default: en
description: 'Wikipedia language edition (en, de, ja, pt); defaults to en. Only for: Wikipedia.'
type: string
mode:
const: get_time_series
description: 'Canonical name (matches the MCP tool). Aliases: ''get_trends'', ''trends'', ''time_series'', ''lookup''.'
type: string
resolution:
default: weekly
description: '''weekly'' (about 5 years, default) or ''daily'' (last 90 days, fetched live). Only for: Google Search, Google Images, Google News, Google Shopping, YouTube.'
enum:
- weekly
- daily
type: string
source:
description: Exactly one source per request.
enum:
- Google Search
- Google Images
- Google News
- Google Shopping
- YouTube
- Wikipedia
- TikTok
- Amazon
- npm
- Python
- Steam
- App Downloads
- App Rankings
type: string
required:
- mode
- source
- keyword
type: object
GetGrowthRequest:
properties:
country:
description: 'ISO 3166-1 alpha-2 country code (US, GB, JP). Boards and TikTok default to US; Google time series and growth default to worldwide. Only for: Google Search, Google Images, Google News, Google Shopping, YouTube, TikTok.'
type: string
keyword:
description: 'What to look up. The string format is required by source. Google Search, Google Images, Google News, Google Shopping, YouTube, Wikipedia, TikTok, Amazon: any name or phrase, e.g. ''nike''. npm: Exact npmjs.com package name, case-sensitive. Right: ''react'', ''@babel/core''. Wrong: ''React'', ''React.js''. Python: Exact PyPI project name. Right: ''pandas'', ''requests''. Wrong: ''Pandas''. Steam: Game display name in plain English, not a Steam App ID. Right: ''Elden Ring'', ''CS2''. First Steam store search result wins, so use an unambiguous name. App Downloads: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART. App Rankings: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART.'
type: string
language:
default: en
description: 'Wikipedia language edition (en, de, ja, pt); defaults to en. Only for: Wikipedia.'
type: string
mode:
const: get_growth
description: 'Canonical name (matches the MCP tool). Alias: ''growth''.'
type: string
percent_growth:
default:
- 12M
description: Growth windows. Each item is a window string or, on REST only, a custom date-range object. Every window is a two-date comparison. `window` is accepted as a REST alias.
items:
oneOf:
- description: 'Any whole number plus a D, W, M, or Y suffix, up to 5 years (e.g. ''7D'', ''17D'', ''45D'', ''3M'', ''18M'', ''2Y''), or MTD, QTD, YTD. Common presets: 7D, 1W, 14D, 2W, 30D, 1M, 2M, 3M, 6M, 9M, 12M, 1Y, 18M, 24M, 2Y, 36M, 3Y, 48M, 4Y, 60M, 5Y, MTD, QTD, YTD.'
type: string
- description: Custom date range. REST only; MCP accepts the string windows.
properties:
baseline:
format: date
type: string
name:
description: Optional label.
type: string
recent:
format: date
type: string
required:
- recent
- baseline
type: object
type: array
resolution:
default: weekly
description: '''weekly'' (about 5 years, default) or ''daily'' (last 90 days, fetched live). Only for: Google Search, Google Images, Google News, Google Shopping, YouTube.'
enum:
- weekly
- daily
type: string
source:
description: One source, or comma-separated sources for get_growth (e.g. 'amazon, tiktok, youtube'). get_time_series takes exactly one.
enum:
- Google Search
- Google Images
- Google News
- Google Shopping
- YouTube
- Wikipedia
- TikTok
- Amazon
- npm
- Python
- Steam
- App Downloads
- App Rankings
type: string
required:
- mode
- source
- keyword
type: object
GrowthResponse:
properties:
data_source:
type: string
metadata:
properties:
all_successful:
type: boolean
calculations_completed:
type: integer
total_data_points:
type: integer
type: object
results:
items:
$ref: '#/components/schemas/GrowthResult'
type: array
search_term:
type: string
type: object
GetTopTrendsRequest:
properties:
category:
description: 'Required when type is one of: Amazon Best Sellers by Category, Google Trends by Category, Top Websites, Substack by Category, TikTok Trending Hashtags by Category. Use the official category name (case-insensitive).'
type: string
country:
description: 'ISO 3166-1 alpha-2 code (US, GB, JP); default US. Only for: Google Trends, Google Trends by Category, TikTok Trending Hashtags, TikTok Trending Hashtags by Category, X (Twitter) Trending, YouTube Trending.'
type: string
limit:
default: 25
description: Max rows to return. Free plan boards return the top 10 only.
maximum: 200
minimum: 1
type: integer
mode:
const: get_top_trends
description: 'Canonical name (matches the MCP tool). Alias: ''top_trends''.'
type: string
offset:
default: 0
description: Rows to skip for pagination. Pinned to 0 on the Free plan; pagination is a paid feature.
minimum: 0
type: integer
sort:
default: rank
description: '''rank'': current leaders. ''rank_change'': biggest climbers vs a prior snapshot (rows include prev_rank and rank_change).'
enum:
- rank
- rank_change
type: string
type:
description: One live feed. Required on both REST and MCP; omitting it returns a 400 missing_parameter error.
enum:
- Amazon Best Sellers Top Rated
- Amazon Best Sellers by Category
- App Store Top Free
- App Store Top Paid
- GitHub
- Google News Top News
- Google Play
- Google Trends
- Google Trends by Category
- IMDb MOVIEmeter
- Open Library Trending Books
- Reddit Hot Posts
- Reddit World News
- Top Websites
- Spotify Top Podcasts
- Steam Most Played
- Substack
- Substack by Category
- TikTok Trending Hashtags
- TikTok Trending Hashtags by Category
- TikTok Trending Searches
- Wikipedia Trending
- X (Twitter) Trending
- YouTube Trending
type: string
window:
default: 30d
description: Lookback used only when sort is 'rank_change'. Short windows only have baselines on daily feeds.
enum:
- 1d
- 3d
- 7d
- 14d
- 30d
type: string
required:
- mode
- type
type: object
GetContextRequest:
description: 'What people are posting, reading and betting about a keyword right now: posts, videos, stories, comments and markets from each source, with engagement.'
properties:
days:
description: Look back 1 to 30 days. Default 7.
type: integer
keyword:
description: Any name or phrase.
type: string
limit:
description: Items per source, 1 to 20. Default 10.
type: integer
mode:
const: get_context
description: Canonical name (matches the MCP tool).
type: string
source:
description: 'One source, or up to 5 separated by commas. One of: News, YouTube, TikTok, Instagram, X, Reddit, Bluesky, Hacker News, Polymarket, GitHub.'
type: string
required:
- mode
- keyword
- source
type: object
securitySchemes:
bearerAuth:
description: API key (format `tmcp_live_...`). Get one free at https://www.trendsmcp.ai/account
scheme: bearer
type: http