Twitter Trends Actor

This Apify Actor scrapes trending Twitter topics, providing access to historical and current trending data for different countries and time periods.

Description

The Twitter Trends Actor allows you to extract trending topics data from Twitter for any supported country and date. You can get trends for specific hours or entire days, and limit the number of results returned. The actor supports both single queries and batch processing for multiple requests.

Key Features:

• Scrape trends for 60+ countries or worldwide
• Historical data from May 15, 2024 onwards
• Hourly or daily trend data
• Configurable result limits (10-50 trends)
• Batch processing support
• Residential proxy usage for reliable scraping

Input Schema

The actor accepts the following input parameters:

Parameter	Type	Required	Description
country	string	No	Country code (e.g., 'united-states'). Leave empty for worldwide trends
date	string	No	Date in YYYY-MM-DD format or 'today'. Defaults to today
hour	integer	No	Specific hour (0-23 UTC) for hourly trends
limit	integer	No	Maximum trends to return (10-50). Defaults to 50
queries	array	No	Array of query objects for batch processing

Supported Countries

{
  "worldwide": "Worldwide",
  "algeria": "Algeria",
  "argentina": "Argentina",
  "australia": "Australia",
  "austria": "Austria",
  "bahrain": "Bahrain",
  "belarus": "Belarus",
  "belgium": "Belgium",
  "brazil": "Brazil",
  "canada": "Canada",
  "chile": "Chile",
  "colombia": "Colombia",
  "denmark": "Denmark",
  "dominican-republic": "Dominican Republic",
  "ecuador": "Ecuador",
  "egypt": "Egypt",
  "france": "France",
  "germany": "Germany",
  "ghana": "Ghana",
  "greece": "Greece",
  "guatemala": "Guatemala",
  "india": "India",
  "indonesia": "Indonesia",
  "ireland": "Ireland",
  "israel": "Israel",
  "italy": "Italy",
  "japan": "Japan",
  "jordan": "Jordan",
  "kenya": "Kenya",
  "korea": "Korea",
  "kuwait": "Kuwait",
  "latvia": "Latvia",
  "lebanon": "Lebanon",
  "malaysia": "Malaysia",
  "mexico": "Mexico",
  "netherlands": "Netherlands",
  "new-zealand": "New Zealand",
  "nigeria": "Nigeria",
  "norway": "Norway",
  "oman": "Oman",
  "pakistan": "Pakistan",
  "panama": "Panama",
  "peru": "Peru",
  "philippines": "Philippines",
  "poland": "Poland",
  "portugal": "Portugal",
  "puerto-rico": "Puerto Rico",
  "qatar": "Qatar",
  "russia": "Russia",
  "saudi-arabia": "Saudi Arabia",
  "singapore": "Singapore",
  "south-africa": "South Africa",
  "spain": "Spain",
  "sweden": "Sweden",
  "switzerland": "Switzerland",
  "thailand": "Thailand",
  "turkey": "Turkey",
  "ukraine": "Ukraine",
  "united-arab-emirates": "United Arab Emirates",
  "united-kingdom": "United Kingdom",
  "united-states": "United States",
  "venezuela": "Venezuela",
  "vietnam": "Vietnam"
}

Input Example

Single Query

{
  "country": "united-states",
  "date": "2024-12-01",
  "hour": 14,
  "limit": 25
}

Batch Processing (priority over single query if provided )

{
  "queries": [
    {
      "country": "united-states",
      "date": "today",
      "limit": 10
    },
    {
      "country": "united-kingdom", 
      "date": "2024-11-30",
      "hour": 12,
      "limit": 20
    },
    {
      "date": "today",
      "limit": 15
    }
  ]
}

Output Schema

The actor outputs a flat array where each item represents a single trending topic with the following structure:

Field	Type	Description
position	integer/null	Ranking position (1-50, null on error)
trend	string/null	The trending topic or hashtag
tweets	string/null	Number of tweets (formatted, e.g., "125K")
country	string	Country for trends
date	string	Date for trends
hour	integer/null	Hour for trends (null for daily)
limit	integer	Maximum trends requested
scraped_at	string	ISO timestamp when scraped
success	boolean	Whether scraping was successful
query	string	Query parameters used
error	string	Error message (only when success=false)

Output Example

[
  {
    "position": 1,
    "trend": "#MondayMotivation",
    "tweets": "125K",
    "country": "united-states",
    "date": "2024-12-01",
    "hour": 14,
    "limit": 25,
    "scraped_at": "2024-12-01T14:30:00Z",
    "success": true,
    "query": "country=united-states&date=2024-12-01&hour=14&limit=25"
  },
  {
    "position": 2,
    "trend": "Taylor Swift",
    "tweets": "89K",
    "country": "united-states", 
    "date": "2024-12-01",
    "hour": 14,
    "limit": 25,
    "scraped_at": "2024-12-01T14:30:00Z",
    "success": true,
    "query": "country=united-states&date=2024-12-01&hour=14&limit=25"
  },
  {
    "position": null,
    "trend": null,
    "tweets": null,
    "country": "invalid-country",
    "date": "2024-12-01",
    "hour": null,
    "limit": 20,
    "scraped_at": "2024-12-01T14:30:05Z",
    "success": false,
    "error": "Invalid country: invalid-country. Allowed: argentina, australia, ...",
    "query": "country=invalid-country&date=2024-12-01&limit=20"
  }
]