X API trends by WOEID endpoint

X exposes trending topic names through a single location-scoped endpoint: GET /2/trends/by/woeid/:id. The response is a JSON array of topic strings ranked by volume within that geography. Nothing in the payload explains why a topic trended, and there is no worldwide WOEID that returns a single global list.

For the broader X API cost picture, see the X trending topics API and X API pay-per-use endpoint costs.

Endpoint shape and response fields

GET https://api.x.com/2/trends/by/woeid/{id}
Authorization: Bearer YOUR_ACCESS_TOKEN

A successful response returns a data array. Each element includes a trend_name string and a tweet_count field when X exposes volume for that location. Field availability varies by WOEID and account tier.

Example response structure:

{
  "data": [
    {"trend_name": "topic one", "tweet_count": 125000},
    {"trend_name": "topic two", "tweet_count": 98000}
  ]
}

The endpoint returns names only. Tweet bodies, user objects, and engagement breakdowns require separate post-read calls at $0.005 each.

WOEID table for common locations

Teams monitoring multiple markets maintain a WOEID lookup table. The IDs below match values published in X developer examples and third-party geo references. Verify in the Developer Console before production use, since X occasionally deprecates location coverage.

Polling country-level WOEIDs captures national trending lists. City WOEIDs surface local events that never appear on the country list. A product monitoring both needs duplicate calls per interval.

Per-location billing math

X classifies GET /2/trends/by/woeid/:id as a Trends: Read at $0.010 per fetch. Unlike search endpoints, there is no per-result multiplication. One call returns the full trending list for that WOEID regardless of how many topic names appear.

Monthly cost scales linearly with location count and inversely with poll interval. A 15-market monitor on a 15-minute cadence spends roughly $432 per month on trends reads alone, with no post sampling or user resolution.

Why teams still poll multiple WOEIDs

Location-scoped trends answer a different question than a global ranked feed. A breaking story in San Francisco may rank locally before it surfaces nationally. Political and sports events often show city-level spikes hours before country lists update.

Three workflow patterns justify multi-WOEID polling:

1. Geo-fenced alerting. A newsroom watches NYC and LA WOEIDs separately so local editors see city trends without filtering a national list.
2. Market expansion checks. An e-commerce team compares trending product terms across UK, DE, and FR WOEIDs before launching localized campaigns.
3. Cross-location deduplication. A pipeline polls five country WOEIDs, unions topic names, and ranks by how many geographies mention the same string.

Each pattern multiplies the $0.010 per-call cost. Merging results also requires custom deduplication logic X does not provide.

Limits that WOEID polling does not solve

The WOEID endpoint has structural gaps teams discover after wiring production monitors:

• No global list. Worldwide trending requires polling many locations or using an aggregated third-party feed.
• No historical series. Each call is a snapshot. Trend velocity and rank-change history need external storage.
• No category filters. Sports, entertainment, and news share one list per location.
• Volume field inconsistency. tweet_count may be null depending on location and API tier.

For rank-change detection and cron scheduling on a single global feed, see monitoring X trending topics on a schedule.

Aggregated feed alternative

When the goal is a ranked global topic list without WOEID tables or per-location billing, get_top_trends on Trends MCP returns live X trending data in one POST call:

{
  "mode": "get_top_trends",
  "type": "X (Twitter)",
  "limit": 25
}

Response shape:

{
  "as_of_ts": "2026-07-23T06:00:00Z",
  "type": "X (Twitter)",
  "data": [[1, "topic name"], [2, "another topic"]]
}

One request replaces 15 WOEID calls at $0.010 each ($0.15 per poll on the official API). The tradeoff is geography: the aggregated feed does not expose per-city breakdowns. Teams that need city-level lists still require WOEID polling or a geo-aware data provider.

The official WOEID endpoint remains the right path when the product requires X-native location scoping, tweet counts per trend where available, or integration inside an existing X developer project. The aggregated feed fits alerting, cross-platform dashboards, and AI assistant workflows that only need current ranked topic names.