X Trends API

X Trends

主要特性

• 按位置标识采集为一个或多个已知数字 WOEID 请求当前公开趋势，并在 extra.woeid 中保留来源标识。
• 保留来源排名上游提供排名时写入 metrics.rank，不使用 SocQ 自行计算的分数替代。
• 提供实用趋势背景除趋势名称外，还会在上游提供时返回查询和描述，便于理解与整理话题。
• 每个位置单独设上限results_limit 分别作用于每个 WOEID，每个位置只采集一次当前可获得的趋势集合。

参数

如何使用

从已经掌握的数字 WOEID 开始，设置每个位置的结果上限，并把返回记录视为采集时快照。

1. 输入一个或多个已知 WOEID，每项均为数字字符串；此端点不会把地名解析为位置标识。
2. 将 results_limit 设为 20 至 2,000 的整数，或保留每个 WOEID 默认 100 条。
3. 向 /v1/x/trends POST 请求，再轮询 /v1/tasks/{task_id} 直到任务成功。
4. 读取 data.results.items，并在 has_more 为 true 时沿任务结果 next_cursor 继续读取。

curl -X POST "https://api.socq.ai/v1/x/trends" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"woeids":["1"],"results_limit":100}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 观察已知市场的话题： 围绕监测系统已经维护的位置标识，采集当前趋势名称、排名和描述。
• 建立周期性观察快照： 按照自己的调度重复运行同一个 WOEID，并随每条结果保存 collected_at，供后续分析变化。
• 生成话题审阅队列： 结合返回的名称、查询、排名和描述，为分析人员或后续发现流程安排公开话题优先级。

使用建议

• 提交任务前先准备好数字 WOEID；地名和自由文本位置不属于可接受输入。
• 默认值 1 来自后端公开的请求示例；实际使用时请替换为符合目标范围的位置标识。
• results_limit 是每个 WOEID 的结果上限，当前趋势集合可能少于请求数量。
• 如果必须保留全部“趋势—位置”关联，请把可能重叠的位置拆成不同任务，因为同一任务内相同趋势名称可能被去重。
• 使用 collected_at 作为观察时间；上游没有提供趋势创建时间，因此 created_at 为 null。
• 任务结果游标只对已保存记录分页，不会向数据源请求下一页趋势。

相关 API