Twitter 趋势 API：按 WOEID 获取 X 趋势

#Twitter 趋势 API 的工作方式

趋势 API 接收一个地区，返回 X 对该地区此刻热门话题的排名列表，与未登录用户在探索页看到的列表相同。地区以 WOEID（Where On Earth ID）传入：这是雅虎旧地理数据库里的数字位置代码，被 X 沿用至今。1 代表全球，23424977 是美国，2459115 是纽约。

本指南用代码完成这项工作，适用于 X 覆盖的任何地区和任意数量的地区。

X 自己的接口 GET /2/trends/by/woeid/{woeid} 于 2023 年 12 月 8 日加入官方 X API 的 v2（见 X 的更新日志（在新标签页打开）），到 2026 年 11 月仍可使用。按量付费下，每次请求 $0.010，从预付额度中扣除（见 X 的价目表（在新标签页打开））。下表汇总了 X 参考文档（在新标签页打开）的其余内容，核对日期为 2026 年 11 月 2 日。

• 接口

  官方 X API

  GET /2/trends/by/woeid/{woeid}

• 访问方式

  官方 X API

  通过审核的开发者账号、一个 Project 和 App、该 App 的 Bearer 令牌

• 每次调用的趋势数

  官方 X API

  默认 20 条，用 max_trends 最多 50 条

• 字段

  官方 X API

  trend_name，需要时另有 tweet_count

• 价格

  官方 X API

  每次请求 $0.010

• 速率限制

  官方 X API

  每个应用每 15 分钟 75 次请求

有两样东西它没有。X 目前的文档里没有哪个接口能列出有趋势的地区：旧的 v1.1 trends/available 调用已从文档中消失。也没有任何调用返回过去的列表，所以趋势历史只能靠你自己存下快照。

#用 Sorsa API 获取任意地区的趋势

要不用开发者账号、在代码里获取趋势列表，用 Sorsa API，一款 Twitter（X）API 与爬虫：GET /trends 接收同样的 WOEID，一次请求就返回 X 在该地区的列表，每 1,000 份 $1.40 起，官方 X API 则是 $10.00，所有套餐统一每秒 20 次请求。

1. 获取密钥。 注册并从控制台复制 API 密钥。100 次免费请求已经在上面，无需绑卡。

2. 选好地区。 在下面的查找器里找到它的 WOEID，或者用 1 代表全球。

3. 发送请求。 调用 GET /trends（在新标签页打开），查询字符串里带 woeid，密钥放在 ApiKey 请求头里。

   curl "https://api.sorsa.io/v3/trends?woeid=23424900" \
     -H "ApiKey: YOUR_API_KEY"
   

   {
     "trends": [
       {
         "name": "#FelizLunes",
         "query": "%23FelizLunes",
         "url": "https://x.com/search?q=%23FelizLunes"
       },
       {
         "name": "Liga MX",
         "query": "%22Liga+MX%22",
         "url": "https://x.com/search?q=%22Liga+MX%22"
       },
       {
         "name": "Buenos días",
         "query": "%22Buenos+d%C3%ADas%22",
         "url": "https://x.com/search?q=%22Buenos+d%C3%ADas%22"
       }
     ]
   }
   

   显示完整响应

4. 读取列表。 每个趋势都有 name（X 显示的话题名）、query（背后的搜索）和 url（它在 X 上的搜索页）。顺序就是 X 的排名，所以第一项是最热的趋势。

返回 403 表示密钥缺失或请求次数用完，返回 401 表示密钥错误。返回 429 表示一秒内超过了 20 次请求：等一秒再发。失败的请求从不收费，每次调用返回的都是最新数据，所以间隔一小时的两次调用会得到两份不同的快照。

#查找任意国家或城市的 WOEID

X 为 467 个地区发布趋势列表：全球、62 个国家和 404 个城市，每个都有自己的 WOEID（见 X 的趋势地区列表（在新标签页打开），2025 年 8 月再次从 X 获取时没有变化）。其中每一个都能用于 GET /trends。不在列表里的城镇没有自己的趋势，所以请用最近的已列出城市，或者所在国家。

下表列出大家问得最多的国家，各配一个主要城市；下面的查找器里有全部 467 个地区。

• 全球

  WOEID

  1

  主要城市

  —

  城市 WOEID

  —

• 美国

  WOEID

  23424977

  主要城市

  纽约

  城市 WOEID

  2459115

• 墨西哥

  WOEID

  23424900

  主要城市

  墨西哥城

  城市 WOEID

  116545

• 印度

  WOEID

  23424848

  主要城市

  孟买

  城市 WOEID

  2295411

• 日本

  WOEID

  23424856

  主要城市

  东京

  城市 WOEID

  1118370

