# Twitter Trends Scraper (`khadinakbar/twitter-trends-scraper`) Actor

Collect X (Twitter) trending topics by country, city, or worldwide with historical snapshots, rank history, source URLs, and retrieval timestamps.

- **URL**: https://apify.com/khadinakbar/twitter-trends-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Social media, News, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 trend scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Trends Scraper | Real-time X Trending Topics by Country

Scrape real-time X (Twitter) trending topics by country, city, or worldwide with optional historical windows, multi-location batch input, and sparkline history. This Apify Actor accepts location targets and time-window settings, then returns one dataset record per trend per location per window. Each record includes the trend name, rank, location, window label, source links, and optional history so you can review what was trending and how the rank moved over time. It runs over HTTP via getdaytrends.com, requires no login, and is ready for use through Apify MCP.

### Best fit and connected workflows

This Actor fits workflows that need current or historical trend snapshots from X without building a browser scraper.

Use it when you want to:

- compare trends across several countries or cities in one run,
- pull a live Top 50 board for one location,
- review a past snapshot from 1h to 7d back,
- filter for hashtag-led trends,
- collapse repeated trend names across locations into one combined row,
- list supported locations as dataset rows for discovery workflows.

Because each row is tied to one location and one time window, the output works well as an input to dashboards, alerting logic, editorial planning, or AI agent pipelines that need structured trend data.

### Focused standalone workflow

Twitter Trends Scraper | Real-time X Trending Topics by Country is designed as a focused standalone workflow.

### Practical scenario

A social media manager starts with three locations: Worldwide, United States, and Japan. They choose the live window and keep the default history enabled. The dataset returns ranked trend rows with fields such as `name`, `rank`, `location`, `windowLabel`, `searchUrl`, and `history`. The manager sees that the same topic appears across multiple locations and decides to open the `searchUrl` for the top-ranked item in X search, then share the trend list with the content team for same-day post planning.

### Input fields

| Field | Type | Default | Description |
|---|---|---|---|
| `locations` | string\[] | `["worldwide"]` | Locations to scrape. Accepts slugs, display names, full getdaytrends URLs, or WOEID integers. |
| `window` | string | `now` | Snapshot to fetch. Use `now`, `1h`, `2h`, `3h`, `6h`, `12h`, `24h`, `2d`, `3d`, `7d`, or `custom`. |
| `customDateTime` | string | - | UTC timestamp used when `window` is `custom`. |
| `maxTrendsPerLocation` | integer | `50` | Maximum rows returned per location per window. |
| `hashtagOnly` | boolean | `false` | Return only trends that start with `#`. |
| `deduplicateAcrossLocations` | boolean | `false` | Collapse repeated trend names across locations into one row with `locations[]`. |
| `includeHistory` | boolean | `true` | Attach compact sparkline rank history when available. |
| `listAvailableLocations` | boolean | `false` | Return the supported location catalog as dataset rows instead of trend rows. |
| `proxyConfiguration` | object | Apify residential preset | Proxy settings for HTTP requests. |

### Focused input example

```json
{
  "locations": ["worldwide", "united-states", "japan"],
  "window": "now",
  "maxTrendsPerLocation": 20,
  "hashtagOnly": false,
  "deduplicateAcrossLocations": true,
  "includeHistory": true
}
```

### Output fields

| Field | Type | Description |
|---|---|---|
| `recordType` | string | Record type, set to `trend` for trend rows. |
| `rank` | integer | Position in the ranked list, where 1 is the top trend. |
| `name` | string | Trend name as displayed on X trends. |
| `hashtag` | boolean | Whether the trend starts with `#`. |
| `url` | string | getdaytrends detail page URL. |
| `searchUrl` | string | Direct X search URL for the trend. |
| `volume` | integer or null | Approximate tweet volume when derivable. |
| `volumeLabel` | string or null | Human-friendly volume label when available. |
| `category` | string or null | Category label when the source provides one. |
| `promoted` | boolean | Whether the trend is marked as promoted. |
| `location` | string | Human-friendly location label. |
| `locationSlug` | string | Source slug used to build the URL. |
| `woeid` | integer or null | WOEID for the location when known. |
| `windowLabel` | string | Snapshot label such as `Now`, `1h`, or `7d`. |
| `windowHoursBack` | integer | Hours back from now, where 0 means live. |
| `windowTimestamp` | string or null | ISO timestamp for the snapshot when available. |
| `history` | array | Compact rank-history samples parsed from the sparkline. |
| `source` | string | Source used for the record, such as `getdaytrends`. |
| `scrapedAt` | string | ISO timestamp when the row was scraped. |

