query with 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
UseGET /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 inwoeid for GET /trends or GET /x/trends. Omit
woeid or pass 1 for worldwide trends.
Global & Americas
1- Worldwide23424977- United States23424775- Canada23424900- Mexico23424768- Brazil
Europe
23424975- United Kingdom23424969- Turkey23424950- Spain23424829- Germany23424819- France
Asia
23424856- Japan23424848- India
Read a Regional Trends Snapshot
When you callGET /api/v1/trends, Xquik fetches the latest trending topics
for the requested WOEID. Results are cached briefly to keep responses fast.
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. Preserve null and missing
values. Never replace them with zero. A missing estimate does not mean nobody
posted about the topic.
Response:
count query parameter controls how many trends to return. Defaults to
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 timestampwoeid: the requested regionname: the visible topic or hashtagquery: the recommended tweet-search expressionrank: the current regional positiondescription: the optional topic contexttweetVolume: the optional public-post estimatepromotedContent: the optional promotion identifier
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. Usewoeid=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:
- Request the same
countfor each chosen WOEID. - Save the raw regional snapshot before enrichment.
- Compare each topic with its previous regional rank.
- Filter topics against your campaign or research scope.
- Search tweets only for relevant topic queries.
- Store matching tweets with the originating WOEID and rank.
- Alert only after your movement or relevance rule passes.
Search Tweets Behind a Trend
Fetch the top trend for a region, then search for tweets about it:#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. Preserve 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 forRetry-Afterbefore retrying.502: Retry the temporary read-service failure later.
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. Use1 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 requestedcount with each snapshot.
How Do I Find Tweets Behind a Trending Topic?
Pass the trend’squery to 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. Preserve that state in storage.
Use rank movement as a separate regional signal.
Can I Request City-Level Twitter Trends?
No. Xquik currently accepts Worldwide and 11 listed country WOEIDs. An unsupported city WOEID returns400 invalid_input.
How Many Trending Topics Can I Request?
Request1 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
Trends API Reference
Full endpoint reference with query parameters and response schema.
Billing & Usage
Subscription pricing, credits, and per-operation costs.