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

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

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.

  • 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.)

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.