Twitter Trending Topics by Country API: How-To Guide

To get Twitter trending topics by country via API, you need a WOEID (Where On Earth ID) for the target location and an endpoint that proxies the X.com trends feed. Since X shut down free public access to GET trends/place in 2023, the practical path now is either paying $200/month for X's Basic tier or using a pay-per-use actor like Twitter Trends API Global/Country that scrapes the live trends panel for any country.

Quick Answer

The Twitter trending topics by country API works by mapping a country (e.g., "United States" = WOEID 23424977, "Japan" = 23424856) to a request that returns the current top 30–50 trends with hashtag, tweet volume, and rank. X's official API requires a paid developer plan starting at $200/month, while third-party actors on Apify charge pay-per-call (cents per run) and return the same data structure. You send a country code or WOEID, get back JSON with trend names, URLs, and volumes, then refresh every 5–30 minutes since trends shift fast. The fastest setup is calling the Apify actor endpoint with a JSON body specifying your country list — no OAuth, no rate-limit math.

What is a WOEID and why does the Twitter trends API need one?

WOEID stands for "Where On Earth ID" — a 32-bit identifier Yahoo created in 2008 to tag geographic locations. Twitter inherited the system and still uses it internally to scope trends. WOEID 1 means worldwide; country-level codes are 8-digit numbers.

Common WOEIDs you'll actually use:

City-level WOEIDs also exist (New York = 2459115, London = 44418, Tokyo = 1118370), so you can drill down below country granularity.

How do I call the official Twitter trending topics API?

X's official endpoint is GET /1.1/trends/place.json?id={woeid}. As of 2024, you need at least the Basic tier ($200/month) to use it. Here's a minimal cURL after you have a Bearer token:

curl -X GET "https://api.x.com/1.1/trends/place.json?id=23424977" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Response shape:

[{
  "trends": [
    {
      "name": "#WorldCup",
      "url": "http://twitter.com/search?q=%23WorldCup",
      "promoted_content": null,
      "query": "%23WorldCup",
      "tweet_volume": 1284503
    }
  ],
  "as_of": "2026-04-25T14:00:00Z",
  "created_at": "2026-04-25T13:55:00Z",
  "locations": [{"name": "United States", "woeid": 23424977}]
}]

Rate limit on Basic: 75 requests per 15 minutes per app. That covers polling ~25 countries every 5 minutes, which sounds fine until you also need search, user lookup, or timeline endpoints sharing the same quota.

How to get Twitter trends without paying $200/month

Three viable paths:

1. Scrape the X.com explore page directly. Doable but breaks every few weeks when X changes the GraphQL schema or adds bot detection. You'll spend more time on maintenance than on your actual product.
2. Use a pay-per-use actor. Twitter Trends API Global/Country handles the scraping, proxy rotation, and parsing. You pay per run (typically a few cents), so 1,000 country pulls/month often runs under $5 — about 40x cheaper than X Basic if trends are your only need.
3. Self-host with Playwright + residential proxies. Realistic cost: $50–80/month for proxies plus engineering time. Worth it only if you're hitting trends thousands of times per hour.

For most teams — social listening tools, content marketers, news dashboards — option 2 wins.

Step-by-step: pulling country trends with the Apify actor

1. Get an Apify API token

Sign up at apify.com, go to Settings → Integrations, copy your token.

2. Send a run request

curl -X POST "https://api.apify.com/v2/acts/twitterTrendsAPI/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "countries": ["United States", "Japan", "Brazil"],
    "maxTrends": 30
  }'

run-sync-get-dataset-items blocks until the run finishes and returns the dataset directly — no polling needed for short jobs.

3. Parse the response

import requests

resp = requests.post(
    "https://api.apify.com/v2/acts/twitterTrendsAPI/run-sync-get-dataset-items",
    params={"token": "YOUR_TOKEN"},
    json={"countries": ["United States", "Japan"], "maxTrends": 30}
)

for item in resp.json():
    print(f"{item['country']}: {item['trend']} ({item.get('tweetVolume', 'n/a')} tweets)")

