# Twitter trends API: trending topics by location as JSON

> X's trends endpoint costs $0.010 a request and needs a developer account. Ours returns 30 ranked trends per place for 7 credits, each with a search query.

- URL: https://toolzerhub.com/blog/twitter-trends-api
- Published: 2026-10-21
- Publisher: ToolzerHub (we sell the API this post describes)

## Short answer

- X's trends endpoint is GET /2/trends/by/woeid/:id: pay-per-use at $0.010 a request, up to 50 trends, with tweet_count if you ask for it.
- Trend lists are local. New York shared 26 of its 30 trends with the US list, but the US and Germany shared 8, and worldwide and Japan 1.
- ToolzerHub returns 30 ranked trends per WOEID, each with a ready search query, for 7 credits a call and no X developer account. It has no tweet counts or history.

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](https://docs.x.com/x-api/trends/trends-by-woeid/introduction) 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](https://toolzerhub.com/apis/x) has `/v1/x/trends`, which takes a WOEID (1 is worldwide, 23424977 the United States) and costs 7 credits per call.

```bash
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:

```json
{
  "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](https://toolzerhub.com/blog/twitter-api-search-tweets) 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:

| Place | WOEID |
|---|---|
| Worldwide | 1 |
| United States | 23424977 |
| United Kingdom | 23424975 |
| Germany | 23424829 |
| Brazil | 23424768 |
| India | 23424848 |
| Japan | 23424856 |
| New York | 2459115 |
| London | 44418 |
| Tokyo | 1118370 |

## 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`.

```python
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](https://toolzerhub.com/pricing) 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](https://toolzerhub.com/blog/is-twitter-api-free). To follow news channels on Telegram instead, see [Telegram channel messages as JSON](https://toolzerhub.com/blog/telegram-channel-messages).

We are not affiliated with X Corp.