### Illustrative output record

```json
{
  "recordType": "trend",
  "rank": 1,
  "name": "Example Trend",
  "hashtag": false,
  "url": "https://getdaytrends.com/worldwide/trend/Example-Trend/",
  "searchUrl": "https://x.com/search?q=Example%20Trend",
  "volume": null,
  "volumeLabel": null,
  "category": null,
  "promoted": false,
  "location": "Worldwide",
  "locationSlug": "worldwide",
  "woeid": 1,
  "windowLabel": "Now",
  "windowHoursBack": 0,
  "windowTimestamp": null,
  "history": [
    {
      "t": "2026-08-02T15:00:00.000Z",
      "rank": 1
    }
  ],
  "source": "getdaytrends",
  "scrapedAt": "2026-08-02T16:12:34.000Z"
}
```

### How it works

The Actor builds one getdaytrends URL per requested location and time window. It fetches server-rendered HTML over HTTP, then extracts trend rank, name, source URLs, and sparkline history from the page. The dataset stores one trend row per location per window, and the run summary is written to the key-value store for downstream review. The live contract also defines `OUTPUT` and `RUN_SUMMARY` records for run-evidence workflows.

### Pricing

Twitter Trends Scraper | Real-time X Trending Topics by Country uses Pay per event billing plus Apify platform usage.

- One event is charged when the Actor starts.
- One event is charged for each trend row written to the dataset.

For a simple example in words: if you request one location and receive fifty trend rows, the run is billed for one start event and fifty trend events, plus platform usage. For multi-location runs, the billed trend count scales with the number of returned rows across all selected locations and windows.

To review the current pricing details, open the live Pricing tab in the Apify Console. That tab shows the active event billing and platform usage information for this Actor.

### Use with AI agents (MCP)

This Actor is available through Apify MCP as a tool for retrieving structured X trend snapshots.

**Tool description:**

> Get structured X trending topics by location and time window. Returns ranked trend rows with optional history, location metadata, source links, and search URLs. Suitable for social monitoring, news tracking, editorial planning, and location-by-location comparison.

**Actor identity:** `khadinakbar/twitter-trends-scraper`

> "Fetch the live trend board for Worldwide, United States, and Japan. Return up to 20 rows per location, keep history on, and deduplicate repeated names across locations so I can compare the results quickly."

**How to interpret the output:**

- `rank` tells you the order within each location and window.
- `location`, `locationSlug`, and `woeid` identify where the trend was captured.
- `windowLabel` and `windowTimestamp` tell you which snapshot you received.
- `searchUrl` is useful for opening the topic directly in X search.
- `history[]` provides compact rank samples when sparkline history is available.

**Provenance and scope:**

The data comes from getdaytrends.com, which mirrors public X trend boards. The Actor works over HTTP and is MCP-ready, so agents can call it as a structured data tool without a browser session.

**Pagination and cost guidance:**

Each row returned is billed as a trend event. For planning, estimate cost from the number of locations multiplied by `maxTrendsPerLocation`, then adjust for deduplication or smaller row caps when you only need a subset. When `listAvailableLocations` is enabled, the Actor returns the supported location catalog instead of trend rows.

### Apify API example

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

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const run = await client.actor('khadinakbar/twitter-trends-scraper').call({
  locations: ['worldwide', 'united-states'],
  window: 'now',
  maxTrendsPerLocation: 10,
  includeHistory: false,
});

const datasetId = run.defaultDatasetId;
const { items } = await client.dataset(datasetId).listItems();

console.log('Dataset items:', items);
```

### Best results and outcome guidance

Use the smallest location set that matches the workflow. If you only need the current board, keep `window` on `now`. If your workflow depends on trend movement, enable `includeHistory`. If you are comparing markets, leave deduplication off to preserve one row per location. If you are gathering a campaign-ready hashtag list, use `hashtagOnly` together with a lower row cap.

### Design note

I found that the dataset contract is centered on one trend record per location per time window, with `rank`, `name`, `location`, `source`, and `scrapedAt` required on every row. That shape makes the output straightforward to join into downstream workflows.

### FAQ

#### Can I request several markets in one run?

Yes. The `locations` field accepts multiple location values, so one run can return trend rows for several countries or cities.

#### Can I get a past trend snapshot?

Yes. Use `window` values such as `1h`, `6h`, `24h`, `2d`, `3d`, or `7d`, or set `window` to `custom` and provide `customDateTime`.

#### How do I compare the same trend across locations?

Set `deduplicateAcrossLocations` to `true`. Matching trend names are collapsed into one row with a `locations[]` array.

#### How do I return only hashtag trends?

Set `hashtagOnly` to `true`. The dataset then includes only trends that start with `#`.

