trendsmcp

JavaScript/TypeScript client for the Trends MCP API. Query keyword trend time series and growth percentages across Google Search, YouTube, Reddit, Amazon, TikTok, Wikipedia, npm, Steam, app downloads, and more — all from a single endpoint.

Get your free API key at trendsmcp.ai — 100 requests/month, no credit card.

Install

npm install trendsmcp

Quick start

import { TrendsMcpClient } from "trendsmcp";

const client = new TrendsMcpClient({ apiKey: "YOUR_API_KEY" });

// ~5 years of weekly time series
const series = await client.getTimeSeries({
  source: "google search",
  keyword: "bitcoin",
});
console.log(series[0]);
// { date: "2026-03-21", value: 47, volume: 25853617, keyword: "bitcoin", source: "google search" }

// Period-over-period growth
const growth = await client.getGrowth({
  source: "google search",
  keyword: "nike",
  percent_growth: ["12M", "3M", "YTD"],
});
console.log(growth.results[0]);
// { period: "12M", growth: -12.31, direction: "decrease", ... }

// What's trending right now
const trending = await client.getTopTrends({ type: "Google Trends", limit: 10 });
console.log(trending.data);
// [[1, "chuck norris"], [2, "project hail mary"], ...]

Methods

getTimeSeries(params) / getTrends(params)

Returns ~5 years of weekly historical data for one source + keyword. REST mode: get_time_series (get_trends is an accepted alias). Prefer getTimeSeries in new code.

getGrowth(params)

Calculates percentage growth between two points in time. Pass preset strings ("3M", "1Y", "YTD", etc.) or custom date pairs. Omitting percent_growth defaults to ["12M"].

Growth presets: 7D 14D 30D 1M 2M 3M 6M 9M 12M 1Y 18M 24M 2Y 36M 3Y 48M 60M 5Y MTD QTD YTD

Custom date range:

const custom = await client.getGrowth({
  source: "amazon",
  keyword: "air fryer",
  percent_growth: [
    { name: "holiday lift", recent: "2025-12-31", baseline: "2025-10-01" }
  ],
});

getTopTrends(params?)

Returns today's live trending items. Omit type to get all feeds at once. Supports optional category, limit (default 25), and offset.

Available feeds: Google Trends Google News Top News YouTube Trending TikTok Trending Hashtags TikTok Trending Searches TikTok Shop Hot Products X (Twitter) Trending Reddit Hot Posts Reddit World News Wikipedia Trending Amazon Best Sellers Top Rated Amazon Best Sellers by Category App Store Top Free App Store Top Paid Google Play Top Websites Spotify Top Podcasts Steam Most Played GitHub Trending Repos IMDb MOVIEmeter Open Library Trending Books

Data sources

| source | Description | Keyword format | |---|---|---| | "google search" | Google search volume | Any keyword or phrase | | "google images" | Google image search volume | Any keyword or phrase | | "google news" | Google News search volume | Any keyword or phrase | | "google shopping" | Google Shopping search volume | Any keyword or phrase | | "youtube" | YouTube search volume | Any keyword or phrase | | "tiktok" | TikTok hashtag volume | Hashtag or topic | | "reddit" | Subreddit subscribers | Subreddit name only, no r/ prefix | | "amazon" | Amazon product search volume | Product name or category | | "wikipedia" | Wikipedia page views | Article title or topic | | "news volume" | News article mention volume | Any keyword or phrase | | "news sentiment" | News sentiment score | Any keyword or phrase | | "app downloads" | Android app downloads (AppBrain) | Bundle ID e.g. com.openai.chatgpt | | "app rankings" | Android app store rankings (AppBrain) | Bundle ID e.g. com.himshers.hims | | "npm" | npm package weekly downloads | Exact package name, case-sensitive | | "steam" | Steam concurrent players | Game display name e.g. Elden Ring |

All values normalized 0–100 where the pipeline supports it.

Error handling

import { TrendsMcpClient, TrendsMcpError } from "trendsmcp";

try {
  const series = await client.getTimeSeries({ source: "google search", keyword: "bitcoin" });
} catch (err) {
  if (err instanceof TrendsMcpError) {
    console.error(err.status);  // 429
    console.error(err.code);    // "rate_limited"
    console.error(err.message);
  }
}

TypeScript

Full types included. No @types package needed.

Links

• API docs
• Get a free API key
• All packages
• GitHub

License

MIT