# X (Twitter) Trends Scraper | $0.16/1K | By Country (`feedminer/x-trends-scraper`) Actor Scrape trending topics on X (Twitter) country by country. One row per trend with its rank, its category, the post volume when X publishes one, and a ready to open search link. Schedule it and build the trend history X itself does not keep, as JSON, CSV or Excel. By FeedMiner. - **URL**: https://apify.com/feedminer/x-trends-scraper.md - **Developed by:** [FeedMiner](https://apify.com/feedminer) (community) - **Categories:** Social media, News, SEO tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.08 / 1,000 trend returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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
Export what is trending on X (Twitter), country by country and city by city. The full list X publishes for each place, around 50 trends, each with its rank, a ready to use search link and its post volume when X gives one. Schedule it and you own a trend history nobody sells you.
🌍 **Countries and cities, in one run.** Ask for `US`, `Paris` and `JP` together and each row carries the place it came from. Every location X covers is available, hundreds of cities included, read live from X's own catalogue rather than a hand written list. 💸 **$0.16 per 1,000 trends, down to $0.08 on the larger Apify plans.** The closest tools charge $0.39 and $0.23 per 1,000 on the free plan, and one adds a start fee. Here there is none, and a run of three places returns 150 rows in a few seconds. 🔗 **A trend you can act on.** Each row carries the exact search X itself runs for that trend, so feeding it to X Advanced Search Scraper is a copy and paste. 🕰️ **Your own history.** X publishes what is trending now and forgets it. Schedule this daily and the archive is yours, which is the part no API sells. #### Copy to your AI assistant ``` feedminer/x-trends-scraper on Apify. Exports trending topics on X (Twitter) by country. One row per trend with rank, name, category, postCount (when X publishes it), query, url and location. Call ApifyClient("TOKEN").actor("feedminer/x-trends-scraper").call(run_input={...}), then client.dataset(run["defaultDatasetId"]).list_items().items. Input: locations (string[] of two letter country codes, empty means the run's own address), maxTrendsPerLocation (int), sessions (array, optional), debugMode (bool). Country selection routes the run through a residential address in that country, so it needs Apify proxy. Full spec: GET https://api.apify.com/v2/acts/feedminer~x-trends-scraper/builds/default (Bearer TOKEN) → inputSchema, actorDefinition.storages.dataset, readme. Token: https://console.apify.com/account/integrations ``` *** ### How to scrape X (Twitter) trends ##### Basic: one country ```json { "locations": ["US"], "maxTrendsPerLocation": 50 } ``` ##### Several markets at once ```json { "locations": ["US", "GB", "FR", "JP"], "maxTrendsPerLocation": 50 } ``` Each row carries `location`, so one export covers four markets and still splits per place. ##### A city, which is where local news actually trends ```json { "locations": ["Paris", "Tokyo", "Sao Paulo"], "maxTrendsPerLocation": 50 } ``` City names are matched against X's own catalogue of covered places, so what you can ask for is exactly what X publishes. ##### Worldwide, the default ```json { "maxTrendsPerLocation": 50 } ``` ##### By WOEID, when you already have one ```json { "locations": ["615702", "23424977"] } ``` *** ### Input parameters | Parameter | Type | Default | Description | |---|---|---|---| | `locations` | array | | Countries by two letter code (US, FR, JP), cities or countries by name (Paris, Tokyo, Brazil), or WOEIDs. Leave empty for worldwide. The list of covered places comes from X itself | | `maxTrendsPerLocation` | integer | `50` | Stop once this many trends have been collected per country | **Advanced** | Parameter | Type | Default | Description | |---|---|---|---| | `sessions` | array | | Optional. The Actor works without one. X accounts of your own, for anyone who would rather the run used accounts they control | | `debugMode` | boolean | `false` | Verbose logs for support | #### Coming from another trends scraper `country` and `countries` work as they do elsewhere, `locations` as it does in the other one, and `woeids` takes numeric place ids directly. #### How a place is chosen X publishes its trends per place, and each place has an id. The run reads X's live catalogue of covered places, matches what you typed against it, then asks for that place directly. A two letter code gives the country itself, not one of its cities: `FR` is France, `Paris` is Paris. Nothing about your own location matters, so the same run gives the same answer from anywhere, and no proxy is needed to reach another market. #### What an account changes Nothing. This surface is public. `sessions` is accepted for consistency with the rest of the suite and is simply not needed here. *** ### What data can you extract from X trends? | Field | Type | Description | |---|---|---| | `rank` | integer | Position in the list X served, 1 is the top trend | | `name` | string | The trend as displayed, hashtag or phrase | | `category` | string | The domain X attaches, for example Politics, Sports, Entertainment. Empty when there is none | | `postCount` | integer | Posts behind the trend, when X publishes the number | | `query` | string | The exact search X runs for this trend, quoted when it is a phrase | | `url` | string | A ready to open X search link for the trend | | `location` | string | The place X served, as X names it, for example `United States` or `Paris` | | `woeid` | integer | The numeric id of that place, stable, reusable as an input | | `asked` | string | What you typed for it, so a run on many markets is easy to pivot | #### Example output ```json { "rank": 1, "name": "Francis Lalanne", "category": "Politics", "postCount": 45200, "query": "\"Francis Lalanne\"", "url": "https://x.com/search?q=%22Francis+Lalanne%22", "location": "Paris", "woeid": 615702, "asked": "Paris" } ``` *** ### Column mapping, if you are switching | Here | karamelo | |---|---| | `name` | `trend` | | `postCount` | `volume` | | `location` | not returned, the country is a run setting there | | `rank` | not returned | | `query` and `url` | not returned | | `woeid` | not returned | The other actor returns one row per trend and per time window, with `time` and `timePeriod`. Here a run is one snapshot: schedule it and the history is yours, with the place on every row. ### Pricing: Pay Per Event (PPE) | Event | Price | |---|---| | Trend returned | $0.00016 | That is **$0.16 per 1,000 trends**, with no start fee and no charge for a run that returns nothing. A daily watch on five countries is a few cents a month. The price steps down on its own for the larger Apify plans, to $0.12 and then $0.08 per 1,000. *** ##### What a run costs | | | |---|---| | Five countries, 50 trends each, 250 rows | $0.04 | | A daily watch on ten places, for a month | $2.40 | ##### Free tier The Apify free plan includes $5 of usage every month, which is roughly 31,000 trends here. No card required. ### Advanced usage **Build the history X does not keep.** Schedule it every hour or every day. Two weeks later you have a trend archive per country, which is the dataset every social listening tool sells back to you. **Chain it into search.** Take `query` from a trend row and pass it to X Advanced Search Scraper to pull the posts behind it. Trend to conversation, in two runs. **Spot a trend before your market does.** Watching four countries at once shows a topic climbing in one before it reaches the others, which is a real content lead. **Filter the noise by category.** `category` separates a sports trend from a political one, which is what makes an automated content brief usable. **Place coverage.** Every place X covers is available, and the list is read from X at run time rather than hard coded, so a place added by X works the day it appears. A name X does not know is reported by name instead of being silently skipped. *** ### Integrate X trends into your stack **Python** ```python from apify_client import ApifyClient client = ApifyClient("YOUR_APIFY_TOKEN") run = client.actor("feedminer/x-trends-scraper").call(run_input={ "locations": ["US", "GB", "FR"], "maxTrendsPerLocation": 30, }) rows = client.dataset(run["defaultDatasetId"]).list_items().items for r in sorted(rows, key=lambda x: -x["postCount"])[:10]: print(r["location"], r["rank"], r["name"], r["postCount"], r["url"]) ``` **JavaScript** ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' }); const run = await client.actor('feedminer/x-trends-scraper').call({ locations: ['JP'], maxTrendsPerLocation: 50, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); const sports = items.filter((t) => t.category === 'Sports'); ``` **No code** Push each run to Google Sheets, Airtable, Slack, Zapier, Make or n8n from the Integrations tab, and the trend list becomes a daily digest. *** ### Performance | Measure | Value | |---|---| | Places | Processed one after another, one request each | | Volume | Around 50 trends per place, which is the whole list X publishes | | Run time | A few seconds for several places | | Partial results | Places that answered are delivered even if one fails | *** ### FAQ **Which places can I ask for?** Any country by its two letter code, any city or country by name, or any WOEID. The catalogue comes from X itself at run time, and covers hundreds of cities. **Why is `postCount` zero on some rows?** Because X did not publish a volume for that trend. It is left at zero rather than estimated. **Do I need an X account?** No. This surface is public, and the full list is served without one. **Can I get city level trends?** Yes, that is what the place names are for. `Paris`, `Tokyo`, `Chicago` and hundreds of others are covered by X. **How often do trends change?** Continuously. Hourly runs are common for a newsroom, daily is enough for content planning. **Can I get the posts behind a trend?** Yes, pass the `query` field to X Advanced Search Scraper or X Tweet Scraper. **Are promoted trends included?** Promoted entries are not treated as organic trends and do not carry a rank in your export. **Why does a country return fewer trends than I asked for?** Because X served fewer. The run returns what it got rather than padding the list. *** ### Support A country that returns nothing, a category you do not recognise, a volume that looks wrong: write from the actor page. *** ### Legal compliance This actor reads the public trend lists X publishes. It contains no personal data by design: a trend row is a topic, a rank and a link. Anything you collect afterwards from the search links is subject to GDPR, CCPA and similar regimes. *** **FeedMiner** · Fast, honestly priced scrapers, kept alive when platforms change. [X Tweet Scraper](https://apify.com/feedminer/x-tweet-scraper) · [X Profile Scraper](https://apify.com/feedminer/x-profile-scraper) · [X Follower Scraper](https://apify.com/feedminer/x-follower-scraper) · [X Advanced Search Scraper](https://apify.com/feedminer/x-advanced-search-scraper) · [X Media Scraper](https://apify.com/feedminer/x-media-scraper) · [X Mentions Monitor](https://apify.com/feedminer/x-mentions-scraper) · [X Engagement Scraper](https://apify.com/feedminer/x-engagement-scraper) · [X Likes and Reposts Scraper](https://apify.com/feedminer/x-signals-scraper) · X Trends Scraper · [All FeedMiner Actors](https://apify.com/feedminer) # Actor input Schema ## `locations` (type: `array`): Countries by two letter code (US, FR, JP), cities or countries by name (Paris, Tokyo, Brazil), or WOEIDs. Leave empty for worldwide. The list of covered places comes from X itself. ## `maxTrendsPerLocation` (type: `integer`): Stop once this many trends have been collected per country. ## `sessions` (type: `array`): Optional. The Actor works without one. X accounts of your own, for anyone who would rather the run used accounts they control. ## `debugMode` (type: `boolean`): Verbose logs for support. ## Actor input object example ```json { "locations": [ "US", "Paris" ], "maxTrendsPerLocation": 50, "debugMode": false } ``` # Actor output Schema ## `trends` (type: `string`): No description # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "locations": [ "US", "Paris" ], "maxTrendsPerLocation": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("feedminer/x-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "locations": [ "US", "Paris", ], "maxTrendsPerLocation": 50, } # Run the Actor and wait for it to finish run = client.actor("feedminer/x-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": [ "US", "Paris" ], "maxTrendsPerLocation": 50 }' | apify call feedminer/x-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,feedminer/x-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 ` 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/chm2GEEgbBZsP5oZv/builds/6R57gddSB2GZ9XSOC/openapi.json