{
  "markdown": "# TikTok hashtag volume API\n\nTikTok hashtag and search interest trends via the Trends API. History, growth, and live trending hashtags.\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/trendsapi-tiktok.svg)](https://pypi.org/project/trendsapi-tiktok/)\n[![Python](https://img.shields.io/badge/python-3.9%2B-yellow.svg)](https://trendsapi.ai)\n[![npm](https://img.shields.io/npm/v/trendsapi-tiktok.svg)](https://www.npmjs.com/package/trendsapi-tiktok)\n\nKey: [trendsapi.ai/#get-key](https://trendsapi.ai/#get-key). HTTP contract and every source: [trendsapi-ai/trendsapi](https://github.com/trendsapi-ai/trendsapi).\n\n## Authentication\n\n```bash\npip install trendsapi-tiktok\nexport TRENDSAPI_KEY=your_key\n```\n\nPython 3.9+. Same key as the HTTP API.\n\n```python\nfrom trendsapi_tiktok import TrendsAPI\n\nclient = TrendsAPI()                    # TRENDSAPI_KEY\n# client = TrendsAPI(api_key=\"YOUR_KEY\")\n```\n\nKeyword helpers default to `source: \"tiktok\"`. Pass `source=` to hit any other platform with the same client. Official full client (every source, no preset): [`trendsapi`](https://pypi.org/project/trendsapi/).\n\n## Methods\n\n| Method | REST `mode` | Returns |\n|---|---|---|\n| `get_time_series(keyword, source=, data_mode=)` | `get_time_series` | `list[TrendsDataPoint]` |\n| `get_growth(keyword, percent_growth=, source=, data_mode=)` | `get_growth` | `GetGrowthResponse` |\n| `get_live(limit=, offset=, category=)` | `get_top_trends` | `GetTopTrendsResponse` |\n| `get_top_trends(type=, ...)` | `get_top_trends` | `GetTopTrendsResponse` |\n\n`source` is lowercase (`tiktok`). `type` is exact (`TikTok Trending Hashtags`). Mixing them is a 400.\n\n```python\nfrom trendsapi_tiktok import TrendsAPI\n\nclient = TrendsAPI()                    # TRENDSAPI_KEY\n# client = TrendsAPI(api_key=\"YOUR_KEY\")\n\nseries = client.get_time_series(\"matcha\")\nprint(series[-1].date, series[-1].value)\n\ngrowth = client.get_growth(\"matcha\", percent_growth=[\"3M\", \"12M\"])\nprint(growth.results[0].growth, growth.results[0].direction)\n\nhot = client.get_live(limit=10)\nprint(hot.data)                         # [[1, \"...\"], ...]\n```\n\n## get_time_series\n\n```python\npoints = client.get_time_series(\"matcha\")\n```\n\nEach point:\n\n| Field | Always | Meaning |\n|---|---|---|\n| `date` | yes | `YYYY-MM-DD` |\n| `value` | yes | 0-100 index for this series |\n| `keyword` | yes | Echo |\n| `volume` | no | Absolute volume when available |\n| `source` or `datatype` | no | Pipeline label |\n\nPython returns `list[TrendsDataPoint]`. Use `.date` and `.value`, not `[\"date\"]`.\nJS returns the same fields as object properties.\n\n## get_growth\n\n```python\ng = client.get_growth(\"matcha\", percent_growth=[\"12M\", \"3M\", \"YTD\"])\nprint(g.results[0].growth, g.results[0].direction)\n```\n\n`percent_growth` default: `[\"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\"}`.\n\n| Field | Meaning |\n|---|---|\n| `search_term` | Keyword |\n| `data_source` | Source |\n| `results` | One object per window (`period`, `growth`, `direction`, dates, values) |\n| `metadata` | Counts / success flag |\n\nSeveral windows still count as one request. Python: `growth.results[0].growth`. JS: `growth.results[0].growth`.\n\n\n## get_live\n\n```python\nhot = client.get_live(limit=10)\n```\n\n| Field | Meaning |\n|---|---|\n| `as_of_ts` | Snapshot time |\n| `type` | Feed name |\n| `limit`, `offset`, `count` | Pagination |\n| `data` | `[rank, label]` rows |\n\nPython: `hot.data`. JS: `hot.data`. Optional `offset=` and `category=` (`Amazon Best Sellers by Category`, `Top Websites` only).\n\n\n## Async\n\n```python\nimport asyncio\nfrom trendsapi_tiktok import AsyncTrendsAPI\n\nasync def main():\n    c = AsyncTrendsAPI()\n    return await asyncio.gather(\n        c.get_time_series(\"matcha\"),\n        c.get_time_series(\"matcha\", source=\"google search\"),\n    )\n\nasyncio.run(main())\n```\n\nEach 200 is one billed request.\n\n## Pandas\n\n```python\nfrom dataclasses import asdict\nimport pandas as pd\nfrom trendsapi_tiktok import TrendsAPI\n\ndf = pd.DataFrame(asdict(p) for p in TrendsAPI().get_time_series(\"matcha\"))\ndf[\"date\"] = pd.to_datetime(df[\"date\"])\nprint(df.set_index(\"date\")[\"value\"].resample(\"ME\").mean().tail())\n```\n\n## JavaScript / TypeScript\n\n```bash\nnpm install trendsapi-tiktok\n```\n\nNode 18+, Deno, Bun, Workers. Same API key. Field tables above apply.\n\n### Methods\n\n| Method | REST `mode` | Returns |\n|---|---|---|\n| `getTimeSeries(keyword, { source, data_mode })` | `get_time_series` | weekly points |\n| `getGrowth(keyword, { percent_growth, source, data_mode })` | `get_growth` | growth object |\n| `getLive({ limit, offset, category })` | `get_top_trends` | live feed |\n| `getTopTrends({ type, ... })` | `get_top_trends` | live feed |\n\n```ts\nimport { TrendsAPI } from \"trendsapi-tiktok\";\n\nconst client = new TrendsAPI({ apiKey: process.env.TRENDSAPI_KEY! });\nconst series = await client.getTimeSeries(\"matcha\");\nconsole.log(series.at(-1)?.date, series.at(-1)?.value);\n\nconst growth = await client.getGrowth(\"matcha\", {\n  percent_growth: [\"3M\", \"12M\"],\n});\nconsole.log(growth.results[0].growth, growth.results[0].direction);\n\nconst live = await client.getLive({ limit: 10 });\nconsole.log(live.data);                 // [[1, \"...\"], ...]\n```\n\n## Call (curl)\n\n| Field | Value |\n|---|---|\n| Endpoint | `POST https://api.trendsapi.ai/api` |\n| Auth | `Authorization: Bearer $TRENDSAPI_KEY` |\n| History | `source: tiktok` with `get_time_series` or `get_growth` |\n| Keyword | Hashtag or topic, e.g. matcha (`#` optional) |\n| Live `type` | TikTok Trending Hashtags, TikTok Trending Searches, TikTok Shop Hot Products |\n\n```bash\ncurl -sS -X POST https://api.trendsapi.ai/api \\\n  -H \"Authorization: Bearer $TRENDSAPI_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mode\":\"get_time_series\",\"source\":\"tiktok\",\"keyword\":\"matcha\"}'\n```\n\n## Source notes\n\n- `value` is 0-100 for this hashtag, not view count.\n- `tiktok trending hashtags` (wrong case) is 400.\n- Publishing videos still requires TikTok's own APIs. This endpoint is demand only.\n\n## Errors\n\n| HTTP | Client |\n|---|---|\n| 200 | Parsed payload. Python dataclasses / JS typed objects |\n| 400 | Raises. Fix `source` or `type` spelling |\n| 401 | Raises. Check `TRENDSAPI_KEY` |\n| 404 | Raises. No series for that keyword. Do not retry |\n| 429 | Raises. Quota |\n| 5xx | Client retries, then raises |\n\nThe HTTP `body` field is a JSON string. SDKs decode it. Raw curl must parse `body` a second time.\n\nSite: [https://trendsapi.ai/trends/tiktok-trends](https://trendsapi.ai/trends/tiktok-trends).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 6702,
  "sha": "9dd98bf03634c00ea6bf6bb5e40f614fb9808575282913221cf309dc0904bcd3",
  "repo_slug": "trendsapi-ai/tiktok-trends-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_trendsapi_tiktok_8a6641d2/readme"
}