API de trends do Twitter: trends do X por WOEID

#Como funciona a API de trends do Twitter

Uma API de trends recebe um lugar e devolve a lista ordenada de assuntos populares ali neste momento, a mesma lista que a aba Explorar mostra para quem está deslogado. O lugar entra como um WOEID (Where On Earth ID): um código numérico de localização do antigo banco de dados geográfico do Yahoo que o X manteve. 1 é o mundo todo, 23424977 os Estados Unidos, 2459115 Nova York.

Este guia faz o trabalho em código, para qualquer lugar que o X cubra e para quantos você quiser.

O endpoint do próprio X, GET /2/trends/by/woeid/{woeid}, entrou na v2 da API oficial do X em 8 de dezembro de 2023 (changelog do X (abre em uma nova aba)) e ainda responde em novembro de 2026. No pagamento por uso, custa US$ 0,010 por requisição, pagos com créditos pré-pagos (lista de preços do X (abre em uma nova aba)). A tabela resume o restante da referência do X (abre em uma nova aba), conferida em 2 de novembro de 2026.

• Endpoint

  API oficial do X

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

• Acesso

  API oficial do X

  conta de desenvolvedor aprovada, um Project e um App, o Bearer token do App

• Trends por chamada

  API oficial do X

  20 por padrão, até 50 com max_trends

• Campos

  API oficial do X

  trend_name, mais tweet_count quando você pede

• Preço

  API oficial do X

  US$ 0,010 por requisição

• Rate limit

  API oficial do X

  75 requisições por 15 minutos para um app

Duas coisas não estão nela. Nenhum endpoint da documentação atual do X lista os lugares que têm trends: a antiga chamada trends/available da v1.1 sumiu da documentação. E nenhuma chamada devolve listas anteriores, então um histórico de trends só existe se você mesmo guardar os snapshots.

#Obtenha trends de qualquer lugar com a Sorsa API

Para listas de trends em código sem conta de desenvolvedor, use a Sorsa API, uma API e scraper do Twitter (X): o GET /trends recebe o mesmo WOEID e devolve a lista do X para aquele lugar em uma requisição, a partir de US$ 1,40 por 1.000 listas contra US$ 10,00 na API oficial do X, a 20 requisições por segundo em todos os planos.

1. Pegue uma chave. Cadastre-se e copie a chave de API no seu painel. As 100 requisições grátis já estão nela, sem cartão.

2. Escolha o lugar. Ache o WOEID dele no localizador mais abaixo, ou use 1 para o mundo todo.

3. Envie a requisição. Chame o GET /trends (abre em uma nova aba) com woeid na query string e a chave no header 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"
       }
     ]
   }
   

   Ver resposta completa

4. Leia a lista. Cada trend tem um name (o assunto como o X o mostra), uma query (a busca por trás dele) e uma url (a página de busca dele no X). A ordem é o ranking do X, então o primeiro item é o trend do topo.

Uma resposta 403 significa que a chave está ausente ou sem requisições, e um 401 significa que a chave está errada. Um 429 significa mais de 20 requisições em um segundo: espere um segundo e envie de novo. Requisições com falha nunca são cobradas, e toda chamada devolve dados novos, então duas chamadas com uma hora de diferença dão dois snapshots diferentes.

#Ache o WOEID de qualquer país ou cidade

O X publica listas de trends para 467 lugares: o mundo todo, 62 países e 404 cidades, cada um com seu WOEID (lista de locais de trends do X (abre em uma nova aba), sem mudanças quando foi buscada de novo no X em agosto de 2025). Todos funcionam no GET /trends. Uma cidade pequena que não está na lista não tem trends próprios, então use a cidade listada mais próxima ou o país.

A tabela traz os países mais procurados, cada um com uma grande cidade; o localizador abaixo dela traz os 467 lugares.

• Mundial

  WOEID

  1

  Cidade principal

  -

  WOEID da cidade

  -

• Estados Unidos

  WOEID

  23424977

  Cidade principal

  Nova York

  WOEID da cidade

  2459115

• México

  WOEID

  23424900

  Cidade principal

  Cidade do México

  WOEID da cidade

  116545

• Índia

  WOEID

  23424848

  Cidade principal

  Mumbai

  WOEID da cidade

  2295411

• Japão

  WOEID

  23424856

  Cidade principal

  Tóquio

  WOEID da cidade

  1118370

• Reino Unido

  WOEID

  23424975

  Cidade principal

  Londres

  WOEID da cidade

  44418

• Brasil

  WOEID

  23424768

  Cidade principal

  São Paulo

  WOEID da cidade

  455827

• Indonésia

  WOEID

  23424846

  Cidade principal

  Jacarta

  WOEID da cidade

  1047378

• Turquia

  WOEID

  23424969

  Cidade principal

  Istambul

  WOEID da cidade

  2344116

• Espanha

  WOEID

  23424950

  Cidade principal

  Madri

  WOEID da cidade

  766273

• Austrália

  WOEID

  23424748

  Cidade principal

  Sydney

  WOEID da cidade

  1105779

• Coreia do Sul

  WOEID

  23424868

  Cidade principal

  Seul

  WOEID da cidade

  1132599

O México tem 23 cidades com trends além da lista nacional, 23424900: a Cidade do México é 116545, Guadalajara 124162 e Monterrey 134047. Digite qualquer lugar, ou um WOEID que você achou em outro canto, no localizador para conferi-lo e copiar a requisição.

