> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Twitter trends API guide by region & WOEID
> Find ranked X trends by WOEID region, keep each trend query and its rank, then search matching tweets with cursor pagination. Includes exact API steps.
For the complete documentation index, see llms.txt.
Xquik returns ranked X trends for 12 supported WOEID regions. Use each trend's
`query` with [Search Tweets](/api-reference/x/search-tweets) to collect matching
posts.
Use this Twitter trends guide for regional topic discovery and monitoring.
Each call returns one current snapshot. Store snapshots to build trend history.
## Choose the trends endpoint
Use `GET /api/v1/trends` for the top-level Twitter Trends API response.
It returns `trends`, `total`, and `woeid`.
Use `GET /api/v1/x/trends` for the equivalent X API route.
It returns `trends`, `count`, and `woeid`.
Keep one response shape throughout each client. This prevents `total` and
`count` from becoming competing fields in stored snapshots.
## Regions
Use these WOEIDs in `woeid` for `GET /trends` or `GET /x/trends`. Omit
`woeid` or pass `1` for worldwide trends.
* `1` - Worldwide
* `23424977` - United States
* `23424775` - Canada
* `23424900` - Mexico
* `23424768` - Brazil
* `23424975` - United Kingdom
* `23424969` - Turkey
* `23424950` - Spain
* `23424829` - Germany
* `23424819` - France
* `23424856` - Japan
* `23424848` - India
`GET /x/trends` also takes the WOEID of any other place X offers trends for.
[List trend locations](/api-reference/x/trend-locations) returns every place with its WOEID.
You can name the place instead. Send `country=TR`, or `location=Istanbul` for a town.
The response returns the place it read as `location`.
## Read a regional trends snapshot
When you call `GET /api/v1/trends`, Xquik fetches the latest trending topics
for the requested WOEID. Xquik caches results briefly.
Each trend includes a `name`, optional `description`, optional `rank`, and
optional `query` string. Rich responses can also include `promotedContent`,
`tweetVolume`, and `url`.
Use `name` as the visible topic or hashtag. Use `rank` for regional ordering.
Use `query` for a follow-up tweet search. Fall back to `name` when `query` is
missing.
Treat `tweetVolume` as an optional estimate. Keep `null` and missing
values. Never replace them with 0. A missing estimate does not mean nobody
posted about the topic.
**Response.**
```json theme={null}
{
"woeid": 23424977,
"total": 30,
"trends": [
{
"name": "#AI",
"description": "Artificial Intelligence discussions",
"rank": 1,
"query": "#AI"
}
]
}
```
The `count` query parameter controls how many trends to return. The default is
`30`. Valid values are `1` through `50`.
## Compare Twitter topic trends over time
The trends endpoints return current snapshots. They do not return stored
history. Create history by saving each regional response on your schedule.
Store these fields for every snapshot:
* `captured_at`: your UTC collection timestamp
* `woeid`: the requested region
* `name`: the visible topic or hashtag
* `query`: the recommended tweet-search expression
* `rank`: the current regional position
* `description`: the optional topic context
* `tweetVolume`: the optional public-post estimate
* `promotedContent`: the optional promotion identifier
Compare normalized `name` values within the same WOEID. Track `first_seen`,
`last_seen`, `current_rank`, `previous_rank`, and `best_rank`. Keep every
snapshot immutable. Derived movement can change when late jobs arrive.
An absent topic only left the requested result slice. It may still appear
below your selected `count`. Increase `count` before treating absence as a
meaningful change.
## Build a multi-region Twitter trends monitor
Choose only the regions that match your market. Poll each WOEID independently.
Store the WOEID beside every trend row. Never compare ranks across regions as
if they share one list.
Use `woeid=1` for a worldwide snapshot. Use country WOEIDs for regional
comparisons. Xquik supports the 12 WOEIDs listed above. Unsupported country or
city identifiers return `400 invalid_input`.
A practical monitor follows this sequence:
1. Request the same `count` for each chosen WOEID.
2. Save the raw regional snapshot before enrichment.
3. Compare each topic with its previous regional rank.
4. Filter topics against your campaign or research scope.
5. Search tweets only for relevant topic queries.
6. Store matching tweets with the originating WOEID and rank.
7. Alert only after your movement or relevance rule passes.
This sequence keeps unrelated trends out of tweet searches. It also records
why every topic entered a dashboard, alert, or AI summary.
## Search tweets behind a trend
Fetch the top trend for a region, then search for tweets about it:
```bash cURL theme={null}
# 1. Get top trend
TREND=$(curl -s "https://xquik.com/api/v1/trends?woeid=23424977&count=1" \
-H "x-api-key: xq_YOUR_KEY_HERE" \
| jq -r '.trends[0].query')
# 2. Search tweets about it
curl -G "https://xquik.com/api/v1/x/tweets/search" \
--data-urlencode "q=$TREND" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
```javascript Node.js theme={null}
const API_KEY = "xq_YOUR_KEY_HERE";
const headers = { "x-api-key": API_KEY };
// 1. Get top trend
const trendsRes = await fetch("https://xquik.com/api/v1/trends?woeid=23424977&count=1", {
headers,
});
const trendsData = await trendsRes.json();
const query = trendsData.trends[0].query;
// 2. Search tweets about it
const searchRes = await fetch(
`https://xquik.com/api/v1/x/tweets/search?q=${encodeURIComponent(query)}`,
{ headers },
);
const searchData = await searchRes.json();
console.log(searchData);
```
```python Python theme={null}
import requests
API_KEY = "xq_YOUR_KEY_HERE"
headers = {"x-api-key": API_KEY}
# 1. Get top trend
trends_res = requests.get(
"https://xquik.com/api/v1/trends",
params={"woeid": 23424977, "count": 1},
headers=headers,
)
query = trends_res.json()["trends"][0]["query"]
# 2. Search tweets about it
search_res = requests.get(
"https://xquik.com/api/v1/x/tweets/search",
params={"q": query},
headers=headers,
)
print(search_res.json())
```
```go Go theme={null}
package main
import (
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"net/url"
)
const apiKey = "xq_YOUR_KEY_HERE"
func main() {
// 1. Get top trend
req, err := http.NewRequest("GET", "https://xquik.com/api/v1/trends?woeid=23424977&count=1", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("x-api-key", apiKey)
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
var trends struct {
Trends []struct {
Query string `json:"query"`
} `json:"trends"`
}
json.Unmarshal(body, &trends)
// 2. Search tweets about it
searchURL := "https://xquik.com/api/v1/x/tweets/search?q=" + url.QueryEscape(trends.Trends[0].Query)
req2, err := http.NewRequest("GET", searchURL, nil)
if err != nil {
log.Fatal(err)
}
req2.Header.Set("x-api-key", apiKey)
resp2, err := http.DefaultClient.Do(req2)
if err != nil {
log.Fatal(err)
}
defer resp2.Body.Close()
body2, err := io.ReadAll(resp2.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(body2))
}
```
The trend response supplies a raw search expression such as `#AI`.
`--data-urlencode` and `URLSearchParams` encode that expression once. Do not
manually encode it before using these examples.
Search results provide the tweets behind a selected topic. Keep each
tweet's ID, author, text, metrics, and creation time. Store the originating
trend name, WOEID, rank, and collection timestamp beside those tweets.
Use cursor pagination when you need more than one search page. Stop when the
response has no next cursor. Also stop when a cursor repeats.
## Handle trend request failures
Handle each documented status before scheduling another regional request.
* `400`: Use one of the 12 supported WOEIDs.
* `401`: Replace the missing or invalid credential.
* `402`: Top up credits or use an eligible paid read.
* `424`: Retry the temporary read-service dependency failure.
* `429`: Wait for `Retry-After` before retrying.
* `502`: Retry the temporary read-service failure later.
Use capped exponential backoff for `424`, `429`, and `502` responses. Do not
retry `400`, `401`, or `402` without changing the request or account state.
## Twitter trends API questions
### What is a WOEID in the Twitter trends API?
WOEID means Where On Earth ID. It selects one supported geographic trend list.
Use `1` for Worldwide. Use a listed country code for regional trends.
### How do I get Twitter trends by country?
Call either trends endpoint with that country's supported WOEID. Save the
returned WOEID with every rank. This prevents regional rows from mixing.
### Can I get historical Twitter trends?
The endpoint returns one current snapshot. Poll it and store timestamped
responses to build history. Keep the requested `count` with each snapshot.
### How do I find tweets behind a trending topic?
Pass the trend's `query` to [Search Tweets](/api-reference/x/search-tweets).
Use `name` only when `query` is missing. Paginate the matching tweet results.
### Does every trend include a public-post estimate?
No. `tweetVolume` can be missing or `null`. Keep that state in storage.
Use rank movement as a separate regional signal.
### Can I request city-level Twitter trends?
No. Xquik accepts Worldwide and 11 listed country WOEIDs. An
unsupported city WOEID returns `400 invalid_input`.
### How many trending topics can I request?
Request `1` through `50` topics. The default is `30`.
### Which endpoint should a new client use?
Choose the response shape your client already uses. `/trends` returns `total`.
`/x/trends` returns `count`. Both return ranked trends for one WOEID.
### Is Xquik the official X trends API?
No. Xquik is an independent third-party service. It is not affiliated with X
Corp. This guide documents Xquik endpoints and response fields.
## Next steps
Full endpoint reference with query parameters and response schema.
Subscription pricing, credits, and per-operation costs.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.