Twitter Trends API

By Michael Park•8 min read
A world map with WOEID code labels — Worldwide=1 (center), USA=23424977, Tokyo=1118370, London=44418, Sao Paulo=455825 — and a sample Trends API JSON response in the corner showing trending hashtags
WOEID is the address. The address survived. The toll changed.

The Twitter Trends API — the endpoint that returns the list of trending topics for a specific location — has been around so long that the location codes it uses pre-date Twitter itself. WOEID (Yahoo's Where-On-Earth ID system) was built in the 2000s for Yahoo Pipes and never went away. The endpoint built on top of it has been part of the Twitter API since v1.0. Every Twitter dashboard, every brand-monitoring tool, every social-listening product that shows "trending in NYC right now" hits this endpoint.

In 2026 the WOEID system itself is unchanged — Worldwide is still 1, USA is still 23424977, Tokyo is still 1118370. What changed is how access is billed. X no longer sells fixed monthly tiers: the official API, Trends included, is pay-per-usage with no subscriptions ($0.010 per Trends request), needs an X developer account with a saved payment card, and caps pay-per-usage at 3,000,000 Post reads per monthly billing cycle (Enterprise above that, no public price). The endpoint that powered every basic "trending now" widget for fifteen years is now a metered call.

This page covers what "Twitter Trends API" means in 2026: what survived (WOEID, the endpoint shape), what changed (metered billing and the cap), the official endpoint signature, the WOEID reference table you actually need, and a working alternative that doesn't require an X developer account.

Trends cost vs official

Polling 30 cities every 5 minutes = ~259,200 calls/month. On TwitterAPI.io, the top 30 trends per city (count=30, the default) cost about $1,166/month at 15 credits per trend. On official X the same polling costs about $2,592/month at $0.010 per Trends request. About 2.2× less.

01 — Section

A Trends API call takes a single parameter — a WOEID — and returns the list of currently-trending hashtags and phrases for that location, ranked roughly by velocity. A typical response is 50 trends, each with the topic string, the URL it links to on X, an estimated tweet-volume number (on the official API, when available), and sometimes a context object describing why the trend appears in that location.

The endpoint is read-only and idempotent — call it as often as you like, you get the latest snapshot of the trending list for that WOEID. Trends refresh server-side roughly every 5 minutes; polling more often than that doesn't get you fresher data, only more bills.

Common use cases that have not changed since 2016: real-time content discovery for editorial teams, brand-safety monitoring (is my brand trending unexpectedly?), seed-keyword generation for SEO and ad workflows, sentiment tracking starting points, dashboard widgets for marketing teams. None of those use cases got easier in 2026; the data is just behind a higher wall.

02 — Section

WOEID — The Location System You Need

WOEID stands for Where-On-Earth Identifier, originally Yahoo's geocode system. Twitter adopted it in early v1 and never replaced it — the codes are stable, well-documented, and cover every country, every US state, and most major cities worldwide. WOEIDs are integers, typically 5-8 digits long.

The single most useful WOEID is 1 — Worldwide. Calling the Trends API with woeid=1 returns the trending list across all of X, not filtered to any country or city. Most analytics dashboards start here.

Country and city WOEIDs you'll use most:

LocationWOEID
Worldwide1
United States23424977
United Kingdom23424975
Japan23424856
Brazil23424768
Germany23424829
France23424819
Spain23424950
Canada23424775
Australia23424748
India23424848
Mexico23424900
New York2459115
Los Angeles2442047
London44418
Tokyo1118370
Paris615702
Sao Paulo455825
Sydney1105779
Toronto4118

The complete list of supported WOEIDs is roughly 500 — every major metro area plus every country. Locations not in the supported set return an empty trends list rather than an error.

03 — Section

On the X v2 surface the endpoint is GET /2/trends/by/woeid/{woeid}. The path takes the WOEID as a URL parameter (not query), authorization is a bearer token, and the response is JSON.

Access: an X developer account with a saved payment card. There are no tiers or subscriptions any more — Trends calls are billed pay-per-usage like other resources: X lists Trends at $0.010 per request (docs.x.com/x-api/getting-started/pricing), so polling 30 locations every 5 minutes (259,200 requests a month) costs about $2,592 on the official API. This is the change that brings most teams to this page — pre-2024 the trends endpoint was effectively free; in 2026 every call is metered.

Cap impact: pay-per-usage is capped at 3,000,000 Post reads per monthly billing cycle. A trends call returns trend metadata rather than Posts, but a team polling trends for 20 locations every 5 minutes (288 calls/day × 20 = 5,760 calls/day × 30 days = 172,800 calls/month, about $1,728 at $0.010 each) usually runs search and timeline reads on the same account, and those reads are what push it toward the cap.

Rate limit: like other v2 endpoints, trends has per-endpoint limits in 15-minute windows (see docs.x.com for the current figure). The bottleneck is rarely the per-window rate limit; it's the metered bill and the monthly cap.

04 — Section

The overhead is hard to justify for most use cases smaller than a top-50 newsroom or an enterprise social-listening platform. A small editorial team that wants "trending in 5 cities every 15 minutes" has to open an X developer account, save a payment card and pay $0.010 per call for what is functionally a 50-item JSON response refreshed every 5 minutes server-side.

Three failure modes are common with the official path:

Setup mismatch. A side project, an indie analytics tool, a startup's MVP — all want a trends feed without opening an X developer account, saving a payment card and modelling per-resource billing for a 50-item list.

Polling-cost mismatch. Trends update every 5 minutes server-side. To stay current you poll every 5 minutes per WOEID. For 30 cities that's ~260,000 calls/month — about $2,592 at $0.010 per request, and well under the 3M Post-read cap on its own, but when combined with any other read workload (search, user info, timelines), the cap binds.

Visibility mismatch. The official endpoint returns no historical trend data — only the current snapshot. To track "what was trending yesterday at 3pm in Tokyo" you have to poll continuously and persist the snapshots yourself. That polling cost compounds with every metered call.

05 — Section

The third-party path most teams move to is TwitterAPI.io's /twitter/trends endpoint. The signature is intentionally similar to the official one — take a WOEID, return the trend list — so existing code that assumed the official shape ports over with a base-URL swap and a one-line change to unwrap each trend.

Endpoint: GET https://api.twitterapi.io/twitter/trends?woeid={woeid}. Auth is X-API-Key header. Required param is woeid. The one optional param is count, the number of trends to return (minimum 30: smaller values are raised to 30; see docs.twitterapi.io).

Pricing: 15 credits ($0.00015) per trend returned, with a 15-credit minimum per request (see twitterapi.io/pricing). count defaults to 30 ($0.0045 a call) and has a floor of 10, so the smallest call returns 10 trends and costs $0.0015. A team polling 30 cities every 5 minutes (~259,200 calls/month) pays about $1,166/month for the top 30 per city. The same workload on the official API costs about $2,592/month at $0.010 per request, however many trends come back.

Same WOEID system: the WOEID values are unchanged across both APIs — Worldwide=1, USA=23424977, Tokyo=1118370. The lookup table above works as-is.

Response shape: a top-level trends list, each item wrapped as {"trend": {...}} with the topic string in name, its position in rank, and the search query the trend resolves to in target.query. There is no tweet-volume field. The nesting differs from the official v2 response, so read item["trend"]["name"] when porting.

06 — Section

Two scenarios where the official path is the right choice:

You already run other workloads on the official API. If your team already has an X developer account billing search or streaming reads, Trends is one more metered call on the same account and the same bill, and the cap math is shared across all your reads.

You need official X branding compliance. Some enterprise data licensing terms require that data come from the official X API surface (compliance with internal data-source policies, contractual obligations to end customers). In those cases TwitterAPI.io is not a substitute regardless of cost.

Outside these two cases, the alternative path costs less per trend poll as long as each call returns fewer than about 66 trends ($0.010 ÷ $0.00015 per trend): about 2.2× less at the default 30 trends. For most teams the answer is "start on the alternative, move up if compliance demands it."

python
import os
import time
import requests

API_KEY = os.environ["TWITTERAPI_IO_KEY"]
HEADERS = {"X-API-Key": API_KEY}

# Common WOEIDs — see body for the full table
WOEIDS = {
    "worldwide": 1,
    "usa": 23424977,
    "tokyo": 1118370,
    "london": 44418,
    "sao_paulo": 455825,
    "sydney": 1105779,
}


def get_trends(woeid: int) -> list[dict]:
    """Return the current trend list for a WOEID."""
    r = requests.get(
        "https://api.twitterapi.io/twitter/trends",
        params={"woeid": woeid, "count": 30},  # 30 is the minimum; billed per trend returned
        headers=HEADERS,
        timeout=30,
    )
    r.raise_for_status()
    return r.json().get("trends", [])


# Poll trends for 6 locations every 5 minutes
# Monthly bill: 6 × 288 polls/day × 30 days = 51,840 calls × 30 trends × 15 credits
# = 23,328,000 credits = ~$233.28
for name, woeid in WOEIDS.items():
    trends = get_trends(woeid)
    print(f"=== {name.upper()} (woeid={woeid}) ===")
    for t in trends[:10]:
        trend = t["trend"]  # each item is wrapped: {"trend": {"name", "rank", "target"}}
        print(f"  {trend.get('rank')}. {trend['name']}")

# In production wrap the above in a loop with `time.sleep(300)` — trends
# refresh server-side every 5 minutes, polling more often returns the
# same snapshot.

Researching this?Free starter credits cover end-to-end testing — Google sign-in, no card. Get a key.

07 — Questions

Questions readers ask

Does Twitter still have a Trends API in 2026?

Yes — GET /2/trends/by/woeid/{woeid} on the official v2 surface, but it is now billed pay-per-usage ($0.010 per request), with no subscriptions or tiers, and needs an X developer account with a saved payment card. The endpoint shape and the WOEID location system are unchanged from earlier API generations; what changed is that every call is metered.

What is a WOEID?

WOEID stands for Where-On-Earth Identifier — Yahoo's geocode system, adopted by Twitter in early v1 and never replaced. Each supported location has a stable integer code: Worldwide is 1, USA is 23424977, Tokyo is 1118370, London is 44418. The system covers every country plus ~500 major metro areas globally. Codes are stable across both the official X API and third-party alternatives.

How often do Twitter trends update?

Server-side roughly every 5 minutes. Polling the endpoint more often than that returns the same snapshot — you get more bills, not fresher data. For most dashboards a 5-minute poll interval is the right cadence; for editorial discovery workflows a 60-second poll catches the trend the moment it cycles.

How much does the Twitter Trends API cost in 2026?

On official X: Trends is billed pay-per-usage at $0.010 per request, with no subscription (docs.x.com/x-api/getting-started/pricing), on an account capped at 3,000,000 Post reads per monthly billing cycle; polling 30 cities every 5 minutes costs about $2,592/month. On TwitterAPI.io: 15 credits ($0.00015) per trend returned, no tier and no cap; the same polling costs about $1,166/month for the top 30 trends per city (count=30, the default).

Can I get historical Twitter trends?

Neither the official Trends API nor most third-party trends endpoints return historical trend snapshots — only the current state. To track "what was trending in Tokyo at 3pm yesterday" you have to poll continuously and persist the snapshots in your own database. A 5-minute poll cadence persisted for one year on 10 WOEIDs is roughly 10.5M rows; manageable on PostgreSQL or any time-series store.

Why do some trends show no tweet_volume?

Tweet volume is estimated server-side and only attached to trends above a confidence threshold. Newer or smaller trends typically come through with tweet_volume: null — the trend is real, the volume estimate hasn't accumulated enough signal yet. That applies to responses that carry a volume at all. TwitterAPI.io's /twitter/trends returns no volume field: each trend has name, rank and target.query, so count matching tweets yourself with /twitter/tweet/advanced_search if you need a number.

Can I get trends for a city not in the WOEID list?

No — the trends system only computes per-location trends for the ~500 WOEIDs in the supported set. Locations outside the set return an empty trends list rather than an error. Smaller cities are aggregated into their containing metro or country WOEID. For a city not in the list, the nearest containing region (usually the country) is the closest approximation available.

08 — Further reading

Continue

More from this series

Writing about something you built with TwitterAPI.io? Our community rewards program pays API credits for honest tutorials, build logs and videos.

Build it

Stop reading. Start building.

Starter credits cover real testing on real data. Google sign-in, no card, no application queue.

Get an API key

Already building with TwitterAPI.io? Publish an honest tutorial or build log about it and earn up to $200 a month in API credits.