• 英国

  WOEID

  23424975

  主要城市

  伦敦

  城市 WOEID

  44418

• 巴西

  WOEID

  23424768

  主要城市

  圣保罗

  城市 WOEID

  455827

• 印度尼西亚

  WOEID

  23424846

  主要城市

  雅加达

  城市 WOEID

  1047378

• 土耳其

  WOEID

  23424969

  主要城市

  伊斯坦布尔

  城市 WOEID

  2344116

• 西班牙

  WOEID

  23424950

  主要城市

  马德里

  城市 WOEID

  766273

• 澳大利亚

  WOEID

  23424748

  主要城市

  悉尼

  城市 WOEID

  1105779

• 韩国

  WOEID

  23424868

  主要城市

  首尔

  城市 WOEID

  1132599

墨西哥除全国列表 23424900 外，还有 23 个趋势城市：墨西哥城是 116545，瓜达拉哈拉是 124162，蒙特雷是 134047。在查找器里输入任意地区，或你在别处找到的 WOEID，就能核对并复制请求。

须知

网上流传的 WOEID 表常常把相邻的代码弄混：23424868 是韩国，不是墨西哥（23424900）；23424775 是加拿大，不是澳大利亚（23424748）；455825 是里约热内卢，不是圣保罗（455827）；1105779 是悉尼，不是东京（1118370）。错误的代码仍会返回有效的列表，只是属于另一个地区，所以保存之前先核对名称。

各地城市覆盖不均。美国有 63 个趋势城市，英国 26 个，墨西哥 23 个，而 62 个国家中有 9 个只有全国列表，比利时、丹麦和葡萄牙就在其中。X 没有州或地区的列表。

#获取每个趋势背后的帖子

趋势的 query 本身就是一个现成的搜索：把它发给 POST /search-tweets（在新标签页打开），Sorsa API 就会返回该趋势背后的帖子，每次请求约 20 条，每条都带有作者的完整资料。"order": "popular" 返回 X 排为热门（Top）的帖子；"latest" 则最新的在前。

下面的脚本读取墨西哥的列表，并为前五个趋势各打印三条热门帖子。代码会先把 URL 编码的 query 解码，再放进搜索里。

import requests
from urllib.parse import unquote_plus

API = "https://api.sorsa.io/v3"
HEADERS = {"ApiKey": "YOUR_API_KEY"}
MEXICO = 23424900

