tiktok-trends-api 1.0.0

package/README.md

@@ -0,0 +1,104 @@
+# tiktok-trends-api
+
+TikTok hashtag volume over time via REST API. Weekly or daily series, period-over-period growth, and live TikTok trending hashtags. No TikTok API approval needed.
+
+**[Get your free API key at trendsmcp.ai](https://trendsmcp.ai)** — 100 requests/month, no credit card.
+
+## Install
+
+```bash
+npm install tiktok-trends-api
+```
+
+## Quick start
+
+```typescript
+import { TrendsMcpClient } from "tiktok-trends-api";
+
+const client = new TrendsMcpClient({ apiKey: "YOUR_API_KEY" });
+
+// 5-year weekly time series
+const series = await client.getTrends({
+  source: "tiktok",
+  keyword: "BookTok",
+});
+console.log(series[0]);
+// { date: "2026-03-28", value: 72, volume: null, keyword: "BookTok", source: "tiktok" }
+
+// Period-over-period growth
+const growth = await client.getGrowth({
+  source: "tiktok",
+  keyword: "BookTok",
+  percent_growth: ["3M", "1Y"],
+});
+console.log(growth.results[0]);
+// { period: "3M", growth: 14.5, direction: "increase", ... }
+
+// What's trending right now
+const trending = await client.getTopTrends({ limit: 10 });
+console.log(trending.data);
+// [[1, "topic one"], [2, "topic two"], ...]
+```
+
+## Methods
+
+### `getTrends(params)`
+
+Returns a historical time series for a keyword. Defaults to 5 years of weekly data. Pass `data_mode: "daily"` for the last 30 days.
+
+### `getGrowth(params)`
+
+Calculates percentage growth between two points in time. Pass preset strings (`"3M"`, `"1Y"`, `"YTD"`, etc.) or custom date pairs.
+
+**Growth presets:** `7D` `14D` `30D` `1M` `2M` `3M` `6M` `9M` `12M` `1Y` `18M` `24M` `2Y` `36M` `3Y` `48M` `60M` `5Y` `MTD` `QTD` `YTD`
+
+### `getTopTrends(params?)`
+
+Returns today's live trending items. Omit `type` to get all feeds at once.
+
+## All supported sources
+
+This package exposes the full `TrendsMcpClient` — all sources work, not just `tiktok`:
+
+| source | Description |
+|---|---|
+| `"google search"` | Google search volume |
+| `"google images"` | Google image search volume |
+| `"google news"` | Google News search volume |
+| `"google shopping"` | Google Shopping search volume |
+| `"youtube"` | YouTube search volume |
+| `"tiktok"` | TikTok hashtag volume |
+| `"reddit"` | Reddit mention volume |
+| `"amazon"` | Amazon product search volume |
+| `"wikipedia"` | Wikipedia page views |
+| `"news volume"` | News article mention volume |
+| `"news sentiment"` | News sentiment score |
+| `"npm"` | npm package weekly downloads |
+| `"steam"` | Steam concurrent players |
+
+## Error handling
+
+```typescript
+import { TrendsMcpClient, TrendsMcpError } from "tiktok-trends-api";
+
+try {
+  const series = await client.getTrends({ source: "tiktok", keyword: "BookTok" });
+} catch (err) {
+  if (err instanceof TrendsMcpError) {
+    console.error(err.status);  // 429
+    console.error(err.code);    // "rate_limited"
+    console.error(err.message);
+  }
+}
+```
+
+## Links
+
+- [API docs](https://trendsmcp.ai/docs)
+- [Get a free API key](https://trendsmcp.ai)
+- [All packages](https://www.npmjs.com/~trendsmcp)
+- [GitHub](https://github.com/trendsmcp/trendsmcp-js)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+export { CustomGrowthPeriod, GetGrowthParams, GetGrowthResponse, GetTopTrendsParams, GetTopTrendsResponse, GetTrendsParams, GetTrendsResponse, GrowthMetadata, GrowthPreset, GrowthResult, TopTrendsFeed, TrendsDataPoint, TrendsMcpClient, TrendsMcpClientOptions, TrendsMcpError, TrendsMcpErrorBody, TrendsSource } from 'trendsmcp';
+
+/** Default source for this package. Pass to `source` in any request. */
+declare const SOURCE: "tiktok";
+
+export { SOURCE };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { CustomGrowthPeriod, GetGrowthParams, GetGrowthResponse, GetTopTrendsParams, GetTopTrendsResponse, GetTrendsParams, GetTrendsResponse, GrowthMetadata, GrowthPreset, GrowthResult, TopTrendsFeed, TrendsDataPoint, TrendsMcpClient, TrendsMcpClientOptions, TrendsMcpError, TrendsMcpErrorBody, TrendsSource } from 'trendsmcp';
+
+/** Default source for this package. Pass to `source` in any request. */
+declare const SOURCE: "tiktok";
+
+export { SOURCE };

package/dist/index.js

@@ -0,0 +1,158 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SOURCE: () => SOURCE,
+  TrendsMcpClient: () => TrendsMcpClient,
+  TrendsMcpError: () => TrendsMcpError
+});
+module.exports = __toCommonJS(index_exports);
+
+// node_modules/trendsmcp/dist/index.mjs
+var TrendsMcpError = class extends Error {
+  constructor(status, body) {
+    var _a;
+    super(body.message);
+    this.name = "TrendsMcpError";
+    this.status = status;
+    this.code = (_a = body.error) != null ? _a : String(status);
+  }
+};
+var BASE_URL = "https://api.trendsmcp.ai/api";
+var TrendsMcpClient = class {
+  constructor(options) {
+    var _a, _b;
+    if (!options.apiKey) {
+      throw new Error(
+        "TrendsMcpClient: apiKey is required. Get a free key at https://trendsmcp.ai"
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (_b = (_a = options.baseUrl) == null ? void 0 : _a.replace(/\/$/, "")) != null ? _b : BASE_URL;
+  }
+  async post(body) {
+    const res = await fetch(this.baseUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    const envelope = await res.json();
+    let parsed;
+    if (envelope !== null && typeof envelope === "object" && typeof envelope.statusCode === "number" && typeof envelope.body === "string") {
+      parsed = JSON.parse(envelope.body);
+      if (envelope.statusCode >= 400) {
+        throw new TrendsMcpError(envelope.statusCode, parsed);
+      }
+    } else {
+      if (!res.ok) {
+        throw new TrendsMcpError(res.status, envelope);
+      }
+      parsed = envelope;
+    }
+    return parsed;
+  }
+  /**
+   * Returns a historical time series for a keyword from a single source.
+   *
+   * Defaults to 5 years of weekly data. Set `data_mode: "daily"` for the
+   * last 30 days at daily granularity.
+   *
+   * @example
+   * const series = await client.getTrends({
+   *   source: "google search",
+   *   keyword: "bitcoin",
+   * });
+   *
+   * @example
+   * const daily = await client.getTrends({
+   *   source: "reddit",
+   *   keyword: "AI agents",
+   *   data_mode: "daily",
+   * });
+   */
+  getTrends(params) {
+    const body = {
+      source: params.source,
+      keyword: params.keyword
+    };
+    if (params.data_mode) body.data_mode = params.data_mode;
+    return this.post(body);
+  }
+  /**
+   * Calculates point-to-point percentage growth for a keyword over one or
+   * more time windows.
+   *
+   * Accepts preset strings ("12M", "YTD", etc.) or custom date pairs.
+   *
+   * @example
+   * const growth = await client.getGrowth({
+   *   source: "google search",
+   *   keyword: "nike",
+   *   percent_growth: ["12M", "3M", "YTD"],
+   * });
+   *
+   * @example
+   * const custom = await client.getGrowth({
+   *   source: "amazon",
+   *   keyword: "air fryer",
+   *   percent_growth: [
+   *     { name: "holiday season", recent: "2025-12-31", baseline: "2025-10-01" }
+   *   ],
+   * });
+   */
+  getGrowth(params) {
+    const body = {
+      source: params.source,
+      keyword: params.keyword,
+      percent_growth: params.percent_growth
+    };
+    if (params.data_mode) body.data_mode = params.data_mode;
+    return this.post(body);
+  }
+  /**
+   * Returns today's top trending items from live platform feeds.
+   * Omit `type` to receive all feeds at once.
+   *
+   * @example
+   * const trending = await client.getTopTrends({ type: "Google Trends", limit: 10 });
+   *
+   * @example
+   * const all = await client.getTopTrends({});
+   */
+  getTopTrends(params = {}) {
+    const body = { mode: "top_trends" };
+    if (params.type) body.type = params.type;
+    if (params.limit) body.limit = params.limit;
+    return this.post(body);
+  }
+};
+
+// src/index.ts
+var SOURCE = "tiktok";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SOURCE,
+  TrendsMcpClient,
+  TrendsMcpError
+});

package/dist/index.mjs

@@ -0,0 +1,129 @@
+// node_modules/trendsmcp/dist/index.mjs
+var TrendsMcpError = class extends Error {
+  constructor(status, body) {
+    var _a;
+    super(body.message);
+    this.name = "TrendsMcpError";
+    this.status = status;
+    this.code = (_a = body.error) != null ? _a : String(status);
+  }
+};
+var BASE_URL = "https://api.trendsmcp.ai/api";
+var TrendsMcpClient = class {
+  constructor(options) {
+    var _a, _b;
+    if (!options.apiKey) {
+      throw new Error(
+        "TrendsMcpClient: apiKey is required. Get a free key at https://trendsmcp.ai"
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (_b = (_a = options.baseUrl) == null ? void 0 : _a.replace(/\/$/, "")) != null ? _b : BASE_URL;
+  }
+  async post(body) {
+    const res = await fetch(this.baseUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    const envelope = await res.json();
+    let parsed;
+    if (envelope !== null && typeof envelope === "object" && typeof envelope.statusCode === "number" && typeof envelope.body === "string") {
+      parsed = JSON.parse(envelope.body);
+      if (envelope.statusCode >= 400) {
+        throw new TrendsMcpError(envelope.statusCode, parsed);
+      }
+    } else {
+      if (!res.ok) {
+        throw new TrendsMcpError(res.status, envelope);
+      }
+      parsed = envelope;
+    }
+    return parsed;
+  }
+  /**
+   * Returns a historical time series for a keyword from a single source.
+   *
+   * Defaults to 5 years of weekly data. Set `data_mode: "daily"` for the
+   * last 30 days at daily granularity.
+   *
+   * @example
+   * const series = await client.getTrends({
+   *   source: "google search",
+   *   keyword: "bitcoin",
+   * });
+   *
+   * @example
+   * const daily = await client.getTrends({
+   *   source: "reddit",
+   *   keyword: "AI agents",
+   *   data_mode: "daily",
+   * });
+   */
+  getTrends(params) {
+    const body = {
+      source: params.source,
+      keyword: params.keyword
+    };
+    if (params.data_mode) body.data_mode = params.data_mode;
+    return this.post(body);
+  }
+  /**
+   * Calculates point-to-point percentage growth for a keyword over one or
+   * more time windows.
+   *
+   * Accepts preset strings ("12M", "YTD", etc.) or custom date pairs.
+   *
+   * @example
+   * const growth = await client.getGrowth({
+   *   source: "google search",
+   *   keyword: "nike",
+   *   percent_growth: ["12M", "3M", "YTD"],
+   * });
+   *
+   * @example
+   * const custom = await client.getGrowth({
+   *   source: "amazon",
+   *   keyword: "air fryer",
+   *   percent_growth: [
+   *     { name: "holiday season", recent: "2025-12-31", baseline: "2025-10-01" }
+   *   ],
+   * });
+   */
+  getGrowth(params) {
+    const body = {
+      source: params.source,
+      keyword: params.keyword,
+      percent_growth: params.percent_growth
+    };
+    if (params.data_mode) body.data_mode = params.data_mode;
+    return this.post(body);
+  }
+  /**
+   * Returns today's top trending items from live platform feeds.
+   * Omit `type` to receive all feeds at once.
+   *
+   * @example
+   * const trending = await client.getTopTrends({ type: "Google Trends", limit: 10 });
+   *
+   * @example
+   * const all = await client.getTopTrends({});
+   */
+  getTopTrends(params = {}) {
+    const body = { mode: "top_trends" };
+    if (params.type) body.type = params.type;
+    if (params.limit) body.limit = params.limit;
+    return this.post(body);
+  }
+};
+
+// src/index.ts
+var SOURCE = "tiktok";
+export {
+  SOURCE,
+  TrendsMcpClient,
+  TrendsMcpError
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "tiktok-trends-api",
+  "version": "1.0.0",
+  "description": "TikTok hashtag volume over time via REST API. Weekly or daily series, period-over-period growth, and live TikTok trending hashtags. No TikTok API approval needed. Powered by trendsmcp.ai",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "tiktok",
+    "tiktok-api",
+    "tiktok-trends",
+    "hashtag-volume",
+    "trend-data",
+    "social-media",
+    "analytics",
+    "growth-rate",
+    "viral",
+    "trendsmcp"
+  ],
+  "author": "Trends MCP",
+  "license": "MIT",
+  "homepage": "https://trendsmcp.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trendsmcp/trendsmcp-js"
+  },
+  "bugs": {
+    "url": "https://github.com/trendsmcp/trendsmcp-js/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "trendsmcp": "^1.0.0"
+  }
+}