Twitter trends API: X trends by WOEID

#How the Twitter trends API works

A trends API takes a place and returns X's ranked list of the topics popular there right now, the same list the Explore tab shows to someone signed out. The place goes in as a WOEID (Where On Earth ID): a numeric location code from Yahoo's old geo database that X kept. 1 is the whole world, 23424977 the United States, 2459115 New York.

This guide does the job in code, for any place X covers and any number of them.

X's own endpoint, GET /2/trends/by/woeid/{woeid}, joined the official X API's v2 on December 8, 2023 (X's changelog (opens in a new tab)) and still answers in November 2026. On pay-per-use it costs $0.010 per request, paid from prepaid credits (X's price list (opens in a new tab)). The table sums up the rest of X's reference (opens in a new tab), checked on November 2, 2026.

• Endpoint

  Official X API

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

• Access

  Official X API

  approved developer account, a Project and App, the App's Bearer token

• Trends per call

  Official X API

  20 by default, up to 50 with max_trends

• Fields

  Official X API

  trend_name, plus tweet_count when you ask for it

• Price

  Official X API

  $0.010 per request

• Rate limit

  Official X API

  75 requests per 15 minutes for one app

Two things are not in it. No endpoint in X's current documentation lists the places that have trends: the old v1.1 trends/available call is gone from the docs. And no call returns earlier lists, so a history of trends exists only if you store the snapshots yourself.

#Get trends for any place with Sorsa API

For trend lists in code without a developer account, use Sorsa API, a Twitter (X) API and scraper: GET /trends takes the same WOEID and returns X's list for that place in one request, from $1.40 per 1,000 lists against $10.00 on the official X API, at 20 requests per second on every plan.

1. Get a key. Sign up and copy the API key from your dashboard. The 100 free requests are already on it, with no card.

2. Pick the place. Find its WOEID in the finder further down, or use 1 for worldwide.

3. Send the request. Call GET /trends (opens in a new tab) with woeid in the query string and the key in the ApiKey header.

   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"
       }
     ]
   }
   

   Show full response

4. Read the list. Each trend has a name (the topic as X shows it), a query (the search behind it) and a url (its search page on X). The order is X's ranking, so the first item is the top trend.

A 403 answer means the key is missing or out of requests, and a 401 means the key is wrong. A 429 means more than 20 requests in one second: wait a second and send it again. Failed requests are never charged, and every call returns fresh data, so two calls an hour apart give two different snapshots.

#Find the WOEID for any country or city

X publishes trend lists for 467 places: worldwide, 62 countries and 404 cities, each with its own WOEID (X's list of trend locations (opens in a new tab), unchanged when it was fetched from X again in August 2025). Every one of them works in GET /trends. A town that is not on the list has no trends of its own, so use the nearest listed city or the country.

The table holds the countries people ask about most, each with a major city; the finder under it holds all 467 places.

• Worldwide

  WOEID

  1

  Major city

  —

  City WOEID

  —

• United States

  WOEID

  23424977

  Major city

  New York

  City WOEID

  2459115

• Mexico

  WOEID

  23424900

  Major city

  Mexico City

  City WOEID

  116545

• India

  WOEID

  23424848

  Major city

  Mumbai

  City WOEID

  2295411

• Japan

  WOEID

  23424856

  Major city

  Tokyo

  City WOEID

  1118370

• United Kingdom

  WOEID

  23424975

  Major city

  London

  City WOEID

  44418

• Brazil

  WOEID

  23424768

  Major city

  São Paulo

  City WOEID

  455827

• Indonesia

  WOEID

  23424846

  Major city

  Jakarta

  City WOEID

  1047378

• Turkey

  WOEID

  23424969

  Major city

  Istanbul

  City WOEID

  2344116

• Spain

  WOEID

  23424950

  Major city

  Madrid

  City WOEID

  766273

• Australia

  WOEID

  23424748

  Major city

  Sydney

  City WOEID

  1105779

• South Korea

  WOEID

  23424868

  Major city

  Seoul

  City WOEID

  1132599

Mexico has 23 trend cities besides its national list, 23424900: Mexico City is 116545, Guadalajara 124162 and Monterrey 134047. Type any place, or a WOEID you found elsewhere, into the finder to check it and copy the request.

Good to know

WOEID tables copied around the web mix up codes that sit next to each other: 23424868 is South Korea, not Mexico (23424900); 23424775 is Canada, not Australia (23424748); 455825 is Rio de Janeiro, not São Paulo (455827); 1105779 is Sydney, not Tokyo (1118370). A wrong code still returns a valid list, just for another place, so check the name before you store it.

City coverage is uneven. The United States has 63 trend cities, the United Kingdom 26 and Mexico 23, while 9 of the 62 countries, among them Belgium, Denmark and Portugal, have a national list only. X keeps no lists for states or regions.

#Get the posts behind each trend

A trend's query is a ready search: send it to POST /search-tweets (opens in a new tab) and Sorsa API returns the posts behind the trend, about 20 per request, each with its author's full profile. "order": "popular" gives the posts X ranks as Top; "latest" gives the newest first.

The script below reads Mexico's list and prints the three top posts for each of its five top trends. The code decodes a URL-encoded query before it goes into the search.

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

The posts are where a trends job gets expensive on the official X API. Each post costs $0.005, and from November 22, 2026 each post's author is billed as a $0.010 user read too (X's notice (opens in a new tab)), so 1,000 posts with their authors cost $15.00. For the posts behind trends, use Sorsa API: from $0.07 per 1,000 results, author profiles included.