def get_trends(woeid):
    r = requests.get(f"{API}/trends", params={"woeid": woeid},
                     headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()["trends"]

def top_posts(query):
    body = {"query": query, "order": "popular"}
    r = requests.post(f"{API}/search-tweets", json=body,
                      headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()["tweets"]

for rank, trend in enumerate(get_trends(MEXICO)[:5], start=1):
    query = trend["query"]
    if "%" in query:  # decode a URL-encoded search
        query = unquote_plus(query)
    print(f"{rank}. {trend['name']}")
    for post in top_posts(query)[:3]:
        user = post["user"]["username"]
        print(f"   @{user}: {post['likes_count']} likes")

// Node.js 18+, saved as trends.mjs
const API = "https://api.sorsa.io/v3";
const HEADERS = { ApiKey: "YOUR_API_KEY" };

async function getTrends(woeid) {
  const url = `${API}/trends?woeid=${woeid}`;
  const res = await fetch(url, { headers: HEADERS });
  if (!res.ok) throw new Error(`trends: ${res.status}`);
  return (await res.json()).trends;
}

async function topPosts(query) {
  const res = await fetch(`${API}/search-tweets`, {
    method: "POST",
    headers: { ...HEADERS, "Content-Type": "application/json" },
    body: JSON.stringify({ query, order: "popular" }),
  });
  if (!res.ok) throw new Error(`search: ${res.status}`);
  return (await res.json()).tweets;
}

const trends = (await getTrends(23424900)).slice(0, 5);
for (const [i, trend] of trends.entries()) {
  const query = trend.query.includes("%")
    ? decodeURIComponent(trend.query.replace(/\+/g, " "))
    : trend.query;
  console.log(`${i + 1}. ${trend.name}`);
  for (const post of (await topPosts(query)).slice(0, 3)) {
    console.log(`   @${post.user.username}: ${post.likes_count} likes`);
  }
}

在官方 X API 上，趋势这项工作贵就贵在帖子上。每条帖子 $0.005，而且从 2026 年 11 月 22 日起，每条帖子的作者还要按 $0.010 的用户读取另外计费（见 X 的通知（在新标签页打开）），所以 1,000 条帖子连同作者要 $15.00。要获取趋势背后的帖子，用 Sorsa API：每 1,000 条结果 $0.07 起，作者资料已包含在内。

要按语言、日期或点赞数缩小趋势帖子的范围，可以在 query 里加上 X 运算符；Twitter 搜索 API指南讲了翻页，Twitter 搜索运算符列表里有全部筛选条件。

#保存趋势历史

没有任何趋势接口会返回过去的列表，官方接口也不例外：每次调用都是此刻的快照，所以趋势历史就是你自己保存的那些快照。按计划轮询你要跟踪的地区，把每份列表连同时间和排名一起存下来。

X 没有公布重新计算列表的间隔。每小时一次的快照适合仪表盘和研究；关注突发话题的新闻编辑部则每 5 到 15 分钟轮询一次。下面的脚本把四个地区的一次快照存进 SQLite。

import sqlite3
import time
from datetime import datetime, timezone

import requests

API = "https://api.sorsa.io/v3/trends"
HEADERS = {"ApiKey": "YOUR_API_KEY"}
PLACES = {"Worldwide": 1, "United States": 23424977,
          "Mexico": 23424900, "Japan": 23424856}

db = sqlite3.connect("trends.db")
db.execute("""CREATE TABLE IF NOT EXISTS trends (
    taken_at TEXT, woeid INTEGER, place TEXT,
    rank INTEGER, name TEXT, query TEXT)""")

now = datetime.now(timezone.utc)
taken_at = now.strftime("%Y-%m-%d %H:%M:%S")
for place, woeid in PLACES.items():
    params = {"woeid": woeid}
    r = requests.get(API, params=params, headers=HEADERS, timeout=30)
    if r.status_code == 429:  # over 20 requests in one second
        time.sleep(1)
        r = requests.get(API, params=params, headers=HEADERS, timeout=30)
    r.raise_for_status()
    rows = [(taken_at, woeid, place, rank, t["name"], t["query"])
            for rank, t in enumerate(r.json()["trends"], start=1)]
    db.executemany("INSERT INTO trends VALUES (?, ?, ?, ?, ?, ?)", rows)
db.commit()

每小时运行一次，比如用 cron 的 0 * * * * python3 save_trends.py。按每秒 20 次请求，一个密钥约 23 秒就能读完全部 467 个地区，所以每小时跑一次完全够用，哪怕是全部地区。一天之后，用一条查询就能看到墨西哥哪些趋势持续得最久：

SELECT name, COUNT(DISTINCT taken_at) AS hours
FROM trends
WHERE woeid = 23424900
  AND taken_at >= datetime('now', '-1 day')
GROUP BY name
ORDER BY hours DESC
LIMIT 10;

要获取早于你快照的帖子，趋势的 query 也能当作回溯到 2006 年的搜索来用：Twitter 历史数据里有做法。要在新话题一进入列表时就收到提醒，把每份快照和前一份对比即可，见 Twitter 实时监控。

#趋势数据每月的成本

两家 API 都按每份列表计费，所以月账单就是地区数乘以刷新次数：25 个地区每小时刷新一次，每月 18K 份列表，在官方 X API 上是 $180，在 Sorsa API 上是 $25.20 起。下面可以填入你自己的数字。

在决定趋势这项工作的每个指标上，Sorsa API 都领先于官方 X API：

• 每 1,000 份趋势列表的价格

  Sorsa API

  $1.40 起

  官方 X API

  $10.00

• 趋势背后的帖子，每 1,000 条

  Sorsa API

  $0.07 起，含作者

  官方 X API

  $5.00，11 月 22 日起含作者为 $15.00

• 速率限制

  Sorsa API

  每秒 20 次请求

  官方 X API

  每个应用每 15 分钟 75 次请求

• 遍历全部 467 个地区一轮

  Sorsa API

  约 23 秒

  官方 X API

  约 90 分钟

• 接入

  Sorsa API

  一个 API 密钥

  官方 X API

  通过审核的开发者账号、应用、Bearer 令牌

• 是否需要 X 账号

  Sorsa API

  不需要

  官方 X API

  需要

做趋势仪表盘、新闻编辑部信息流或研究存档，用 Sorsa API：WOEID 与 X 相同，每份列表约便宜 7 倍，每个趋势背后的帖子每 1,000 条 $0.07 起。Sorsa API 从不要求你的 X 登录信息，所以你自己的账号不会有风险。

#获取你的第一份趋势列表

任何地区的趋势列表都只要一次请求：选好 WOEID，调用 GET /trends，再把头部趋势的 query 发给 POST /search-tweets，就能取到它们背后的帖子。Sorsa API 用一个密钥就能完成两步，列表每 1,000 份 $1.40 起，帖子每 1,000 条 $0.07 起，每个新账号送的 100 次免费请求可覆盖你的前 100 份列表，无需绑卡，也不会过期。

#常见问题