Twitter trends API: trending topics by location as JSON

X's trends API is GET /2/trends/by/woeid/:id. It returns up to 50 trending topics for a place, with tweet counts if you ask, at $0.010 a request. ToolzerHub returns a ranked list of 30 current trends for a place for 7 credits, with no X developer account and no tweet counts.

What X's trends endpoint gives you

X's trends endpoint returns trending topics for a place identified by a Yahoo! Where On Earth ID (WOEID). max_trends runs from 1 to 50 and defaults to 20, and tweet_count comes back only when you pass trend.fields=tweet_count. It is pay-per-use at $0.010 a request, limited to 75 requests per 15 minutes per app, and the pricing page lists no free allowance.

Neither X nor our route has a parameter for past trends. To know what trended yesterday at 3pm, you need to have saved it at 3pm. Use X's endpoint if you need tweet counts, more than 30 trends, or already have a developer account with credits.

Get trends for a place with ToolzerHub

We make ToolzerHub. Our X API has /v1/x/trends, which takes a WOEID (1 is worldwide, 23424977 the United States) and costs 7 credits per call.

export TOOLZERHUB_API_KEY=your_key
curl -H "x-api-key: $TOOLZERHUB_API_KEY" \
  "https://api.toolzerhub.com/v1/x/trends?woeid=1"

The start of the worldwide response:

{
  "data": {
    "woeid": 1,
    "location": "Worldwide",
    "updated_at": "2026-10-21T18:32:23.662Z",
    "count": 30,
    "trends": [
      { "rank": 1, "name": "Carrick", "query": "Carrick" },
      { "rank": 2, "name": "Manchester United", "query": "\"Manchester United\"" },
      { "rank": 3, "name": "Nico Paz", "query": "\"Nico Paz\"" }
    ]
  }
}

query is ready to pass to a search: multi-word trends come quoted. Our Twitter search API guide shows how to pull the posts behind a trend.

What 10 places showed

We pulled worldwide, the US, the UK, Germany, Brazil, India, Japan, New York, London and Tokyo. Each call returned 30 trends.

• A city list is mostly its country's list. New York shared 26 of 30 with the US, London 20 with the UK, Tokyo 17 with Japan.
• Country lists overlap far less. The US shared 9 trends with the UK and 8 with Germany. Worldwide shared 13 with the US and 1 with Japan, and 10 worldwide trends appeared in none of the 9 local lists.

The WOEIDs we used, for your own calls:

Log trends over time

The script calls the route for each WOEID you pass and appends every trend to a CSV with the time it was fetched. Run it from cron to build the history neither API keeps, for example 0 * * * * cd /path && TOOLZERHUB_API_KEY=your_key python3 x_trends.py 1,23424977 >> trends.log 2>&1.

import csv
import os
import sys
import time
from datetime import datetime, timezone

import requests

URL = "https://api.toolzerhub.com/v1/x/trends"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
FIELDS = ["fetched_at", "woeid", "location", "rank", "name", "query"]


def trends(woeid, tries=3):
    # 429, 500, 503 and dropped connections are retried; failed calls cost no credits.
    for attempt in range(tries):
        last = attempt == tries - 1
        try:
            r = requests.get(URL, headers=HEADERS, params={"woeid": woeid}, timeout=60)
        except requests.RequestException:
            if last:
                raise
            time.sleep(10 * (attempt + 1))
            continue
        if r.status_code in (429, 500, 503) and not last:
            time.sleep(10 * (attempt + 1))
            continue
        r.raise_for_status()
        return r.json()["data"]


def main(woeids, out="x_trends.csv"):
    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    new_file = not os.path.exists(out)
    rows = 0
    with open(out, "a", newline="", encoding="utf-8-sig" if new_file else "utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=FIELDS)
        if new_file:
            writer.writeheader()
        for woeid in [w.strip() for w in woeids.split(",") if w.strip()]:
            data = trends(woeid)
            for t in data["trends"]:
                writer.writerow({"fetched_at": now, "woeid": woeid, "location": data["location"],
                                 "rank": t["rank"], "name": t["name"], "query": t["query"]})
                rows += 1
    print(f"{rows} trends appended to {out}")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        sys.exit("usage: python x_trends.py 1,23424977,44418 [file.csv]")
    if not HEADERS["x-api-key"]:
        sys.exit("set TOOLZERHUB_API_KEY first")
    main(*sys.argv[1:])

python x_trends.py 1,23424977,44418 made 3 calls and appended 90 rows in 3 seconds. A second run 35 minutes later found 3 new trends in the worldwide 30, 9 in the US list and 6 in London's.

What it costs

Each call is 7 credits, so one place every hour is 24 calls and 168 credits a day. X's endpoint costs $0.24 a day for the same schedule.

You get 100 free credits a month, which cover 14 calls; $19 buys 10,000 credits that never expire, and plans for higher volume cover more places. Set your key and run the script on your first WOEID.

For what the rest of X's API costs, see is the Twitter API free. To follow news channels on Telegram instead, see Telegram channel messages as JSON.

We are not affiliated with X Corp.