To narrow a trend's posts by language, date or likes, add X operators to the query; the Twitter search API guide covers paging, and the Twitter search operators list has every filter.

#Keep a history of trends

No trends endpoint returns past lists, the official one included: each call is a snapshot of the moment, so a trend history is the snapshots you keep. Poll the places you track on a schedule and save each list with its time and rank.

X publishes no interval at which it recomputes the lists. Hourly snapshots suit dashboards and research; a newsroom watching breaking topics polls every 5 to 15 minutes. The script saves one snapshot of four places into 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()

Run it every hour, for example from cron with 0 * * * * python3 save_trends.py. At 20 requests per second one key reads all 467 places in about 23 seconds, so even the full list fits an hourly run. After a day, one query shows what trended longest in Mexico:

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;

For posts older than your snapshots, a trend's query also works as a search back to 2006: historical Twitter data shows how. To get an alert the moment a new topic enters a list, compare each snapshot with the one before, as in real-time Twitter monitoring.

#What trend data costs per month

Both APIs bill trend data per list, so the monthly bill is places times refreshes: 25 places every hour make 18K lists a month, $180 on the official X API and from $25.20 on Sorsa API. Pick your own numbers below.

On every measure that decides a trends job, Sorsa API comes out ahead of the official X API:

• Price per 1,000 trend lists

  Sorsa API

  from $1.40

  Official X API

  $10.00

• Posts behind trends, per 1,000

  Sorsa API

  from $0.07, authors included

  Official X API

  $5.00, or $15.00 with authors from Nov 22

• Rate limit

  Sorsa API

  20 requests per second

  Official X API

  75 requests per 15 minutes per app

• One pass over all 467 places

  Sorsa API

  about 23 seconds

  Official X API

  about 90 minutes

• Setup

  Sorsa API

  one API key

  Official X API

  approved developer account, app, Bearer token

• X account needed

  Sorsa API

  no

  Official X API

  yes

For a trends dashboard, a newsroom feed or a research archive, use Sorsa API: the same WOEIDs as X, about 7 times less per list, and the posts behind every trend from $0.07 per 1,000. Sorsa API never asks for your X login, so your own account is never at risk.

#Pull your first trend list

A trend list for any place is one request: pick the WOEID, call GET /trends, and send the top queries to POST /search-tweets for the posts behind them. Sorsa API does both with one key, from $1.40 per 1,000 lists and $0.07 per 1,000 posts, and the 100 free requests every new account gets cover your first 100 lists, with no card and no expiry.

#FAQ