# X (Twitter) Account Country & Location Scraper (`lurkapi/x-twitter-location-scraper`) Actor Get 'Account based in' country, signup source, affiliate org, and verification metadata for any X (Twitter) account. No login, no API key, no cookies required. - **URL**: https://apify.com/lurkapi/x-twitter-location-scraper.md - **Developed by:** [LurkAPI](https://apify.com/lurkapi) (community) - **Categories:** Agents, Automation, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 account locateds 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## X (Twitter) Account Country & Location Scraper Get the country an X account is based in: the exact "Account based in" field X shows in its About panel. Plus signup source (App Store country vs Web), verified badge type, affiliate organization, join date, and how many times the handle has been renamed. ### 🌍 What you get X's internal "About this account" data, per handle: - **Account based in**: country name X shows on the profile's About panel, plus a clean ISO 3166-1 alpha-2 code (`United States` → `US`). - **Connected via**: device / store the account was most recently active on. `Web`, ` App Store`, or ` Android App`. Useful for identifying which country / platform the account operates from. - **Verified status**: Blue, Business, Government badges + the reason X shows + since date. - **Affiliate**: parent organization the account is affiliated with (e.g. employees → their employer). - **Rename count**: join date + number of times the handle has been renamed + date of the most recent rename (previous handle strings not exposed by X). Not a self-typed profile string. X's own determination. ### 📋 How to use it #### Step 1: Add targets Drop in any mix of: - **Handles**: `nike`, `elonmusk`, `@openai`. One per line. - **Numeric user IDs**: `44196397`, `1339835893`. Survives handle changes. Resolved to the current handle before lookup. - **Full profile URLs**: `https://x.com/nike`. Bare profile URLs only. Mix all three in one run. Duplicates across fields are deduped for free. #### Step 2: Run and export Click **Start**. Rows stream into the **Output** tab as they scrape. Export from the Output tab as JSON, CSV, or Excel, or pull the dataset over the Apify API. Optional: turn off any fields you don't need in the 📤 Output fields section to keep rows lean. Off means the field is omitted entirely (not null). Every row carries a `status` field. `Success` = country resolved. `no_location` = About panel returned but has no country (usually gov / political accounts, not billed). `not_found` = handle does not exist. `error` = temporary lookup failure. Retry the run. ### 💰 Pricing Pay per row. Filtered, missing, and failed rows are always free. | Event | Per 1,000 | |----------------------|----------:| | Account located | **$2.00** | ### 💡 Good to know - **Two location fields**. `account_based_in` = X's determined country. `connected_via` = the country / platform of the most recent device the account connected from. They can differ, e.g. a Danish account whose owner recently used the US App Store returns `Denmark` + `United States App Store`. - **Regional buckets**. X sometimes returns a multi-country region (`Europe`, `East Asia`, `North America`, `West Asia`) instead of a country. `account_based_in_is_region` is `true` on those rows and `account_based_in_iso` is null (no single ISO for a region). - **`Web` signups have no country**. `connected_via = Web` means browser signup, no country signal. `connected_via_iso` stays null. - **Field toggles**. Every output field has its own on/off switch to keep rows lean. - **Cross-input dedup**. The same account arriving via handle + user ID + URL in the same run is charged once. ### ❓ FAQ **How is account_based_in different from a user's self-typed profile location?** X computes `account_based_in` internally from signup metadata + activity signals. It's on the "About this account" panel, not on the profile header. The free-text self-typed location field is not returned by this actor. **Why is account_based_in_iso null on some rows?** Two reasons. Either X returned a regional bucket (`Europe`, `East Asia`, ...), in which case those rows have `account_based_in_is_region: true`. Or the country name is not yet in the ISO mapping table (a bug candidate to flag). **Why is status: no_location on some rows?** X hides the About panel country for some high-profile government, political, or diplomatic accounts. The row still returns identity data (verified status, affiliate, date joined) but not country. These rows are not billed. **Can I get the free-text location field a user typed?** No. This actor targets the X-determined country only. For self-typed location, use [X Profile Scraper](https://apify.com/lurkapi/x-twitter-profile-scraper). **Do I need X cookies or an API key?** No. This actor works without any authentication. **Can I scrape a private / protected / suspended account?** No. If X hides it, no scraper can see it. The row will come back as `not_found`. **How do I export to Google Sheets / Excel / a CRM?** From the run's Output tab, hit Export → CSV, Excel, JSON, or HTML. Or pull via the Apify API. **How long are results kept?** Rows live in your Apify account. Retention depends on your Apify plan. ### 🔗 Other tools you might like - [X.com (Twitter) Profile Scraper](https://apify.com/lurkapi/x-twitter-profile-scraper): tweets from any X profile with filters. - [X.com (Twitter) Follower Scraper](https://apify.com/lurkapi/x-twitter-follower-scraper): followers, following, verified followers, plus optional email extraction. - [X.com (Twitter) Tweet Scraper](https://apify.com/lurkapi/x-twitter-tweet-scraper): any tweet by URL, ID, or search query. - [X.com (Twitter) Tweet Replies Scraper](https://apify.com/lurkapi/x-twitter-tweet-replies-scraper): full reply tree from any tweet URL. ### ⚖️ Legal disclaimer & terms of use **Purpose.** Intended for research, journalism, OSINT, market analysis, and educational use. The tool extracts data X itself publishes in its own "About this account" panel. The developer does not host, store, or possess any data you extract with this tool. **Personal data.** Country / location information about identifiable individual accounts is Personally Identifiable Information under GDPR, CCPA, and similar frameworks. By running this Actor you become the Data Controller for anything you collect. If you process data belonging to EU / UK / California / other regulated data subjects, you are responsible for the notification, purpose-limitation, retention, and opt-out obligations those laws impose (e.g. GDPR Article 14 notice within 30 days). **User liability.** You assume 100% responsibility for compliance with X's Terms of Service and every applicable law in your jurisdiction and the jurisdiction of the accounts you target. The developer assumes zero liability for platform blocks, account bans, regulatory fines, or legal actions resulting from your use of this software. **No warranty.** Software provided "as-is" without warranties of any kind. Country / verification / affiliate data reflects what X displayed at scrape time and can change without notice. You agree to hold the developer harmless from any damages or losses incurred. **Keywords:** x location scraper, twitter location scraper, account based in, twitter country lookup, x profile country, twitter geolocation, account country api, twitter user country, x connected via, twitter verified badge, twitter affiliate lookup # Actor input Schema ## `screenNames` (type: `array`): Usernames (e.g. elonmusk) or @-prefixed (e.g. @openai). One entry per target. ## `userIds` (type: `array`): Numeric X user IDs (e.g. 44196397). Survives handle changes. ## `urls` (type: `array`): Full X URLs (https://x.com/elonmusk). Bare profile URLs only. No /followers, /status, etc. ## `outputScreenName` (type: `boolean`): Canonical @handle. ## `outputName` (type: `boolean`): Display name. ## `outputAvatarUrl` (type: `boolean`): Profile picture URL. ## `outputAccountBasedIn` (type: `boolean`): Country name X shows in the About panel (e.g. "United States"). ## `outputAccountBasedInIso` (type: `boolean`): ISO 3166-1 alpha-2 country code (e.g. "US"). ## `outputAccountBasedInIsRegion` (type: `boolean`): true when X returned a multi-country region (e.g. Europe, East Asia) instead of a specific country. ## `outputConnectedVia` (type: `boolean`): Device / store the account most recently connected from: "Web", " App Store", " Android App". ## `outputConnectedViaIso` (type: `boolean`): ISO code parsed from connected_via when it names a specific country. Null for "Web" or regional buckets. ## `outputAffiliateUsername` (type: `boolean`): Handle of the parent organization the account is affiliated with (e.g. Musk → X, employees → their employer). ## `outputAffiliateDisplay` (type: `boolean`): Human-readable affiliate label (e.g. "X (@X)"). ## `outputVerifiedReason` (type: `boolean`): Reason string X shows for verification. ## `outputVerifiedSince` (type: `boolean`): Date verification started (e.g. "December 2011"). ## `outputIsBlueVerified` (type: `boolean`): Boolean: Blue verification badge. ## `outputIsBusinessVerified` (type: `boolean`): Boolean: Business (organization) verification badge. ## `outputIsGovernmentVerified` (type: `boolean`): Boolean: Government verification badge. ## `outputUsernameChangesCount` (type: `boolean`): Number of times the handle was renamed. ## `outputLastUsernameChange` (type: `boolean`): Date of the most recent handle change (e.g. "August 2017"). ## `outputDateJoined` (type: `boolean`): Month + year the account was created (e.g. "June 2009"). ## `outputProfileUrl` (type: `boolean`): Canonical https://x.com/ URL. ## `outputInputUserId` (type: `boolean`): Populated only when the row was produced from a userIds input; carries the numeric ID that was resolved. ## Actor input object example ```json { "screenNames": [ "nike", "elonmusk" ], "userIds": [], "urls": [], "outputScreenName": true, "outputName": true, "outputAvatarUrl": true, "outputAccountBasedIn": true, "outputAccountBasedInIso": true, "outputAccountBasedInIsRegion": true, "outputConnectedVia": true, "outputConnectedViaIso": true, "outputAffiliateUsername": true, "outputAffiliateDisplay": true, "outputVerifiedReason": true, "outputVerifiedSince": true, "outputIsBlueVerified": true, "outputIsBusinessVerified": true, "outputIsGovernmentVerified": true, "outputUsernameChangesCount": true, "outputLastUsernameChange": true, "outputDateJoined": true, "outputProfileUrl": true, "outputInputUserId": true } ```` # Actor output Schema ## `overview` (type: `string`): Compact table with the essentials — @handle, based-in country, connected via, affiliate, verified. ## `location` (type: `string`): Country + region + signup source fields, ready to filter or geo-segment. ## `identity` (type: `string`): Verification badge, affiliate org, join date, handle-change history. # 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 = { "screenNames": [ "nike", "elonmusk" ], "userIds": [], "urls": [] }; // Run the Actor and wait for it to finish const run = await client.actor("lurkapi/x-twitter-location-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 = { "screenNames": [ "nike", "elonmusk", ], "userIds": [], "urls": [], } # Run the Actor and wait for it to finish run = client.actor("lurkapi/x-twitter-location-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "screenNames": [ "nike", "elonmusk" ], "userIds": [], "urls": [] }' | apify call lurkapi/x-twitter-location-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lurkapi/x-twitter-location-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X (Twitter) Account Country & Location Scraper", "description": "Get 'Account based in' country, signup source, affiliate org, and verification metadata for any X (Twitter) account. No login, no API key, no cookies required.", "version": "0.0", "x-build-id": "zpcfwl8vSZoqnv6Mb" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lurkapi~x-twitter-location-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lurkapi-x-twitter-location-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lurkapi~x-twitter-location-scraper/runs": { "post": { "operationId": "runs-sync-lurkapi-x-twitter-location-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lurkapi~x-twitter-location-scraper/run-sync": { "post": { "operationId": "run-sync-lurkapi-x-twitter-location-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "screenNames": { "title": "👤 X handles", "type": "array", "description": "Usernames (e.g. elonmusk) or @-prefixed (e.g. @openai). One entry per target.", "items": { "type": "string" } }, "userIds": { "title": "🔢 Numeric user IDs", "type": "array", "description": "Numeric X user IDs (e.g. 44196397). Survives handle changes.", "items": { "type": "string" } }, "urls": { "title": "🔗 Full profile URLs", "type": "array", "description": "Full X URLs (https://x.com/elonmusk). Bare profile URLs only. No /followers, /status, etc.", "items": { "type": "string" } }, "outputScreenName": { "title": "screen_name", "type": "boolean", "description": "Canonical @handle.", "default": true }, "outputName": { "title": "name", "type": "boolean", "description": "Display name.", "default": true }, "outputAvatarUrl": { "title": "avatar_url", "type": "boolean", "description": "Profile picture URL.", "default": true }, "outputAccountBasedIn": { "title": "account_based_in", "type": "boolean", "description": "Country name X shows in the About panel (e.g. \"United States\").", "default": true }, "outputAccountBasedInIso": { "title": "account_based_in_iso", "type": "boolean", "description": "ISO 3166-1 alpha-2 country code (e.g. \"US\").", "default": true }, "outputAccountBasedInIsRegion": { "title": "account_based_in_is_region", "type": "boolean", "description": "true when X returned a multi-country region (e.g. Europe, East Asia) instead of a specific country.", "default": true }, "outputConnectedVia": { "title": "connected_via", "type": "boolean", "description": "Device / store the account most recently connected from: \"Web\", \" App Store\", \" Android App\".", "default": true }, "outputConnectedViaIso": { "title": "connected_via_iso", "type": "boolean", "description": "ISO code parsed from connected_via when it names a specific country. Null for \"Web\" or regional buckets.", "default": true }, "outputAffiliateUsername": { "title": "affiliate_username", "type": "boolean", "description": "Handle of the parent organization the account is affiliated with (e.g. Musk → X, employees → their employer).", "default": true }, "outputAffiliateDisplay": { "title": "affiliate_display", "type": "boolean", "description": "Human-readable affiliate label (e.g. \"X (@X)\").", "default": true }, "outputVerifiedReason": { "title": "verified_reason", "type": "boolean", "description": "Reason string X shows for verification.", "default": true }, "outputVerifiedSince": { "title": "verified_since", "type": "boolean", "description": "Date verification started (e.g. \"December 2011\").", "default": true }, "outputIsBlueVerified": { "title": "is_blue_verified", "type": "boolean", "description": "Boolean: Blue verification badge.", "default": true }, "outputIsBusinessVerified": { "title": "is_business_verified", "type": "boolean", "description": "Boolean: Business (organization) verification badge.", "default": true }, "outputIsGovernmentVerified": { "title": "is_government_verified", "type": "boolean", "description": "Boolean: Government verification badge.", "default": true }, "outputUsernameChangesCount": { "title": "username_changes_count", "type": "boolean", "description": "Number of times the handle was renamed.", "default": true }, "outputLastUsernameChange": { "title": "last_username_change", "type": "boolean", "description": "Date of the most recent handle change (e.g. \"August 2017\").", "default": true }, "outputDateJoined": { "title": "date_joined", "type": "boolean", "description": "Month + year the account was created (e.g. \"June 2009\").", "default": true }, "outputProfileUrl": { "title": "profile_url", "type": "boolean", "description": "Canonical https://x.com/ URL.", "default": true }, "outputInputUserId": { "title": "input_user_id", "type": "boolean", "description": "Populated only when the row was produced from a userIds input; carries the numeric ID that was resolved.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```