#### Can I list supported locations before scraping trends?

Yes. Set `listAvailableLocations` to `true` and the Actor returns the supported location catalog as dataset rows.

### Responsible use

Use this Actor for public trend analysis, monitoring, editorial workflows, and similar lawful purposes. Review your own obligations under X terms, getdaytrends terms, and applicable laws before building production workflows on top of the output.

# Actor input Schema

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

List of locations to scrape trends for. Accepts slug strings (e.g. 'worldwide', 'united-states', 'japan'), display names (e.g. 'United States', 'Brazil'), full getdaytrends URLs (e.g. https://getdaytrends.com/united-states/), or WOEID integers (e.g. 23424977 for the United States, 1 for Worldwide). Defaults to Worldwide. To list every available location once with zero trends, set listAvailableLocations=true instead.

## `window` (type: `string`):

Which snapshot to fetch. 'now' returns the live Top 50. '1h', '3h', '6h', '12h', '24h', '2d', '3d', '7d' return historical snapshots for the same location(s). 'custom' uses customDateTime. Defaults to 'now'. NOT a tweet-posted filter - it is the timestamp at which the trend board was captured.

## `customDateTime` (type: `string`):

Used only when window='custom'. UTC timestamp in 'YYYY-MM-DD HH' (24h) or full ISO format. Example: '2026-08-01 16' returns the snapshot from Aug 1, 2026 at 16:00 UTC. Earliest supported date is 2024-05-15.

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

Cap on the number of trend rows returned per location per window. Source returns up to 50; lower values reduce cost. Default 50.

## `hashtagOnly` (type: `boolean`):

When true, only trends starting with '#' are returned. Useful for hashtag-driven campaigns. Default false.

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

When true and multiple locations are scraped, repeats of the same trend name across locations collapse to a single row with a 'locations\[]' array. Default false (keeps one row per location, useful for market comparison).

## `includeHistory` (type: `boolean`):

When true, attaches a compact 'history\[]' array of (timestamp, rank) samples parsed from the source sparkline. Adds tokens, useful for trend trajectory analysis. Default true.

## `listAvailableLocations` (type: `boolean`):

When true, the actor returns the full catalog of supported locations (slug, displayName, country, woeid) as dataset rows and skips trend scraping. Default false.

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

Proxy servers used for HTTP requests. Defaults to Apify residential. getdaytrends is rarely WAF-protected so datacenter often works; switch to RESIDENTIAL only if you hit blocks.

## Actor input object example

```json
{
  "locations": [
    "worldwide",
    "united-states",
    "japan"
  ],
  "window": "now",
  "customDateTime": "2026-08-01 16",
  "maxTrendsPerLocation": 50,
  "hashtagOnly": false,
  "deduplicateAcrossLocations": false,
  "includeHistory": true,
  "listAvailableLocations": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset items containing one record per trend per location per time window.

## `summary` (type: `string`):

Run summary including trends scraped, location counts, window usage, charge counts, and source diagnostics.

## `runSummary` (type: `string`):

Same payload persisted under the RUN\_SUMMARY key for run-evidence workflows.

# 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"
    ],
    "window": "now",
    "maxTrendsPerLocation": 50,
    "hashtagOnly": false,
    "deduplicateAcrossLocations": false,
    "includeHistory": true,
    "listAvailableLocations": false,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/twitter-trends-scraper").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"],
    "window": "now",
    "maxTrendsPerLocation": 50,
    "hashtagOnly": False,
    "deduplicateAcrossLocations": False,
    "includeHistory": True,
    "listAvailableLocations": False,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/twitter-trends-scraper").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"
  ],
  "window": "now",
  "maxTrendsPerLocation": 50,
  "hashtagOnly": false,
  "deduplicateAcrossLocations": false,
  "includeHistory": true,
  "listAvailableLocations": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call khadinakbar/twitter-trends-scraper --silent --output-dataset

```

## MCP server setup

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

```

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/L2pDj8ou2JPNWFeJY/builds/O1my6HHWplxjmWs2G/openapi.json