Trends by Location

Description

Retrieve the trending topics X shows worldwide, in a supported country, or at a location identified by its WOEID (Where On Earth ID).

Usage notes

Use country=US for the United States or country=IT for Italy. Country codes are two letters and case-insensitive. Omit both country and woeid for worldwide trends. Alternatively, use woeid=1 for worldwide or a supported country or city WOEID from /tw-v2/trends/locations. Supply only one location parameter; sending both returns 400. Not every country is supported, and an unsupported country code returns 404 instead of falling back to worldwide. If the country list is unavailable or invalid, the request returns 502 and is not billed. The response names the location X answered for. Trends are in X's order. tweetVolume is null when X does not report a volume, which is usually the case; do not read rank as volume. When X has no trends for a WOEID, TweetAPI checks X's location list: a 404 means the list confirmed the WOEID is not supported. If that can't be confirmed, for example because the list is unavailable or still includes the WOEID, the request returns 502 and is not billed. The response is not paginated.

A request costs one API unit. 400, 401, 403, 429 and 5xx errors are free; a 404 is billed.

Query Parameters

Code Examples

const params = new URLSearchParams({
  country: 'US'
});

const response = await fetch(`https://api.tweetapi.com/tw-v2/trends?${params}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

Response

Success Response (200 OK)

Synthetic example:

{
  "data": {
    "location": {
      "woeid": 23424977,
      "name": "United States"
    },
    "asOf": "2026-10-28T10:02:56Z",
    "createdAt": "2026-10-26T21:57:22Z",
    "trends": [
      {
        "name": "#SampleTag",
        "query": "#SampleTag",
        "url": "http://twitter.com/search?q=%23SampleTag",
        "promoted": false,
        "tweetVolume": null
      },
      {
        "name": "Sample Phrase",
        "query": "\"Sample Phrase\"",
        "url": "http://twitter.com/search?q=%22Sample+Phrase%22",
        "promoted": false,
        "tweetVolume": 12345
      }
    ]
  }
}

location is the place X answered for. asOf and createdAt are X's timestamps and do not prove how recent each trend is. url is the search link X sends.

Errors

Errors return { statusCode, message } with a non-2xx HTTP status.

Malformed country codes, malformed WOEIDs, or supplying both parameters return an unbilled 400. A country code or WOEID that X's location list confirms is unsupported returns 404, which is billed. An unavailable or invalid country list returns an unbilled 502. If X answers for a different location than the one requested, or the WOEID can't be confirmed as unsupported, the request returns 502 and is not billed.

{
  "statusCode": 400,
  "message": "Request validation failed"
}

TweetAPI is a third-party API and is not affiliated with X Corp.