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
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/trends/locations"{ "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": "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.
Related endpoints
- Trends: Read the current trending topics for a location.
- User Search: Find users by keyword across display names, handles, and bios.
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. Cost: $0.0008 per call.
Overview
Account: Your API account: credit balance, usage totals, and payment history. Served from the API root (https://api.twitterapis.com/account/*), not under /twitter, because billing owns their authentication. Free.