Use X Trends Lookup by Country, City & WOEID with Python

Get ranked trending topics on X for any country or city, or for all 467 locations at once, with trend type, ready-made search links and post volumes when X publishes them.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "allLocations": false,
  "dedupeAcrossLocations": false,
  "excludeHashtags": false,
  "includeSearchUrls": true,
  "locations": [
    "Worldwide"
  ],
  "maxTrendsPerLocation": 3,
  "mode": "trends",
  "placeTypeFilter": "all",
  "trendNameContains": []
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`mode`	string	required	Choose whether to collect the current trends or list the places X publishes trends for.
`locations`	array	optional	Countries, cities, country codes, slugs or WOEIDs (mode=trends). Examples: Worldwide, United States, US, United Kingdom, GB, London, Tokyo, sao-paulo, 23424977. Put "all" to collect every location. Add a country after a comma when two places share a name, for example "Barcelona, ES".
`allLocations`	boolean	optional	Collect trends for every place X serves (currently 467 countries and cities, up to 50 trends each). When enabled, the Locations list is ignored.
`maxTrendsPerLocation`	integer	optional	How many ranked trends to keep for each location. X publishes up to 50.
`excludeHashtags`	boolean	optional	Skip trends that start with #. X applies this filter before returning the list.
`trendNameContains`	array	optional	Optional case-insensitive keyword filter. A trend is kept when its name contains at least one of these words. Useful for brand or topic monitoring.
`dedupeAcrossLocations`	boolean	optional	When the same trend appears in several requested locations, keep one row with all locations and the best rank instead of one row per location.
`includeSearchUrls`	boolean	optional	Include a ready-made X search link for every trend.
`placeTypeFilter`	string	optional	Limit the location list to countries, cities and towns, the worldwide entry, or X's unknown place type.
`proxyConfiguration`	object	optional	Optional. Use a proxy if you plan very large or repeated runs.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/mipelXF4sTs2Hzgga/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Ranked X trends per location, with trend type, search links, cross-location overlap and catalog metadata, plus location-list rows and problem status rows.

Questions before you run

Which inputs are required?

The published required fields are mode

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build OmGd5pPiMJWniHoUW and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.