# Twitter/X Trends Scraper & Intelligence (`zapticx/twitter-x-trends-scraper-intelligence`) Actor

Scrape real-time Twitter/X trends from countries and cities. Get rankings, WOEIDs, trend scores, cross-location insights, and analysis-ready data.

- **URL**: https://apify.com/zapticx/twitter-x-trends-scraper-intelligence.md
- **Developed by:** [Zapticx](https://apify.com/zapticx) (community)
- **Categories:** Automation, Social media, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.09 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Twitter/X Trends Scraper & Intelligence

Discover current Twitter/X trending topics across countries and individual cities, then receive clean, analysis-ready data in seconds. This Twitter trends scraper supports multi-location collection across hundreds of X-supported geographic locations in a single run.

No X account, login, cookie, or personal API token is required. Lightweight direct HTTP collection returns ranked real-time trends, trending hashtags, location metadata, and transparent trend intelligence for cross-location analysis.

### What does it do?

Twitter/X Trends Scraper & Intelligence retrieves up to 50 current trends for every selected location. Each trend is a separate flat dataset row containing its rank, location, WOEID, country metadata, hashtag and promotion status, available post volume, X search link, timestamp, and transparent derived metrics.

Use it as an X trends scraper in Apify Console or as a practical Twitter trends API through the Apify API and automated workflows.

### Features

- Current Twitter/X trending topics from Worldwide, countries, and cities
- Multiple locations in one run with controlled concurrency
- Dynamic WOEID-backed coverage of hundreds of X-supported locations
- Post volume when X provides it; omitted values are clearly marked and never fabricated
- Rank, hashtag detection, promoted status, and URL-encoded X search links
- Derived `trendScore`, `normalizedVolume`, `locationCount`, `locationsTrending`, and `globalReachScore`
- Optional cross-location deduplication without losing location coverage
- No X username, password, account cookie, or user API token required
- JSON, JSONL, CSV, XML, RSS, and Excel-compatible dataset exports
- Partial results when an individual location fails
- Bounded retries, exponential backoff, and Apify Proxy support
- Pay-Per-Event compatible output

### Supported locations

Collect trends by country, trends by city, Worldwide trends, or use numeric WOEIDs in advanced workflows. The Actor loads X's WOEID-backed location catalog dynamically and merges it with a bundled fallback, so coverage is not limited to a short hard-coded list.

Recent live tests loaded **467 X-supported locations**. X can change this catalog, so the exact count may vary over time. Verified examples from the current live or fallback catalog include:

- **Global:** Worldwide
- **North America:** United States, New York, Los Angeles, Canada, Toronto, Mexico
- **Europe:** United Kingdom, London, Germany, France
- **South Asia:** Pakistan, Karachi, Lahore, India, Mumbai, Delhi
- **Asia-Pacific:** Australia, Japan
- **Middle East:** United Arab Emirates, Dubai, Saudi Arabia
- **Other regions:** Brazil, South Africa

Location names are case-insensitive. If the same city name exists in more than one country, enter its numeric WOEID to remove ambiguity. Unsupported names fail before trend collection rather than silently returning the wrong region.

### See the output

The default dataset is flat, readable, and ready to export or connect to another workflow. The example below is a real multi-location run in Apify Console.

![Twitter/X trend results in the Apify dataset](https://api.apify.com/v2/key-value-stores/2GaHrldcuefUXGtnS/records/sample-output.png?signature=IzCn7Yvn09iV6KIZPmcw)

Each row is one trend in one location. `tweetVolume` remains `null` when X does not provide it; the Actor never fabricates missing volume.

### Use cases

- Social media and breaking-news monitoring
- Marketing research and hashtag discovery
- Regional trend and market intelligence
- Content ideation and automated reporting
- Comparing attention across countries and cities
- Monitoring brand or competitor-adjacent conversations

### Input

The main input is `locations`, a list of human-readable place names. Names are case-insensitive. Numeric WOEIDs are also accepted for advanced workflows. Duplicate locations are removed before requests are made.

```json
{
  "locations": ["Worldwide", "Pakistan", "Karachi", "United States"],
  "maxTrendsPerLocation": 50,
  "includeTweetVolume": true,
  "includeSearchUrl": true,
  "includeTrendIntelligence": true,
  "deduplicateAcrossLocations": false,
  "sortBy": "rank"
}
```

| Field | Default | Description |
| ----- | ------- | ----------- |
| `locations` | `["Worldwide"]` | Country names, city names, or numeric WOEIDs |
| `maxTrendsPerLocation` | `50` | From 1 to 50 trends per location |
| `includeTweetVolume` | `true` | Include volume and availability fields |
| `includeSearchUrl` | `true` | Include an encoded X search URL |
| `includeTrendIntelligence` | `true` | Include score and normalized volume |
| `deduplicateAcrossLocations` | `false` | Keep one row per trend and preserve all matching locations |
| `sortBy` | `rank` | `rank`, `tweetVolume`, or `trendScore` |
| `proxyConfiguration` | disabled | Optional Apify Proxy configuration |
| `debug` | `false` | Enable more diagnostic logging; secrets are never logged |

Useful presets:

```json
{"locations":["Worldwide"]}
```

```json
{"locations":["United States","United Kingdom","Pakistan","India"]}
```

```json
{"locations":["Pakistan","Karachi","Lahore"]}
```

### Output

The Actor writes validated results to the default Apify dataset. Important fields include:

| Field | Description |
| ----- | ----------- |
| `trend` | Trend phrase, topic, cashtag, or hashtag |
| `rank` | Position within the selected location |
| `tweetVolume` | Approximate volume supplied by X, or `null` |
| `locationName`, `countryName` | Human-readable geographic context |
| `locationWoeid` | X/Yahoo Where On Earth identifier |
| `isHashtag`, `isPromoted` | Classification flags |
| `trendScore` | Transparent 0–100 score derived from rank and available volume |
| `searchUrl` | URL-encoded link to the topic on X |
| `scrapedAt` | UTC snapshot timestamp |

```json
{
  "trend": "#AI",
  "rank": 1,
  "tweetVolume": 125000,
  "tweetVolumeAvailable": true,
  "isHashtag": true,
  "isPromoted": false,
  "searchUrl": "https://x.com/search?q=%23AI",
  "locationName": "Pakistan",
  "locationWoeid": 23424922,
  "locationType": "country",
  "countryName": "Pakistan",
  "countryCode": "PK",
  "trendScore": 100.0,
  "normalizedVolume": 1.0,
  "locationCount": 2,
  "locationsTrending": ["Pakistan", "Karachi"],
  "globalReachScore": 0.5,
  "scrapedAt": "2026-08-19T14:00:00Z"
}
```

`globalReachScore` is `locationCount / successfully retrieved locations`. When deduplication is enabled, the retained row uses the requested sort criterion while `locationsTrending` still lists every matching location.

### Trend intelligence

Trend intelligence is calculated by this Actor. These are **derived Actor metrics, not official X metrics**:

- `trendScore` is a transparent 0–100 measure based on relative rank and available volume.
- `normalizedVolume` compares a trend's supplied volume with the largest supplied volume in the same location.
- `locationCount` records how many successfully retrieved locations contain a trend.
- `locationsTrending` preserves the names of those locations.
- `globalReachScore` is `locationCount / successfully retrieved locations`.

With cross-location deduplication enabled, the Actor returns one row per trend while retaining `locationsTrending`, `locationCount`, and the requested sort criterion.

When volume is available, the score is 75% relative rank strength and 25% logarithmic volume strength relative to that location's largest trend. Logarithmic scaling prevents one unusually large trend from overwhelming all other results. When X omits volume, the score uses rank alone so missing upstream data does not unfairly lower a trend. Scores range from 0 to 100.

`normalizedVolume` is the trend volume divided by the largest available volume in the same location. It is `null` when volume is unavailable.

### Tweet volume limitations

X currently does not provide post-volume counts for many trends through the upstream trends data used by this Actor. When X omits the value, `tweetVolume` is `null` and `tweetVolumeAvailable` is `false`. The Actor never estimates or fabricates missing volume.

```json
{"tweetVolume":null,"tweetVolumeAvailable":false}
```

The field historically called `tweet_volume` by X represents an approximate post count, despite the current “post” terminology.

### Integrations and exports

Use the default dataset through Apify API or clients for Python and JavaScript. Dataset results can also feed Make, n8n, Zapier, Google Sheets, or any system that accepts JSON/CSV. Mentioning these tools describes compatible workflow options; it does not imply an official partnership.

### Scheduling and historical tracking

Every row has a UTC `scrapedAt` snapshot timestamp. Schedule the Actor hourly, daily, or at another interval with Apify Schedules and retain each dataset to build your own historical series.

V1 does not claim persistent cross-run history, velocity, or first-seen times. Those require comparing saved snapshots.

### Pricing

This Actor uses Apify's Pay Per Event model:

- **Actor start:** $0.001 per run
- **Results:** $0.09 per 1,000 dataset items ($0.00009 per result)
- **Platform usage:** included—you do not pay separate platform usage costs for this Actor

Estimated run price is `$0.001 + (dataset items × $0.00009)`. For example, a 50-result Worldwide run costs approximately **$0.0055**, and a 250-result run costs approximately **$0.0235**. Failed locations do not create result items, and fewer returned trends mean fewer billable results.

See the Pricing tab on the Actor page for the current pricing. Apify shows the final estimated or charged amount in Console.

### Reliability notes

The Actor uses the public guest session used by X's logged-out web client and calls X's WOEID trends endpoint directly. It does not use the paid official developer API and is not guaranteed by X. Upstream access can change; session, transport, and parsing logic are deliberately isolated for quick maintenance. Requests use finite retries and backoff. A failed location does not discard successful locations from the same run.

### FAQ

**Does this require a Twitter/X account?**\
No. You do not provide an account, cookie, password, or personal bearer token.

**Does this use the official paid X API?**\
No. It uses endpoints available to X's logged-out web client. They can change independently of documented developer APIs.

**Why is tweet volume often missing?**\
X currently omits volume for many trends through this upstream source. Missing values remain `null`, with `tweetVolumeAvailable` set to `false`.

**Can I retrieve multiple countries and cities?**\
Yes. Mix Worldwide, country names, city names, and advanced WOEIDs in one run.

**Can I schedule it?**\
Yes. Use Apify Schedules to create periodic snapshots.

**Can I export CSV, Excel, or JSON?**\
Yes. The flat dataset is designed for those exports and automation tools.

**Can I use it from Make or n8n?**\
Yes. Start a run through Apify integrations/API and consume its default dataset.

### Legal and responsibility

Twitter/X Trends Scraper & Intelligence is an independent tool and is not affiliated with or endorsed by X Corp. Users are responsible for using the Actor and its public trend data in compliance with applicable laws and platform requirements.

# Actor input Schema

## `locations` (type: `array`):

Countries and cities to retrieve. Duplicate entries are processed only once.

## `maxTrendsPerLocation` (type: `integer`):

Maximum number of ranked trends returned for each location.

## `includeTweetVolume` (type: `boolean`):

Include X's estimated post volume when X supplies it.

## `includeSearchUrl` (type: `boolean`):

Add a correctly encoded X search link for every trend.

## `includeTrendIntelligence` (type: `boolean`):

Calculate the Actor's transparent trend score and normalized volume.

## `deduplicateAcrossLocations` (type: `boolean`):

Return one row per trend while preserving locationsTrending and locationCount.

## `sortBy` (type: `string`):

Rank sorts ascending; volume and score sort highest first.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy settings. Residential proxies are not required by default.

## `debug` (type: `boolean`):

Enable additional diagnostics. Authentication and proxy secrets are never logged.

## Actor input object example

```json
{
  "locations": [
    "Worldwide"
  ],
  "maxTrendsPerLocation": 50,
  "includeTweetVolume": true,
  "includeSearchUrl": true,
  "includeTrendIntelligence": true,
  "deduplicateAcrossLocations": false,
  "sortBy": "rank",
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "debug": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

Validated trend records in the run's default dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        "Worldwide"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zapticx/twitter-x-trends-scraper-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "locations": ["Worldwide"] }

# Run the Actor and wait for it to finish
run = client.actor("zapticx/twitter-x-trends-scraper-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    "Worldwide"
  ]
}' |
apify call zapticx/twitter-x-trends-scraper-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zapticx/twitter-x-trends-scraper-intelligence"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/VWSEr3RszOxOuEws4/builds/2bZtmFIWbOfD97eYv/openapi.json