4. Schedule recurring pulls

Apify has built-in schedulers (cron syntax). Set it to run every 15 minutes, push results to your database via webhook, and you have a real-time trends feed. A 15-minute cadence across 10 countries = 960 runs/month, which on pay-per-use pricing typically lands at $3–8.

How often do Twitter trends change?

In active markets like the US, India, and Brazil, the top 5 trends shift roughly every 20–60 minutes during peak hours (12pm–11pm local time). Off-peak, a trend can hold its slot for 2–4 hours. Hashtag-driven trends (sports events, TV finales, breaking news) churn fastest — sometimes a new top trend every 5 minutes during live events.

For a content tool tracking opportunities, polling every 10 minutes catches >95% of trend appearances. Polling every 30 minutes still catches the long-lived ones but misses ~30% of short-burst hashtags.

Can I get historical Twitter trends?

The official X API does not provide historical trends — trends/place only returns the current snapshot. To build a historical dataset you have to:

• Run your own poller and store snapshots (most teams do this with a 5–15 minute cron)
• Buy from a data vendor (Brandwatch, Talkwalker — typically $1,500+/month enterprise contracts)
• Use community datasets on Kaggle (often outdated and limited to a few countries)

If historical trends matter, start polling now. Even a basic Postgres table with (country, trend, rank, tweet_volume, captured_at) becomes valuable after 30 days.

What data fields come back from the trends API?

The actor and X's official endpoint both return these per trend:

• name — display string, e.g., #Election2026 or Taylor Swift
• url — search URL on x.com
• query — URL-encoded search query
• tweet_volume — count of tweets in trailing 24 hours (often null for low-volume trends)
• rank — position 1–50 in the list
• promoted_content — null for organic trends, populated for paid placements

Tweet volume is the most-requested field and the most unreliable from official sources — X returns null for ~40% of trends, especially for non-English markets. Scraping the explore page sometimes captures the volume that the API hides.

Common use cases for country-level trend data

• Content calendars — marketers cross-reference trending hashtags with brand-relevant keywords before publishing.
• News aggregators — surface breaking stories per country before wire services pick them up.
• Trading signals — meme stocks and crypto often trend 30–90 minutes before price moves; quants use trend velocity as a feature.
• Localization QA — verify that a campaign's hashtag is actually trending in the target market.
• Competitive intel — track when competitor brand names appear in trends (good or bad).

FAQ

Q: Is scraping Twitter trends legal? Public trend data isn't personal information and isn't behind a login wall, which puts it in the same category as scraping public news headlines. The hiQ v. LinkedIn ruling (2022) reinforced that scraping public data isn't a CFAA violation. That said, X's ToS prohibits scraping, so the legal-but-against-ToS distinction matters if you have a paid X account at risk.

Q: How many countries does the Twitter trends API support? Twitter publishes trends for roughly 60 countries and 400+ cities globally. Some smaller markets (most of Africa, parts of Central Asia) don't have dedicated trend feeds and roll up to regional WOEIDs. The actor exposes the same coverage list X uses internally.

Q: What's the difference between WOEID and country code (ISO 3166)? ISO codes (US, JP, BR) are 2-letter standards used by most APIs. WOEIDs are Yahoo's proprietary 32-bit IDs that Twitter inherited. There's no clean mapping — you have to maintain a lookup table. The actor lets you pass country names directly so you can skip WOEID management entirely.

Q: Can I get tweet volume for every trend? No. X returns tweet_volume: null for trends below ~10,000 tweets/day, and for many non-English-market trends regardless of volume. Roughly 40–60% of trends in smaller markets show null volume. If volume is critical, supplement with a search-count call on the trend name.

Q: How fast can I poll the trends API? Practically, every 5 minutes per country is the sweet spot — fast enough to catch most trend changes, slow enough to avoid waste. X itself updates the underlying data every ~5 minutes, so polling faster returns identical responses. The Apify actor has no hard rate limit; you pay per run, so the constraint is budget rather than throttling.