X / Twitter Trend Locations API

List every place with X (Twitter) trends — about 470 countries and cities — with WOEID, country, and type, for use with the Twitter Trends API. JSON, $0.01 per call.

POST/v1/twitter/trends-locations

$0.01/call

Returns every place X publishes trends for (about 470), with the WOEID to pass to the Twitter Trends API. The list rarely changes, so fetch it once and store it.

Usage

const res = await fetch('https://api.yepapi.com/v1/twitter/trends-locations', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const { data } = await res.json();
console.log(data);

curl -X POST https://api.yepapi.com/v1/twitter/trends-locations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import requests

res = requests.post(
    "https://api.yepapi.com/v1/twitter/trends-locations",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={},
)
print(res.json()["data"])

Request Body

Parameter	Type	Required	Description	Default

This endpoint takes no parameters — send an empty JSON body {}.

Response

{
  "ok": true,
  "data": {
    "locations": [
      {
        "country": null,
        "country_code": null,
        "name": "Worldwide",
        "type": "Supername",
        "woeid": 1
      },
      {
        "country": "Canada",
        "country_code": "CA",
        "name": "Winnipeg",
        "type": "Town",
        "woeid": 2972
      }
    ]
  }
}

Response Fields

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`data.locations`	`object[]`	Supported places
`data.locations[].woeid`	`number`	Place WOEID
`data.locations[].name`	`string`	Place name
`data.locations[].country`	`string \| null`	Country name (`null` for Worldwide)
`data.locations[].country_code`	`string \| null`	Two-letter country code
`data.locations[].type`	`string`	`Supername` (worldwide), `Country`, or `Town`

Caching

Responses are cached for 24 hours.

Errors

Status	Code	When
`429`	`RATE_LIMITED_UPSTREAM`	Too many requests in a short burst — retry after a few seconds
`502` / `503`	`UPSTREAM_ERROR` / `SERVICE_UNAVAILABLE`	Temporary problem fetching data from X — retry later

Failed calls are not charged.

Twitter Trends API — trends for one of these places