Six of the 27 get_top_trends boards accept a category parameter. The other 21 take none, per the catalog. This tutorial calls all six live in Python on 2026-11-17. Passing category Technology to Google Trends by Category returned 10 rows, all tagged Technology, with outlook outage at rank 1. The same call without a category returned 10 rows across 10 different categories, every row at rank 1. The other boards answered with the same shape, on different snapshots: Pinterest Food and Drink led with pumpkin, Substack Technology with Ahead of AI, Top Websites finance with paypal.com. A wrong name fails with invalid_request and the full valid list. The helper below sends each call, parses the response body twice, and prints the real responses.
Six boards take a category, the other 21 do not
Only 6 of the 27 get_top_trends boards accept a category parameter, as of 2026-11-17. The other 21 take no category parameter, per the catalog. The six are listed below with the category count each one returned live on 2026-11-17.
| Board | Categories | Board updates |
|---|---|---|
| Google Trends by Category | 19 | Live |
| TikTok Trending Hashtags by Category | 79 | Daily |
| Amazon Best Sellers by Category | 26 | Daily |
| Pinterest Trending by Category | 21 | Live |
| Substack by Category | 34 | Daily |
| Top Websites | 91 paths | Monthly |
The counts came from the error message each board returns for an unknown category, read live on 2026-11-17. The Substack gap shows why the live list matters: the catalog lists 31, the error lists 34. Top Websites lists 91 paths, including hierarchical ones such as arts-and-entertainment and arts-and-entertainment/animation-and-comics. The full board catalog lives on the data catalog.
One helper sends the request and parses the body twice
One helper sends the board calls in this tutorial, and the helper parses the response twice. The REST endpoint answered HTTP 200 in the raw call in this run, with an envelope of two fields, statusCode and body. The body field holds text rather than an object, so a second json.loads call turns it into the board data. The raw call in this run returned outer keys body and statusCode, and body had the type str.
import json
import os
import requests
URL = "https://api.trendsmcp.ai/api"
KEY = os.environ["TMCP_API_KEY"]
def board(board_type, category=None, limit=10):
payload = {"mode": "get_top_trends", "type": board_type, "limit": limit}
if category:
payload["category"] = category
resp = requests.post(
URL,
headers={"Authorization": "Bearer " + KEY, "Content-Type": "application/json"},
json=payload,
timeout=30,
)
outer = resp.json()
return json.loads(outer["body"])
The key comes from the environment, never from the code. Setup for the key lives in the docs. The call below ran live on 2026-11-17 and returned 10 rows from the Technology board. The print shows the count, the snapshot time, and the first three rows.
tech = board("Google Trends by Category", category="Technology", limit=10)
print(tech["count"])
print(tech["as_of_ts"])
print(tech["data"][:3])
10
2026-11-17T05:01:37.375716+00:00
[[1, "outlook outage", "Technology"], [2, "apple home view", "Technology"], [3, "gta 6 price", "Technology"]]
Each row is a list of rank, keyword and category path. The response also carries requests_charged, which read 1 on every successful call in this run. The limit accepts 1 to 200 rows, per the cost note in the live Pinterest, Substack and Top Websites responses read on 2026-11-17. The same note charges 1 request per 10 rows, so larger limits cost more than the 1 request charged at limit 5 or 10, and the API default is 100 while the helper defaults to 10.
Category on: 10 rows, one topic. Category off: 10 rows, 10 topics
The category parameter changes what the board returns, not how many rows it returns. With category Technology and limit 10, the board returned 10 rows, all tagged Technology, as of 2026-11-17T05:01:37Z.
- outlook outage
- apple home view
- gta 6 price
- xbox playback
- workday outage
- nintendo black friday
- ast spacemobile at&t verizon partnership
- zelda ocarina of time remake sales
- iphone hacked
- nintendo eshop philippines
The same board with no category and the same limit returned 10 rows across 10 distinct categories: Autos and Vehicles, Climate, Food and Drink, Hobbies and Leisure, Jobs and Education, Pets and Animals, Politics, Shopping, Technology, and Travel and Transportation. Every one of those rows sat at rank 1. The pattern suggests the unscoped board merges the top row of each category board instead of ranking across categories. That reading is inference from the 10 rank 1 rows, not a stated rule. That is consistent with the unscoped board showing one leader per category, but it is inference, not a stated rule.
TikTok Food is not Google Food
Category names are board specific, so copy the name from the board being called. TikTok Trending Hashtags by Category with category Food returned 5 hashtags on 2026-11-17, all tagged Food: candy, fruit, traderjoes, fruits, groceryshopping. Amazon Best Sellers by Category with category Books returned 5 books, all tagged Books.
- Paint by Sticker Kids (Official): Christmas: Create 10 Pictures One Sticker at a Time! Includes Glitter Stickers
- Dog Man: A Sprinkle in Time: A Graphic Novel (Dog Man #15): From the Creator of Captain Underpants (15)
- Rudolph the Red-Nosed Reindeer (Rudolph the Red-Nosed Reindeer) (Little Golden Book)
- Theo of Golden: A Novel
- How the Grinch Stole Christmas! Full Color Edition (Classic Seuss)
The two boards do not share a snapshot time. The TikTok board read 2026-11-17T05:01:37Z, the same minute as the Google board. The Amazon board read 2026-11-16T05:01:36Z, a day earlier. Amazon boards update daily, so a one-day-old snapshot fits the cadence. A Books rank from that call answers Monday, not today. Names also differ between boards: Google has no category named Food; its list uses Food and Drink instead. A name that works on one board is no promise it works on another.
Three more boards take the same parameter
The same category parameter scopes Pinterest, Substack and Top Websites, and all three answered on 2026-11-17 with 1 request charged each. Pinterest Trending by Category with category Food and Drink returned 5 searches, all tagged Food and Drink: pumpkin, crockpot meals, soup recipes, banana bread recipe, soup. Substack by Category with category Technology returned 5 newsletters, all tagged Technology: Ahead of AI, AI blew my mind, Marcus on AI, Effluvia, The Sunday Signal. Top Websites with category finance returned 5 sites, all tagged finance: paypal.com, tradingview.com, chase.com, capitalone.com, citi.com.
The snapshot times show what as_of_ts means. Pinterest read 2026-11-17T10:10:28Z, hours after the 05:01 snapshot shared by Google, TikTok and Substack, which fits the live cadence in the catalog. Top Websites read 2026-11-02T05:01:39Z, 15 days earlier, which fits the monthly cadence in the catalog. The timestamp marks the board snapshot, not the moment of the call.
A wrong name on the Google board fails loudly and lists every valid name
A misspelled category on the Google board returned no rows at all. The call fails with invalid_request and the full valid list. Calling the Google board with category Tech returned this error on 2026-11-17: invalid_request, Unknown category 'Tech'. Valid categories: Autos and Vehicles, Beauty and Fashion, Business and Finance, Climate, Entertainment, Food and Drink, Games, Health, Hobbies and Leisure, Jobs and Education, Law and Government, Other, Pets and Animals, Politics, Science, Shopping, Sports, Technology, Travel and Transportation. That is all 19 names, in one message.
Lowercase technology worked, and the response echoed the canonical name Technology, so matching is case insensitive. Failed calls are free, per the catalog dated 2026-11-01, and the Google error response in this run carried no requests_charged field. On the Google board, a bad-name call lists the categories at no request cost. The live error is also the check to run when a category name from an old catalog stops working, as the Substack count showed.
Categories scope boards only, not keyword calls
The category parameter belongs to get_top_trends boards. The keyword tools, get_time_series, get_growth and get_context, take a keyword and a source and no category, per their parameter tables in the catalog. To scope a series by topic, pick the keyword. One call takes one category, so loop over the list for more categories. Each successful call in this run charged 1 request whether or not a category was passed. Request pools live on pricing. For a worked example of one keyword read across several sources instead, see collagen peptides product signals in Python.