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.
Authorization
bearerAuth Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.
In: header
Query Parameters
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.
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
| Unit | Price |
|---|---|
| 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.
Related endpoints
- 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.)
Do I need to call this before every Trends call?
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.
Trends GET
Fetch the current top trends for one location. Ask for it by country name, ISO code, or numeric WOEID; with no location parameter you get Worldwide. X returns roughly 50 trends per location, ranked. Pass category instead: trending, news, sports, entertainment or for_you reads that X Explore tab, and business_and_finance keeps only the ranked trends X labels Business and finance on its Trending and News tabs. Cost: $0.0008 per call.
Overview
Account: Your API account: credit balance, usage totals, payment history, and product feedback filed from the tool you are using. Served from the API root (https://api.twitterapis.com/account/* and /feedback), not under /twitter, because billing owns their authentication. Free.