Trendsapi Js

Official JS/TS client for Trends API. Node 18+, Deno, Bun, Workers. Zero runtime dependencies. Three methods. Decoded payloads. You never parse the HTTP body string.

HTTP contract and field tables: trendsapi-ai/trendsapi.

License: MIT npm Runtime

Authentication

npm install trendsapi
export TRENDSAPI_KEY=your_key

Key: trendsapi.ai/#get-key (100 calls/month on free).

import { TrendsAPI } from "trendsapi";

const client = new TrendsAPI({ apiKey: process.env.TRENDSAPI_KEY! });

Methods

Method	REST mode	Required	Returns
getTimeSeries	get_time_series	source, keyword	weekly points
getGrowth	get_growth	source, keyword	growth object
getTopTrends	get_top_trends	type	live feed

const series = await client.getTimeSeries({ source: "youtube", keyword: "air fryer" });
const growth = await client.getGrowth({
  source: "google shopping",
  keyword: "air fryer",
  percentGrowth: ["3M", "12M"],
});
const chart = await client.getTopTrends({ type: "App Store Top Free", limit: 25 });

Typed source and type are separate unions. source: "Google Trends" is a type error (and a 400 on raw POST).

getTimeSeries

const points = await client.getTimeSeries({ source: "google search", keyword: "bitcoin" });

Field	Always	Meaning
date	yes	YYYY-MM-DD
value	yes	0-100 index
keyword	yes	Echo
volume	no	Absolute volume when available
source or datatype	no	Pipeline label

getGrowth

const g = await client.getGrowth({
  source: "google search",
  keyword: "nike",
  percentGrowth: ["12M", "3M", "YTD"],
});

Default window: ["12M"]. Presets: 7D 14D 30D 1M 2M 3M 6M 9M 12M/1Y 18M 24M/2Y 36M/3Y 48M 60M/5Y MTD QTD YTD. Custom: { name: "Launch", recent: "2024-06-01", baseline: "2024-01-01" }.

Field	Meaning
search_term	Keyword
data_source	Source
results	Per-window growth, direction, dates, values
metadata	Counts / success flag

getTopTrends

const hot = await client.getTopTrends({ type: "GitHub Trending Repos", limit: 5 });

Field	Meaning
as_of_ts	Snapshot time
type	Feed name
limit, offset, count	Pagination
data	[rank, label] rows

Optional offset, category (Amazon Best Sellers by Category, Top Websites only).

Keyword sources

Pass as source. Details: hub README.

source	keyword
google search, google images, google news, google shopping	Any phrase
youtube	Any phrase
tiktok	Hashtag or topic
reddit	Subreddit, no r/
amazon	Product phrase
wikipedia	Article title
news volume, news sentiment	Any phrase
app downloads, app rankings	Android bundle ID (com.openai.chatgpt)
npm	Exact package name
steam	Game display name

Live feeds

Pass as type. Exact strings: Google Trends, Google News Top News, TikTok Trending Hashtags, TikTok Trending Searches, TikTok Shop Hot Products, YouTube Trending, 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.

Next.js / Workers

Uses global fetch. Bind TRENDSAPI_KEY as a secret.

import { TrendsAPI } from "trendsapi";

export async function GET(req: Request) {
  const keyword = new URL(req.url).searchParams.get("q") ?? "air fryer";
  const client = new TrendsAPI({ apiKey: process.env.TRENDSAPI_KEY! });
  const [search, shopping, video] = await Promise.all([
    client.getGrowth({ source: "google search", keyword, percentGrowth: ["12M"] }),
    client.getGrowth({ source: "google shopping", keyword, percentGrowth: ["12M"] }),
    client.getGrowth({ source: "youtube", keyword, percentGrowth: ["12M"] }),
  ]);
  return Response.json({ keyword, search, shopping, video });
}

Three 200s, three quota units.

export default {
  async fetch(_req: Request, env: { TRENDSAPI_KEY: string }) {
    const client = new TrendsAPI({ apiKey: env.TRENDSAPI_KEY });
    return Response.json(await client.getTopTrends({ type: "GitHub Trending Repos", limit: 5 }));
  },
};

import type { TimeSeriesPoint, GrowthResponse, TopTrendsResponse } from "trendsapi";

Errors

Code	Client
200	Resolves parsed payload
400	Throws. Fix field names
401	Throws. Check TRENDSAPI_KEY
404	Throws. No series. Do not retry
429	Throws. Quota
5xx	Retries, then throws

Raw fetch (second parse required): hub, Raw HTTP.

License

MIT. See LICENSE.