x-twitter-trends_skill

Overview

This skill helps you search and analyze trending topics on X (Twitter) from the command line. It provides quick commands to fetch worldwide or location-specific trends, list available trend locations, and query recent tweets for any trend. It’s focused on practical, scriptable workflows using twurl and jq.

How this skill works

The skill uses the Twitter/X trends endpoint (v1.1) via the twurl CLI to retrieve top trending topics by WOEID or coordinates. It can list available trend locations, find the closest location to coordinates, and use the v2 search endpoint to pull recent tweets for a given hashtag or trend. Output is intended for jq-driven parsing and automation.

When to use it

• When you need the current top trends globally or for a specific country/city.
• When you want to monitor brand-related hashtags or competing topics in realtime.
• When you need to collect sample tweets for a trending hashtag for analysis.
• When building scripts or dashboards that refresh trending data regularly.
• When comparing regional interest or identifying local conversation spikes.

Best practices

• Authenticate with twurl and keep API keys secure; twurl stores OAuth tokens locally.
• Respect rate limits (trends: ~75 requests / 15 min) and cache results to avoid throttling.
• Use jq to filter and extract only fields you need (name, tweet_volume, url).
• Prefer v2 search for richer tweet fields and filtering (media, verified, language).
• Resolve location using trends/available or trends/closest before frequent queries.

Example use cases

• Quickly fetch top 10 worldwide trends for a daily briefing script.
• Pull top trends for a country WOEID to tailor marketing messaging regionally.
• Find recent tweets with media for a trending hashtag to collect visual examples.
• Monitor competitors’ promoted topics or sudden spikes in tweet_volume.
• Build a local news alert that triggers when a specific keyword enters top trends.