TwitterAPIs Docs
API ReferenceTrends

Twitter Trend Locations API | WOEID Lookup

Fetch the full set of locations X serves trends for, each with the WOEID to pass back to the Trends endpoint. Takes no parameters and returns the complete list. Cost: $0.0008 per call.

Trend Locations returns every location Twitter/X has trends available for, currently 467 entries covering 62 countries plus cities and Worldwide. Each carries the WOEID you pass back to the Trends endpoint, along with its name, country, ISO code, and place type. One $0.0008 read.

GET
/trends/locations

Authorization

bearerAuth
AuthorizationBearer <token>

Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.

In: header

Query Parameters

fields?string

Comma-separated list of dotted field paths to keep in the response (one parameter, never repeated), applied to every object in the returned lists and to nested objects (for example fields=id,text,author.username; the list's own name may prefix a path, fields=tweets.id). A path prefix that lands on an array applies to each element (media.media_url_https). Pagination and envelope keys (next_cursor, cursor, has_more, count, partial, error, message, reason) are always kept. Unknown paths are ignored; up to 50 paths of up to 6 segments. Projection never changes status codes or billing, and applies to data reads only: account, feedback, session status, monitor (other than deliveries), webhook and stream-compat reads return their bodies unchanged.

compact?string

Set to 1 (or true) to apply the built-in compact preset: ids, url, text, created_at, lang, the engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. The preset trims what it recognises and leaves alone what it would empty, so it never turns a body into {}. Combine with fields to add paths on top of the preset. Typically cuts a tweet page by 70 to 90 percent for LLM tool callers.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/trends/locations?fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"
{  "count": 467,  "locations": [    {      "name": "Worldwide",      "woeid": 1,      "country": "",      "country_code": null,      "countryCode": null,      "parentid": 0,      "place_type": {        "code": 19,        "name": "Supername"      },      "placeType": {        "code": 19,        "name": "Supername"      },      "url": "http://where.yahooapis.com/v1/place/1"    },    {      "name": "United States",      "woeid": 23424977,      "country": "United States",      "country_code": "US",      "countryCode": "US",      "parentid": 1,      "place_type": {        "code": 12,        "name": "Country"      },      "placeType": {        "code": 12,        "name": "Country"      },      "url": "http://where.yahooapis.com/v1/place/23424977"    }  ]}
{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}
{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}
{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}
{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}
{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}
{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}
{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

UnitPrice
Per call$0.0008
Per 1,000 calls$0.80

One $0.0008 read. The list changes on the order of months, so most callers fetch it once and reuse it rather than calling it per request.

When to use

Call it once to discover which WOEIDs exist, then cache the result on your side. It is the lookup table for the Trends endpoint's woeid parameter.

Notes

  • Takes no parameters.
  • Responses are cached for 6 hours, since the list changes on the order of months.
  • An empty list is never served. If X returns nothing usable the endpoint fails loudly rather than answering with a confidently empty list, and the empty result is not cached.
  • Trends: Read the current trending topics for a location, an Explore tab or a trend label.
  • User Search: Find users by keyword across display names and handles.

FAQ

How many locations are there?

467 at last check, of which 62 are country-level and the rest are cities, plus Worldwide (WOEID 1). The list changes on the order of months, not days.

How do I tell a country from a city?

Read place_type.code: 12 is a country, 7 is a town or city, and 19 is Worldwide. Filter on the code rather than guessing from the name, since several cities carry the same country_code as their country. (The camelCase placeType/countryCode are still returned for a deprecation window; prefer the snake_case fields.)

No. If you already know the WOEID you want, pass it straight to Trends. This endpoint exists to discover WOEIDs, and the result is stable enough to cache.

Does it take any parameters?

No. It returns the full list every time.

Was this page helpful?