Timeline & DMs
Twitter trends API by region, WOEID & search
Get Twitter and X trends for a country, town, or WOEID. Return ranked topics, hashtags, search queries, descriptions, and tweet volume. 3 credits per call.
- 200
- 400
- 401
- 402
- 424
- 429
- 502
- 503
GET
Twitter trends API by region, WOEID & search
GET /x/trends to retrieve X’s ranked trends for a place you choose.
Pick the place by country, location, or woeid. Without one, trends are worldwide.
Use trends for planning, monitor setup, search jobs, and alerts.
Each example emits one JSON record for every returned trend.
Store trend_name for every result.
Keep rank, description, and query when the response includes them.
Leave omitted fields unset. Use the trend name when query is missing.
Also store region_woeid, returned_count, and your own detected_at timestamp.
Pass search_query to Search Tweets for matching tweets.
Save each snapshot before you search.
Build a regional trend monitor
Poll one WOEID on a consistent schedule. Store every trend name and returned optional field. Keep missing values unset. KeeptweetVolume as null when X returns null.
Compare ranks within the same region. Do not mix worldwide and country results
inside one ranking. Keep the WOEID on every row.
Use the returned search query to retrieve matching tweets. Keep the trend
snapshot before starting that search. Each tweet batch then links to the
regional topic that started it.
Missing tweet volume means unknown. Do not convert it to 0. X may omit
that field for some trends.
Query parameters
integer
Positive Where On Earth ID for the region. It wins over
country and location. Invalid or nonpositive values fall back to those names, then to 1 (worldwide). See Trends guide for common regions, or List trend locations for every place.string
Country to read trends for, by name or 2-letter code, such as
Turkey or TR. Case insensitive.string
Town or country to read trends for, by name, such as
Istanbul. Case insensitive. Add country when 2 towns share a name. List trend locations returns every name.integer
Number of trends to return. Default
30, max 50. Invalid or below-minimum values fall back to 30.Headers
string
Send a full Xquik account API key.
string
Bearer xq_your_guest_key_here authenticates paid_reads guest keys through the API-key scheme’s Bearer alias. Direct MPP uses the Payment ... credential from the WWW-Authenticate: Payment challenge.Response
200 OK
object[]
Array of trending topics.
Trend object fields.
string
Trend name or hashtag.
number
Trend rank. Omitted if unavailable.
string
Trend description. Omitted if unavailable.
string
Search query for this trend. Omitted if unavailable.
string | null
Promotion identifier. Null for organic trends.
number | null
Approximate public post volume when X supplies it.
string
X search URL for the trend.
number
Number of trends returned.
number
WOEID used for the request.
object
The place
country or location named, with the fields of a trend location. Absent when woeid picked the place or the request named none.location=Istanbul also names the place it read:
400 Unknown place
country or location. The request costs nothing.
401 Unauthenticated
402 Payment required
Account keys receive account payment options. Guest keys receive only the guest top-up action. Anonymous calls receiveWWW-Authenticate: Payment plus a guest wallet action.
Failed requests never create checkout. Confirm a payment option first.
502 X API unavailable
429 Rate limit exceeded
Retry-After when present. Otherwise, use the JSON retryAfter field.
424 Dependency failed
xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.
Twitter trends API questions
How do I get Twitter trends programmatically?
CallGET /x/trends with a country, a location, or a woeid, and a result count.
Read each trend’s name, rank, query, description, and available tweet volume.
Can I get Twitter trends by country or city name?
Yes. Sendcountry=TR or location=Istanbul. Names ignore case.
The response returns the place it read as location.
Can I track trending hashtags by region?
Yes. Poll the same WOEID on a stable schedule. Compare ranks within the same region. Save each detection time. Usequery to search tweets related to each trending hashtag.
Use the trend name when the response omits query.
How do I authenticate to the Twitter trends API?
Send an Xquik API key or OAuth bearer token. Apaid_reads guest key can use the API-key scheme’s Bearer alias.
For direct MPP, anonymous requests get a payment challenge.
How much does a trends request cost?
The pricing callout above shows the current credit and direct MPP cost. Failed requests return a documented error without creating checkout.How do I build trend tracking into an app?
Schedule one regional request, then store each returned snapshot. Compare the latest ranks with the previous snapshot. Send rank changes you care about to a dashboard, monitor, or alert queue.Does this replace X’s official API?
No. This page documents Xquik, an independent third-party service. It does not document X’s official API.This endpoint returns trends directly from X. For broader Radar topic discovery, use List Radar Items.
Next steps. Search Tweets to find tweets about a trending topic.