{"components":{"schemas":{"ContextResponse":{"description":"Per source, the posts, videos, stories and markets about the keyword, best first.","properties":{"keyword":{"description":"The keyword you asked for.","type":"string"},"sources":{"items":{"properties":{"error":{"description":"Why a source returned nothing, when it failed.","type":["string","null"]},"items":{"description":"Each item: kind, url, title, text, author, published, engagement (views, likes, comments, shares, score\u2026), top_comments.","type":"array"},"source":{"description":"The source.","type":"string"}},"type":"object"},"type":"array"},"window_days":{"description":"How far back it looked.","type":"number"}},"type":"object"},"Envelope":{"description":"REST answers HTTP 200 with an envelope: `{\"statusCode\": 400, \"body\": \"\u2026\"}`. Read `statusCode`, then parse `body`. A missing or wrong key is the exception: HTTP 401 (`missing_api_key`) or 403 (`invalid_api_key`), with the error object as the body. Errors carry an `error` code and a `message`. Over MCP, a failed call sets `isError` on the tool result.","properties":{"body":{"contentMediaType":"application/json","contentSchema":{"oneOf":[{"$ref":"#/components/schemas/TimeSeriesResponse"},{"$ref":"#/components/schemas/GrowthResponse"},{"$ref":"#/components/schemas/TopTrendsResponse"},{"$ref":"#/components/schemas/TopPostsResponse"},{"$ref":"#/components/schemas/ContextResponse"},{"$ref":"#/components/schemas/Error"}]},"description":"JSON text: parse it a second time. On success it matches the tool's response schema; any other statusCode means it parses to Error.","type":"string"},"statusCode":{"description":"The real outcome: 200 on success, otherwise the error status.","type":"integer"}},"required":["statusCode","body"],"type":"object"},"Error":{"description":"The error object: the parsed envelope body when statusCode is not 2xx, or the response body itself on the HTTP 401 and 403 key errors.","properties":{"error":{"enum":["missing_parameter","invalid_source","invalid_mode","invalid_request","no_data","plan_required","source_unavailable","growth_calculation_failed","internal_error","missing_api_key","invalid_api_key","monthly_limit_reached"],"type":"string"},"message":{"type":"string"},"request_id":{"description":"Present on internal_error; quote it when contacting support.","type":"string"}},"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"},"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, Pinterest.","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, Pinterest: 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","Pinterest","npm","Python","Steam","App Downloads","App Rankings"],"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, Pinterest.","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, Pinterest: 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","Pinterest","npm","Python","Steam","App Downloads","App Rankings"],"type":"string"}},"required":["mode","source","keyword"],"type":"object"},"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"},"GetTopTrendsRequest":{"properties":{"category":{"description":"Required when type is one of: Amazon Best Sellers by Category, Google Trends by Category, Pinterest Trending 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, Pinterest Trending, Pinterest Trending 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","Pinterest Trending","Pinterest Trending by Category","Polymarket Top Markets","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"},"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"},"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"},"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"},"TimeSeriesResponse":{"description":"~5 years of weekly data points, oldest to newest.","items":{"$ref":"#/components/schemas/TimeSeriesPoint"},"type":"array"},"TopPostsResponse":{"description":"The top posts for the hashtag right now, fetched live on every call.","properties":{"keyword":{"description":"The hashtag, without #.","type":"string"},"posts":{"items":{"properties":{"author":{"description":"The account, where available.","type":["string","null"]},"caption":{"description":"The post's text.","type":"string"},"comments":{"description":"Engagement, where the source has it.","type":["number","null"]},"likes":{"description":"Engagement, where the source has it.","type":["number","null"]},"plays":{"description":"Engagement, where the source has it.","type":["number","null"]},"posted":{"description":"When it was posted.","type":"string"},"rank":{"description":"Position on the hashtag page.","type":"number"},"url":{"description":"Link to the post.","type":"string"}},"type":"object"},"type":"array"},"source":{"description":"tiktok or instagram.","type":"string"}},"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"}},"securitySchemes":{"bearerAuth":{"description":"API key (format `tmcp_live_...`). Get one free at https://socialytics.dev/account","scheme":"bearer","type":"http"}}},"externalDocs":{"description":"API reference","url":"https://socialytics.dev/docs"},"info":{"contact":{"email":"hello@socialytics.dev","name":"Socialytics API Support","url":"https://socialytics.dev"},"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, Pinterest, npm, PyPI, Steam, Google Play, App Store, GitHub, Google Trends, IMDb, Open Library, Polymarket, Reddit, Web, Spotify, Substack, X, Instagram, Bluesky, Hacker News. 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://socialytics.dev/account","summary":"Live trend data across search, social, commerce, news, and developer platforms","termsOfService":"https://socialytics.dev/terms","title":"Socialytics API","version":"1.0.0","x-logo":{"altText":"Socialytics API","url":"https://socialytics.dev/brand/socialytics.dev/logo.png"},"x-mcp-server":"https://api.trendsmcp.ai/mcp"},"openapi":"3.1.0","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":{"get_context":{"summary":"Get Context","value":{"keyword":"nvidia","mode":"get_context","source":"News"}},"get_growth":{"summary":"Get Growth","value":{"keyword":"electric vehicles","mode":"get_growth","percent_growth":["3M","12M"],"source":"Google Search"}},"get_time_series":{"summary":"Get Time Series","value":{"keyword":"electric vehicles","mode":"get_time_series","source":"Google Search"}},"get_top_posts":{"summary":"Get Top Posts","value":{"keyword":"booktok","mode":"get_top_posts","source":"TikTok"}},"get_top_trends":{"summary":"Get Top Trends","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":{"examples":{"get_context":{"summary":"Get Context","value":{"body":"{\"keyword\": \"nintendo switch 2\", \"window_days\": 7, \"count\": 1, \"sources\": [{\"source\": \"YouTube\", \"count\": 1, \"error\": null, \"items\": [{\"kind\": \"video\", \"title\": \"Switch 2 review\", \"url\": \"https://youtube.com/watch?v=\u2026\", \"published\": \"2026-10-22T09:39:22Z\", \"engagement\": {\"views\": 91542, \"likes\": 5997, \"comments\": 527}}]}]}","statusCode":200}},"get_growth":{"summary":"Get Growth","value":{"body":"{\"search_term\": \"nike\", \"data_source\": \"google search\", \"results\": [{\"period\": \"12M\", \"growth\": -12.31, \"direction\": \"decrease\", \"recent_date\": \"2026-10-24\", \"baseline_date\": \"2025-10-25\", \"recent_value\": 57, \"baseline_value\": 65, \"volume_growth\": -12.31}]}","statusCode":200}},"get_time_series":{"summary":"Get Time Series","value":{"body":"[{\"date\": \"2026-10-17\", \"value\": 47, \"volume\": 25853617, \"keyword\": \"bitcoin\", \"source\": \"google search\"}, {\"date\": \"2026-10-24\", \"value\": 52, \"volume\": 28012440, \"keyword\": \"bitcoin\", \"source\": \"google search\"}]","statusCode":200}},"get_top_posts":{"summary":"Get Top Posts","value":{"body":"{\"keyword\": \"booktok\", \"source\": \"tiktok\", \"count\": 1, \"posts\": [{\"rank\": 1, \"caption\": \"5 books that wrecked me\", \"author\": \"readwithme\", \"plays\": 1840221, \"likes\": 220114, \"posted\": \"2026-10-25\", \"url\": \"https://www.tiktok.com/@readwithme/video/\u2026\"}]}","statusCode":200}},"get_top_trends":{"summary":"Get Top Trends","value":{"body":"{\"type\": \"Google Trends\", \"as_of_ts\": \"2026-10-27T12:00:00Z\", \"count\": 3, \"data\": [[1, \"world series\"], [2, \"election polls\"], [3, \"halloween costumes\"]]}","statusCode":200}}},"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"HTTP 200 with the REST envelope. REST answers HTTP 200 with an envelope: `{\"statusCode\": 400, \"body\": \"\u2026\"}`. Read `statusCode`, then parse `body`. A missing or wrong key is the exception: HTTP 401 (`missing_api_key`) or 403 (`invalid_api_key`), with the error object as the body. Errors carry an `error` code and a `message`. Over MCP, a failed call sets `isError` on the tool result."},"401":{"content":{"application/json":{"example":{"error":"missing_api_key","message":"Missing API key. Send it in the Authorization header."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"missing_api_key: No key was sent. Send it in the Authorization header as Bearer <key>. REST answers HTTP 401."},"403":{"content":{"application/json":{"example":{"error":"invalid_api_key","message":"Invalid API key. Check the key in your account."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid_api_key: The key is mistyped or was regenerated. Get or copy your key on /account. REST answers HTTP 403."}},"security":[{"bearerAuth":[]}],"summary":"Query trend data","tags":["trends"]}}},"security":[{"bearerAuth":[]}],"servers":[{"description":"Production","url":"https://api.trendsmcp.ai"}],"tags":[{"description":"Trend data operations","name":"trends"}]}