How do I get Twitter trending topics for a specific country through an API?

A social team in Jakarta wants Indonesia's X trends in their channel at 8 every morning, so they can jump on a topic before lunch. X trending topics takes country=ID and returns the board as X shows it for that country: rank, the trend's name, its post volume when X displays one, and a search link. No WOEID lookup, no X developer account.

Countries

Pass a two-letter ISO code: US, GB, CA, AU, IN, JP, KR, ID, PH, MY, SG, AE, SA, TR, RU, DE, FR, ES, IT, NL, BR, MX or AR. Leave country out for worldwide trends. Any other code is answered with invalid_params, which is not charged, and the message lists the codes that work. City-level trends are not offered.

Cost of a schedule

Schedule	Calls	Cost
One country, once a day for a year	365	$3.285
One country, every hour for 30 days	720	$6.48
Five countries, daily for 30 days	150	$1.35

A morning job

import csv, datetime, os, requests

API = "https://api.okdata.online/v1"
H = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}

def trends(country):
    body = requests.get(f"{API}/x/trends/list", headers=H, params={"country": country}, timeout=60).json()
    if body["code"] != "ok":
        raise RuntimeError(f"{body['code']}: {body['message']}")
    return body["data"]["items"]

today = datetime.date.today().isoformat()
with open("x-trends.csv", "a", newline="", encoding="utf-8") as f:
    w = csv.writer(f)
    for country in ["ID", "MY", "PH"]:
        for t in trends(country):
            w.writerow([today, country, t["rank"], t["name"], t["heat"], t["url"]])

Run it from cron. The file becomes a dated archive you can chart later, which X itself does not keep for you.

Find out what a trend is about

A trend name alone is often cryptic. Pass it to X post search with sort=top and read the first page ($0.006) to see the posts driving it.

Gotchas

• heat is null when X shows no post count for a trend.
• The board is a snapshot. Trends can come and go within an hour, so store what you saw with the time.
• These are the public country trends. The personalised For you list is not available.

The official route

X's API serves trends by WOEID, a Yahoo place ID (Indonesia is 23424846), and charges $0.010 per trends request under pay-per-use. If you already hold an X developer account and need just one country, that is a fine option. For several countries on a schedule without a developer account, the ISO code is simpler. The trend research guide combines trends with search into one workflow.