Twitter Trends API (X Trends)

Twitter Trends API — get what's trending on X (Twitter) worldwide or in any of ~470 countries and cities by WOEID. JSON, $0.01 per call.

POST/v1/twitter/trends

$0.01/call

The Twitter Trends API returns the trending topics on X for a place, identified by its WOEID: 1 for worldwide, 23424977 for the United States, or any of the ~470 countries and cities listed by Trend Locations. Each trend comes with a ready-to-use search query you can pass to the Twitter Search API.

Usage

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

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

import requests

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

Request Body

Parameter	Type	Required	Description	Default
`woeid`	`number`	No	WOEID of the place — `1` = worldwide, `23424977` = United States. See `/v1/twitter/trends-locations`	`1`

Response

{
  "ok": true,
  "data": {
    "as_of": "2026-10-31T01:10:52Z",
    "location": {
      "name": "Worldwide",
      "woeid": 1
    },
    "trends": [
      {
        "name": "ハッピーハロウィン",
        "query": "ハッピーハロウィン",
        "tweet_volume": null,
        "url": "https://x.com/search?q=%E3%83%8F%E3%83%83%E3%83%94%E3%83%BC%E3%83%8F%E3%83%AD%E3%82%A6%E3%82%A3%E3%83%B3"
      },
      {
        "name": "Happy Halloween",
        "query": "\"Happy+Halloween\"",
        "tweet_volume": null,
        "url": "https://x.com/search?q=%22Happy+Halloween%22"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`data.location.name`	`string`	Place name
`data.location.woeid`	`number`	Place WOEID
`data.as_of`	`string`	When X computed the list, ISO 8601
`data.trends`	`object[]`	Trending topics, most prominent first
`data.trends[].name`	`string`	Trend as displayed
`data.trends[].query`	`string`	URL-encoded search query for the trend
`data.trends[].url`	`string`	x.com search URL
`data.trends[].tweet_volume`	`number \| null`	Tweet volume when X reports it (often `null`)

Caching

Responses are cached for 10 minutes.

Errors

Status	Code	When
`404`	`NOT_FOUND`	No trends for this WOEID — use a place from Trend Locations
`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.

Trend Locations — every supported place and its WOEID
Twitter Search API — tweets for any trend