TwitterScore.io / API docs

Country or region X shows for an account (About this account)

GET https://twitterscore.io/api/v1/get_account_location

Returns where X says the account is based, from X's "About this account" panel: based_in is a country, or one of X's regions (such as Europe or Southeast Asia) when the owner chose to show only a region; country_code is its ISO 3166-1 alpha-2 code. location_accurate is X's own flag: false means X warns that a VPN or proxy may distort the country. connected_via is the app store or platform the account connects through, as X shows it (for example "United States App Store" or "Web"). profile_location is the free-text location from the profile, as typed by the owner and unverified. TwitterScore reads the panel for the accounts it monitors (not for suspended ones or accounts known only from the follower graph), once a country is known it is not re-read, and an empty result is retried after 30 days: checked_at is the date of the value shown. based_in: null with a checked_at means the panel gave no location (X shows none or the profile was not found); based_in: null with checked_at: null means the account is not checked. An empty answer still costs one request.

Required: one of username, twitter_id.

Parameters

Parameter Type Required Default Description
username string no X/Twitter handle without the leading @ (whitespace/slashes stripped). Also matches the profile slug and previous handles of renamed accounts.
twitter_id integer no Numeric X/Twitter user id. Tried before username when both are given.

At least one of username, twitter_id is required.

Example request

curl -s "https://twitterscore.io/api/v1/get_account_location?username=BitDotCountry" \
  -H "X-API-Key: $TWITTERSCORE_API_KEY" \
  -H "User-Agent: my-app/1.0 ([email protected])"
import os, requests

r = requests.get(
    "https://twitterscore.io/api/v1/get_account_location",
    params={"username": "BitDotCountry"},
    headers={"X-API-Key": os.environ["TWITTERSCORE_API_KEY"],
             "User-Agent": "my-app/1.0 ([email protected])"},
    timeout=15,
)
data = r.json()
if not data.get("success", True):      # errors arrive as success=false (see /developers/errors/)
    raise RuntimeError(data["message"])
print(data)
const r = await fetch("https://twitterscore.io/api/v1/get_account_location?username=BitDotCountry", {
  headers: { "X-API-Key": process.env.TWITTERSCORE_API_KEY,
             "User-Agent": "my-app/1.0 ([email protected])" },
});
const data = await r.json();
if (data.success === false) throw new Error(data.message);
console.log(data);

Example response

{
  "success": true,
  "twitter_id": "1299932702557138946",
  "username": "BitDotCountry",
  "based_in": "Singapore",
  "country_code": "SG",
  "location_accurate": true,
  "connected_via": "Singapore App Store",
  "profile_location": "Web3",
  "checked_at": "2026-04-23T09:01:41Z"
}

Errors

Error codes this endpoint can return (see Errors for the body format): api_key_missing, api_key_invalid, api_access_deactivated, api_key_revoked, invalid_params, account_not_found, method_not_allowed, rate_limited, quota_exceeded, server_error.


Authentication: X-API-Key header (or Authorization: Bearer), see Authentication; existing integrations that pass ?api_key= keep working. Limits: per-minute rate and monthly quota by plan, see Rate limits. Machine-readable definition: /openapi.json.

This page as Markdown.