Bom saber

As tabelas de WOEID copiadas pela web misturam códigos vizinhos: 23424868 é a Coreia do Sul, não o México (23424900); 23424775 é o Canadá, não a Austrália (23424748); 455825 é o Rio de Janeiro, não São Paulo (455827); 1105779 é Sydney, não Tóquio (1118370). Um código errado ainda devolve uma lista válida, só que de outro lugar, então confira o nome antes de guardá-lo.

A cobertura de cidades é desigual. Os Estados Unidos têm 63 cidades com trends, o Reino Unido 26 e o México 23, enquanto 9 dos 62 países, entre eles Bélgica, Dinamarca e Portugal, têm só uma lista nacional. O X não mantém listas de estados nem de regiões.

#Obtenha os posts por trás de cada trend

A query de um trend é uma busca pronta: envie-a para o POST /search-tweets (abre em uma nova aba) e a Sorsa API devolve os posts por trás do trend, cerca de 20 por requisição, cada um com o perfil completo do autor. "order": "popular" dá os posts que o X ranqueia como Top; "latest" dá os mais novos primeiro.

O script abaixo lê a lista do México e imprime os três principais posts de cada um dos cinco principais trends. O código decodifica uma query codificada como URL antes de ela entrar na busca.

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`);
  }
}

Os posts são onde um trabalho com trends fica caro na API oficial do X. Cada post custa US$ 0,005 e, a partir de 22 de novembro de 2026, o autor de cada post também é cobrado como uma leitura de usuário de US$ 0,010 (aviso do X (abre em uma nova aba)), então 1.000 posts com seus autores custam US$ 15,00. Para os posts por trás dos trends, use a Sorsa API: a partir de US$ 0,07 por 1.000 resultados, perfis de autores incluídos.

Para restringir os posts de um trend por idioma, data ou curtidas, acrescente operadores do X à query; o guia da API de busca do Twitter cobre a paginação, e a lista de operadores de busca do Twitter traz todos os filtros.

#Guarde um histórico de trends

Nenhum endpoint de trends devolve listas passadas, o oficial inclusive: cada chamada é um snapshot do momento, então um histórico de trends são os snapshots que você guarda. Consulte os lugares que você acompanha em intervalos fixos e salve cada lista com o horário e a posição.

O X não publica o intervalo em que recalcula as listas. Snapshots por hora servem para dashboards e pesquisa; uma redação que acompanha assuntos de última hora consulta a cada 5 a 15 minutos. O script salva um snapshot de quatro lugares no 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()

Rode-o a cada hora, por exemplo pelo cron com 0 * * * * python3 save_trends.py. A 20 requisições por segundo, uma chave lê os 467 lugares em cerca de 23 segundos, então até a lista completa cabe em uma execução por hora. Depois de um dia, uma consulta mostra o que ficou mais tempo em alta no México:

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;

Para posts mais antigos que seus snapshots, a query de um trend também funciona como busca até 2006: dados históricos do Twitter mostra como. Para receber um alerta no momento em que um assunto novo entra em uma lista, compare cada snapshot com o anterior, como em monitoramento do Twitter em tempo real.

#Quanto custam os dados de trends por mês

As duas APIs cobram dados de trends por lista, então a conta mensal é lugares vezes atualizações: 25 lugares a cada hora dão 18 mil listas por mês, US$ 180 na API oficial do X e a partir de US$ 25,20 na Sorsa API. Escolha seus próprios números abaixo.

Em todos os critérios que decidem um trabalho com trends, a Sorsa API sai na frente da API oficial do X:

• Preço por 1.000 listas de trends

  Sorsa API

  a partir de US$ 1,40

  API oficial do X

  US$ 10,00

• Posts por trás de trends, por 1.000

  Sorsa API

  a partir de US$ 0,07, autores incluídos

  API oficial do X

  US$ 5,00, ou US$ 15,00 com autores a partir de 22 de nov.

• Rate limit

  Sorsa API

  20 requisições por segundo

  API oficial do X

  75 requisições por 15 minutos por app

• Uma passada pelos 467 lugares

  Sorsa API

  cerca de 23 segundos

  API oficial do X

  cerca de 90 minutos

• Configuração

  Sorsa API

  uma chave de API

  API oficial do X

  conta de desenvolvedor aprovada, app, Bearer token

• Precisa de conta do X

  Sorsa API

  não

  API oficial do X

  sim

Para um dashboard de trends, o feed de uma redação ou um arquivo de pesquisa, use a Sorsa API: os mesmos WOEIDs do X, cerca de 7 vezes menos por lista, e os posts por trás de cada trend a partir de US$ 0,07 por 1.000. A Sorsa API nunca pede seu login do X, então sua própria conta nunca fica em risco.

#Obtenha sua primeira lista de trends

Uma lista de trends de qualquer lugar é uma requisição: escolha o WOEID, chame o GET /trends e envie as queries do topo para o POST /search-tweets para obter os posts por trás delas. A Sorsa API faz as duas coisas com uma chave, a partir de US$ 1,40 por 1.000 listas e US$ 0,07 por 1.000 posts, e as 100 requisições grátis que toda conta nova ganha cobrem as suas primeiras 100 listas, sem cartão e sem expirar.

#Perguntas frequentes