X Trends
X trends are a location-keyed snapshot of public topics available for a numeric WOEID, with the source name, rank, query, description, and collection time kept together. This structure supports regional topic discovery and repeated observation while making clear that each record reflects collection time rather than a historical trend series.
Features
- Location-keyed collectionRequest current public trends for one or more known numeric WOEIDs and retain the originating identifier in extra.woeid.
- Source ranking preservedKeep the upstream rank in metrics.rank when it is available without replacing it with a SocQ-calculated score.
- Useful trend contextReceive the trend name with an upstream query and provider description when those fields are exposed.
- Independent caps per locationApply results_limit separately to every submitted WOEID while collecting each location's currently available trend set once.
Parameters
| Parameters | Required | Description |
|---|---|---|
woeids | Required | Required array of one or more known X location identifiers, each represented as a non-empty numeric string. |
results_limit | Optional | Optional integer cap applied separately to each WOEID. Defaults to 100 and accepts values from 20 through 2,000. |
How to Use
Start with numeric WOEIDs you already know, choose a per-location cap, and treat the returned records as a collection-time snapshot.
- Enter one or more known WOEIDs as numeric strings; this endpoint does not resolve place names.
- Choose an integer results_limit from 20 to 2,000, or keep the default of 100 per WOEID.
- POST the request to /v1/x/trends, then poll /v1/tasks/{task_id} until the task succeeds.
- Read data.results.items and follow the task result next_cursor while has_more is true.
curl -X POST "https://api.socq.ai/v1/x/trends" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"woeids":["1"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Watch topics in a known market: Collect the current names, ranks, and descriptions associated with a location identifier your monitoring system already maintains.
- Build recurring observation snapshots: Run the same WOEID on a schedule you control and store collected_at with every result for later change analysis.
- Create a topic-review queue: Use the returned name, query, rank, and description to prioritize public topics for analyst review or a downstream discovery workflow.
Pro Tips
- Prepare numeric WOEIDs before submitting a task; place names and free-text locations are not accepted.
- The provided default 1 follows the backend's published request example; replace it with the identifier that matches your intended scope.
- Treat results_limit as a per-WOEID ceiling because a current trend set can contain fewer rows than requested.
- Run overlapping locations in separate tasks when retaining every trend-to-location association matters, because identical trend names can deduplicate within one task.
- Use collected_at as the observation time; created_at is null because the source does not expose a trend creation timestamp.
- Task result cursors page already saved records and do not request another page of trends from the provider.
Related APIs
Use these APIs when you need a different type of public X data.
- Twitter Tweet Scraper API — Retrieve public post text, authors, engagement, media, hashtags, mentions, and conversation relationships from x.com or twitter.com status URLs.
- Twitter Profile Scraper API — Retrieve public account identity, biographies, avatars, cover images, account status, and visible audience statistics by username.
- Twitter User Tweets Scraper API — Collect recent public posts, authors, media, hashtags, mentions, and engagement by username with replies excluded.
- Twitter Search API — Find public posts by search expression with latest or top ordering and a configurable result limit.
- X Followers List API — Collect public follower account identities and visible profile metrics for one or more X usernames.
- X Following List API — Collect profiles followed by public X accounts, including identity, biographies, account signals, visible counters, and source usernames.
- X Post Quotes API — Collect public quote posts for known status URLs with commentary, authors, engagement, media, timestamps, and source-post context.
- X Post Replies API — Collect public replies from X post URLs with selectable ordering, reply text, authors, visible engagement, media, and parent-post context.
- X Post Retweeters API — Collect a task-level unique set of normalized public profiles for accounts that reposted known X or Twitter status URLs.