# Twitter Trends Scraper By City & Multiple Countries (`simpleapi/twitter-trends-scraper`) Actor Twitter Trends Scraper fetches real-time trending topics from X (Twitter), including trend names, ranks, tweet volume, and regional or global availability. Ideal for trend monitoring, audience insights, news tracking, research, and automating fast, structured trend data collection at scale. - **URL**: https://apify.com/simpleapi/twitter-trends-scraper.md - **Developed by:** [SimpleAPI](https://apify.com/simpleapi) (community) - **Categories:** Automation, Lead generation, Social media - **Stats:** 12 total users, 5 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.99 / 1,000 results 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/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 ### Twitter Trends Scraper By City & Multiple Countries Scrape live **X (Twitter) trending topics** for **many locations in a single run** — worldwide, **62 countries** and **402 cities** — and get every trend back with its **rank**, its **location**, the **country code** and the **WOEID** it came from. Most Twitter trends scrapers return one board per run for one country, with no location stamped on the row, so comparing markets means running the actor a dozen times and stitching the CSVs together yourself. This Twitter trending topics scraper takes a **list** of places, resolves each one against X's own public location catalogue, and returns a single flat dataset you can pivot by city or by country immediately. ### What is Twitter Trends Scraper By City & Multiple Countries? It's an Apify actor that pulls live trending topics from X (Twitter) for as many places as you list in one run. Give it country codes, country names, city names or raw WOEIDs — "US", "Brazil", "New York", "sao-paulo", "2459115" all work — and it resolves each against X's real 467-location catalogue (worldwide + 62 countries + 402 cities), fetches that location's current top 50 trends through an anonymous guest-token session (no login, no cookies, no X account), and returns rows tagged with `locationName`, `locationType`, `countryCode` and `woeid` so you can slice the result by market without extra joins. A legacy single-country mode (the original getdaytrends.com board) ships alongside it for existing schedules that only ever tracked one country. ### What data can I extract with Twitter Trends Scraper By City & Multiple Countries? **Trend rows** (`type: "trend"`, one per trend per location): | Field | Description | | --- | --- | | `rank` | Position on that location's board, 1 = highest. | | `trend` | The trend name or hashtag text. | | `isHashtag` | `true` if the trend starts with `#`. | | `locationName` / `locationType` / `countryCode` / `countryName` / `woeid` | Which place this trend came from. | | `searchUrl` | Direct X search URL for the trend. | | `dataSource` | `x_guest_api` (multi-location engine) or `getdaytrends` (legacy board). | | `timePeriod` | `Live`, or an hour-offset label for the legacy board. | | `snapshotTimeUtc` / `time` / `scrapedAt` | When X (or getdaytrends) generated the board vs. when the row was captured. | **Location rows** (`type: "location"`, catalogue mode): `woeid`, `locationName`, `locationType`, `countryName`, `countryCode`, `parentWoeid` — the full list of 467 places you can pass into `locations`. **Error/accounting rows** (`type: "error"`, uncharged): `errorReason` such as `location_not_found`, `no_trends_returned` or `archive_endpoint_gone`, so a failed location is visible in the dataset instead of silently missing. ### Why not build this yourself? X doesn't publish a documented public trends API — the endpoint this actor uses (`trends/place.json`) is X's own internal web-client surface, reached with an anonymous guest token that expires and rate-limits at roughly 15 calls per 15 minutes. Building this yourself means reverse-engineering the guest-token handshake, handling 429s with token rotation, and maintaining a location-name-to-WOEID lookup table for 467 places by hand. This actor already does all three, plus keeps the older getdaytrends.com HTML-scrape board working for anyone with an existing single-country workflow. One honest limitation worth knowing before you rely on trend **volume**: X's own guest API returns `tweet_volume: null` on every trend at this endpoint, and getdaytrends' fallback selector was found to silently emit the trend name itself as a fake "volume" on roughly a quarter of rows. Rather than ship a column that's either empty or wrong, this actor doesn't emit a `volume` field at all — rank is the reliable ordering signal instead. ### How to use data extracted from Twitter Trends Scraper By City & Multiple Countries? - **Social media managers** — compare what's trending in each market you post into before scheduling content, instead of guessing from one country's board. - **PR and crisis-comms teams** — watch a city-level trend list for early spikes tied to a brand, product or event, filtered down to the exact metro that matters. - **Market researchers** — build a cross-country trend index over repeated scheduled runs to see which topics travel between markets and which stay local. - **Growth and content teams** — feed `trend` + `searchUrl` straight into a content-ideation pipeline, deduplicated by `woeid` so the same global trend isn't double-counted per city. ### 🔼 Input sample | Parameter | Required | Type | Description | Example | | --- | --- | --- | --- | --- | | `locations` | No | array | Places to track: country code, country name, city name/slug, `"City, CC"`, raw WOEID, or `worldwide`. Leave empty to fall back to the legacy single-country board below. | `["worldwide", "US", "New York", "London", "JP"]` | | `maxTrendsPerLocation` | No | integer | Cap trends kept per location (1-50, X publishes 50 per place). Default `50`. | `10` | | `listAvailableLocations` | No | boolean | Catalogue mode — return the 467-place list instead of trends, to discover exact names/WOEIDs. Default `false`. | `false` | | `catalogueTypeFilter` | No | string | Narrows catalogue mode: `all`, `city`, `country`, `worldwide`. | `"city"` | | `country` | No | string | Legacy single-country enum for the original getdaytrends.com board. Empty = worldwide. | `"US"` | | `live` | No | boolean | Legacy board: scrape the current board now. | `true` | | `hour1`-`hour23` | No | boolean | Legacy board: rewind N hours (1-23). | `false` | | `yesterday` / `day2` / `day3` / `weekAgo` / `monthAgo` / `yearAgo` | No | boolean | Legacy date-archive toggles. **Common pitfall:** getdaytrends' date archive now returns HTTP 520 for every date — these are accepted for backward compatibility but only produce an uncharged `archive_endpoint_gone` accounting row, never real data. | `false` | | `startUrls` | No | array | Extra raw getdaytrends URLs to scrape alongside everything else. | `["https://getdaytrends.com/japan/3/"]` | | `maxRetries` | No | integer | Retry attempts per failed legacy-board page fetch. Default `3`. | `3` | | `requestTimeoutSecs` | No | integer | Per-request timeout for both engines. Default `30`. | `30` | | `proxy` | No | object | Optional — both engines work with no proxy; guest-token quota is handled by token rotation, not IP rotation. | `{"useApifyProxy": false}` | ```json { "locations": ["worldwide", "US", "New York", "London", "JP"], "maxTrendsPerLocation": 10 } ``` ### 🔽 Output sample ```json { "type": "trend", "dataSource": "x_guest_api", "timePeriod": "Live", "rank": 1, "trend": "#WorldCupFinal", "isHashtag": true, "locationName": "New York", "locationType": "city", "countryCode": "US", "countryName": "United States", "woeid": 2459115, "parentWoeid": 23424977, "searchUrl": "https://x.com/search?q=%23WorldCupFinal", "snapshotTimeUtc": "2026-07-26T14:02:00Z", "time": "2026-07-26T14:02:00Z", "scrapedAt": "2026-07-26T14:03:11Z" } ``` ### How do you filter and target specific X trends? Pass exactly the mix of places you need in `locations` — country codes for national boards, city names for metro-level trends, or `worldwide` for the global board — and every row comes back stamped with enough location metadata to filter or group downstream without a lookup table. **Just three global markets, top 10 each:** ```json { "locations": ["US", "GB", "JP"], "maxTrendsPerLocation": 10 } ``` **City-level only, disambiguated where the name is ambiguous:** ```json { "locations": ["New York", "Birmingham, GB", "sao-paulo"], "maxTrendsPerLocation": 50 } ``` **Discover exact city names/WOEIDs first, filtered to cities only:** ```json { "listAvailableLocations": true, "catalogueTypeFilter": "city" } ``` ### ▶️ Want to try other scrapers? | Actor | What it does | | --- | --- | | [twitter-x-posts-scraper-replies](https://apify.com/SimpleAPI/twitter-x-posts-scraper-replies) | Scrape X posts and their reply threads. | | [x-twitter-posts-search-by-advanced-keyword-filters](https://apify.com/SimpleAPI/x-twitter-posts-search-by-advanced-keyword-filters) | Search X posts with advanced keyword filters. | | [twitter-x-reply-scraper-with-replier-contact-leads](https://apify.com/SimpleAPI/twitter-x-reply-scraper-with-replier-contact-leads) | Pull repliers to an X post as contact leads. | ### How to extract Twitter trends programmatically ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("SimpleAPI/twitter-trends-scraper-by-city-multiple-countries").call(run_input={ "locations": ["worldwide", "US", "New York", "London", "JP"], "maxTrendsPerLocation": 10, }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["locationName"], item["rank"], item["trend"]) ``` Every run's dataset can also be exported straight to JSON, CSV, Excel or an API endpoint from the Apify Console — no code needed for a one-off pull. ### Is it legal to scrape X (Twitter) trends? Scraping publicly accessible data — including public trending-topics boards — is generally lawful in the US under the precedent set in *hiQ Labs v. LinkedIn*, which held that scraping data not gated behind a login does not violate the Computer Fraud and Abuse Act. This actor reads only X's own public, anonymous guest-token trends surface — the same data any visitor sees, without an account or login. If you extract data tied to identifiable people, GDPR (EU) and CCPA (California) still govern what you do with it, so review your own use case, especially for storage, resale or profiling. ### ❓ FAQ **Does this need an X (Twitter) account or API key?** No. It uses X's own public anonymous guest-token endpoint — the same one your browser gets when you visit x.com without logging in. No login, cookie or developer API key is required. **Why doesn't the output include trend volume (tweet counts)?** X's guest API returns `tweet_volume: null` on every trend at this endpoint, and the legacy getdaytrends fallback was found to silently substitute the trend name itself as a fake volume on about a quarter of rows. Shipping a column that's either always empty or sometimes wrong would be worse than omitting it, so `volume` isn't emitted. **How many locations can I track in one run?** As many as you list. The catalogue covers 467 places (worldwide, 62 countries, 402 cities); each resolved location costs one API call against a shared 15-calls-per-15-minutes guest-token quota, which the actor rotates through automatically on 429s. **What happens if I misspell a city name?** The actor tries an exact match, then a slug match, then a substring match. An ambiguous substring match (e.g. "Springfield") picks the first hit and logs the alternatives; a name with no match at all produces an uncharged `location_not_found` accounting row instead of stopping the run. **Can I still run this the old single-country way?** Yes. Leave `locations` empty and use `country` plus `live`/`hour1`-`hour23` exactly as the original getdaytrends-based actor worked — every existing schedule keeps running unchanged. **Do the date-archive toggles (`yesterday`, `weekAgo`, etc.) still work?** No — getdaytrends' date-archive pages now return HTTP 520 for every date. These toggles are still accepted so old input JSON doesn't break validation, but they only emit an uncharged `archive_endpoint_gone` row. Use live `locations` tracking on a schedule instead of historical lookback. **How is this different from other Twitter/X trends scrapers on Apify?** As observed on the Apify Store on 2026-07-26, the other Twitter trends actors we reviewed return one country or one board per run with no per-row location field, so multi-market comparison means running the actor repeatedly and merging results yourself. This actor resolves a list of mixed country/city/WOEID inputs in a single run and stamps every row with `locationName`, `locationType`, `countryCode` and `woeid` for direct multi-market analysis. **What's the difference between a "board" row and a "sidebar" row on the legacy engine?** getdaytrends' page renders four tables: two make up the 50-row main board, and two are 10-row sidebar panels ("top by score" and "longest trending"). Every row carries a `sourcePanel` field so you can tell which table it came from and exclude sidebar rows if you only want the primary board. ### Conclusion Twitter Trends Scraper By City & Multiple Countries turns X's anonymous guest-token trends surface into a multi-market dataset in one run — list the places you care about, get back ranked trends stamped with location, country and WOEID, ready to pivot without extra API calls or manual stitching. # Actor input Schema ## `locations` (type: `array`): One run, many markets. Each entry may be a country code (US, GB, JP), a country name (Brazil), a city name or slug (New York, sao-paulo, London), "City, CC" to disambiguate (Birmingham, GB), a raw Yahoo WOEID (2459115), or worldwide. Every trend row is stamped with locationName, locationType, countryCode and woeid so multi-market results stay separable. Leave empty to fall back to the legacy single-country board below. ## `maxTrendsPerLocation` (type: `integer`): Cap the number of trends kept per location, ranked 1 = highest. X publishes 50 per place. Example: 10 locations x 10 trends = 100 rows. Default 50. ## `listAvailableLocations` (type: `boolean`): Catalogue mode. Returns one row per place X supports (woeid, locationName, locationType, countryName, countryCode, parentWoeid) instead of trend rows — use it to discover the exact city names and WOEIDs to paste into Locations above. Default off. ## `catalogueTypeFilter` (type: `string`): Narrows catalogue mode. Only applies when the catalogue toggle above is on. ## `country` (type: `string`): The original one-country-per-run input, kept so existing runs and schedules keep working. It drives the getdaytrends.com board together with the time toggles below. Prefer Locations above for anything multi-market. ## `live` (type: `boolean`): Scrape the current getdaytrends board for the legacy country above (or worldwide when it is empty). ## `hour1` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 1 hour(s) ago (worldwide, or the Legacy country below). ## `hour2` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 2 hour(s) ago (worldwide, or the Legacy country below). ## `hour3` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 3 hour(s) ago (worldwide, or the Legacy country below). ## `hour4` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 4 hour(s) ago (worldwide, or the Legacy country below). ## `hour5` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 5 hour(s) ago (worldwide, or the Legacy country below). ## `hour6` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 6 hour(s) ago (worldwide, or the Legacy country below). ## `hour7` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 7 hour(s) ago (worldwide, or the Legacy country below). ## `hour8` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 8 hour(s) ago (worldwide, or the Legacy country below). ## `hour9` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 9 hour(s) ago (worldwide, or the Legacy country below). ## `hour10` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 10 hour(s) ago (worldwide, or the Legacy country below). ## `hour11` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 11 hour(s) ago (worldwide, or the Legacy country below). ## `hour12` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 12 hour(s) ago (worldwide, or the Legacy country below). ## `hour13` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 13 hour(s) ago (worldwide, or the Legacy country below). ## `hour14` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 14 hour(s) ago (worldwide, or the Legacy country below). ## `hour15` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 15 hour(s) ago (worldwide, or the Legacy country below). ## `hour16` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 16 hour(s) ago (worldwide, or the Legacy country below). ## `hour17` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 17 hour(s) ago (worldwide, or the Legacy country below). ## `hour18` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 18 hour(s) ago (worldwide, or the Legacy country below). ## `hour19` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 19 hour(s) ago (worldwide, or the Legacy country below). ## `hour20` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 20 hour(s) ago (worldwide, or the Legacy country below). ## `hour21` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 21 hour(s) ago (worldwide, or the Legacy country below). ## `hour22` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 22 hour(s) ago (worldwide, or the Legacy country below). ## `hour23` (type: `boolean`): Legacy getdaytrends slice: the board as it stood 23 hour(s) ago (worldwide, or the Legacy country below). ## `yesterday` (type: `boolean`): Accepted for backward compatibility, but getdaytrends' date-archive pages now answer HTTP 520 for every date, so no data exists behind this toggle. Enabling it emits an uncharged accounting row (errorReason=archive\_endpoint\_gone) rather than silently returning nothing. ## `day2` (type: `boolean`): Accepted for backward compatibility, but getdaytrends' date-archive pages now answer HTTP 520 for every date, so no data exists behind this toggle. Enabling it emits an uncharged accounting row (errorReason=archive\_endpoint\_gone) rather than silently returning nothing. ## `day3` (type: `boolean`): Accepted for backward compatibility, but getdaytrends' date-archive pages now answer HTTP 520 for every date, so no data exists behind this toggle. Enabling it emits an uncharged accounting row (errorReason=archive\_endpoint\_gone) rather than silently returning nothing. ## `weekAgo` (type: `boolean`): Accepted for backward compatibility, but getdaytrends' date-archive pages now answer HTTP 520 for every date, so no data exists behind this toggle. Enabling it emits an uncharged accounting row (errorReason=archive\_endpoint\_gone) rather than silently returning nothing. ## `monthAgo` (type: `boolean`): Accepted for backward compatibility, but getdaytrends' date-archive pages now answer HTTP 520 for every date, so no data exists behind this toggle. Enabling it emits an uncharged accounting row (errorReason=archive\_endpoint\_gone) rather than silently returning nothing. ## `yearAgo` (type: `boolean`): Accepted for backward compatibility, but getdaytrends' date-archive pages now answer HTTP 520 for every date, so no data exists behind this toggle. Enabling it emits an uncharged accounting row (errorReason=archive\_endpoint\_gone) rather than silently returning nothing. ## `startUrls` (type: `array`): Optional raw getdaytrends URLs to scrape in addition to everything above. Was read by the original code but never declared in its schema. Example: https://getdaytrends.com/japan/3/ ## `maxRetries` (type: `integer`): Retry attempts for a failed getdaytrends page fetch. Was read by the original code but never declared. Default 3. ## `requestTimeoutSecs` (type: `integer`): Per-request timeout for both engines. Was read by the original code but never declared. Default 30. ## `proxy` (type: `object`): Optional. Both the X guest-token engine and getdaytrends answer fine with no proxy from Apify; guest-token quota is handled by token rotation, not by IP rotation. ## Actor input object example ```json { "locations": [ "worldwide", "US", "New York", "London", "JP" ], "maxTrendsPerLocation": 50, "listAvailableLocations": false, "catalogueTypeFilter": "all", "country": "", "live": false, "hour1": false, "hour2": false, "hour3": false, "hour4": false, "hour5": false, "hour6": false, "hour7": false, "hour8": false, "hour9": false, "hour10": false, "hour11": false, "hour12": false, "hour13": false, "hour14": false, "hour15": false, "hour16": false, "hour17": false, "hour18": false, "hour19": false, "hour20": false, "hour21": false, "hour22": false, "hour23": false, "yesterday": false, "day2": false, "day3": false, "weekAgo": false, "monthAgo": false, "yearAgo": false, "maxRetries": 3, "requestTimeoutSecs": 30, "proxy": { "useApifyProxy": false } } ``` # Actor output Schema ## `results` (type: `string`): All scraped items in the Actor's default dataset. ## `runSummary` (type: `string`): Accounting record written once at the end of the run: charged/uncharged row counts, proxy used, X guest-token activations/rotations/API calls, catalogue size and the run ID. # 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": [ "worldwide", "US", "New York", "London", "JP" ], "proxy": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("simpleapi/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "locations": [ "worldwide", "US", "New York", "London", "JP", ], "proxy": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("simpleapi/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", "US", "New York", "London", "JP" ], "proxy": { "useApifyProxy": false } }' | apify call simpleapi/twitter-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,simpleapi/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 ` 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/qLdINS8SDahjDGUHu/builds/nspAkfR91bkQTVXez/openapi.json