Audience Geography

How to retrieve the country associated with any public X account and aggregate audience geography data from a follower list.

Note: For a fuller walkthrough with worked examples and country-distribution analysis, see Twitter Audience Geography API: Analyze Followers by Country on the blog.

The `/about` Endpoint

Returns “About” section metadata for any public X account: country, username change history, X Premium (Blue) status and start date, account source, and organization affiliation.

Request

curl "https://api.sorsa.io/v3/about?username=elonmusk" \
  -H "ApiKey: YOUR_API_KEY"

import requests

resp = requests.get(
    "https://api.sorsa.io/v3/about",
    headers={"ApiKey": "YOUR_API_KEY"},
    params={"username": "elonmusk"},
)
print(resp.json())

Parameters

Parameter	Type	Required	Description
`username`	string	One of three	Handle without @.
`user_id`	string	One of three	Numeric user ID.
`user_link`	string	One of three	Full profile URL.

Response

{
  "country": "United States",
  "username_change_count": 1,
  "last_username_change_at": "2021-01-01T00:00:00Z",
  "premium_start_at": "2026-03-14T18:30:35Z",
  "is_blue_verified": true,
  "source": "US App Store",
  "affiliate_username": null
}

Response fields

Field	Type	Description
`country`	string	Country associated with the account, derived from platform-level signals (not the bio “Location” field). Returns `"Unknown"` when the platform has insufficient data.
`username_change_count`	integer	Total number of handle changes on the account.
`last_username_change_at`	string (ISO 8601) or null	Timestamp of the most recent handle change. `null` if the handle has never changed.
`premium_start_at`	string (ISO 8601) or null	Date the account’s X Premium (Blue) subscription started. `null` if the account is not on X Premium.
`is_blue_verified`	boolean	Whether the account has a Blue (X Premium) verified badge.
`source`	string	Source shown in the About section, such as the app store region or client the account registered from (for example, `"US App Store"`).
`affiliate_username`	string or null	Handle of the affiliated organization or parent account. `null` when there is no affiliation.

For audience geography you only need country. The remaining fields come back on the same call and are documented here for completeness.

Audience Geography Workflow

To build a country distribution for any account’s audience:

Extract the follower list with GET /v3/followers.
Call GET /v3/about for each follower using their user_id.
Aggregate the country values into a distribution.

import requests
import time
from collections import Counter

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.sorsa.io/v3"
HEADERS = {"ApiKey": API_KEY}


def get_followers(username, max_pages=10):
    followers, cursor = [], None
    for _ in range(max_pages):
        params = {"username": username}
        if cursor:
            params["next_cursor"] = cursor
        resp = requests.get(f"{BASE_URL}/followers", headers=HEADERS, params=params, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        followers.extend(data.get("users", []))
        cursor = data.get("next_cursor")
        if not cursor:
            break
        time.sleep(0.1)
    return followers


def get_country(user_id):
    resp = requests.get(
        f"{BASE_URL}/about",
        headers=HEADERS,
        params={"user_id": user_id},
        timeout=15,
    )
    resp.raise_for_status()
    return resp.json().get("country") or "Unknown"


def audience_geography(username, max_follower_pages=5):
    followers = get_followers(username, max_pages=max_follower_pages)
    countries = Counter()
    for user in followers:
        countries[get_country(user["id"])] += 1
        time.sleep(0.05)  # stay within 20 req/s
    return countries, len(followers)

Cost

Each /about call counts as one request against your quota. For a 1,000-follower sample, that is roughly 1,005 requests: 1,000 country lookups and 5 follower-list pages (200 followers per page). Every new account starts with 100 free requests (no card required), enough to test a smaller geography sample before choosing a plan. See Pricing for per-plan rates.

Exporting to CSV

import csv

def export_to_csv(countries, total, path="geography.csv"):
    with open(path, "w", newline="") as f:
        w = csv.writer(f)
        w.writerow(["country", "count", "percentage"])
        for country, count in countries.most_common():
            w.writerow([country, count, round(count / total * 100, 2)])

Data Accuracy

country is the account country returned by /about; location on a profile is a separate free-text field. Report the returned country as an account-level label, not a verified residence or precise location.

Keep "Unknown" as its own category and report its share of the retrieved sample. Do not substitute a country or treat failed requests as unknown-country results.
The first follower pages are an ordered sample. State the sample size and collection date; do not assume they represent the full audience.
Compare distributions collected with the same sampling method. A larger sample alone does not remove selection bias.

Getting started

Core Mechanics

Solution Guides

Support & Resources

The `/about` Endpoint

Request

Parameters

Response

Response fields

Audience Geography Workflow

Cost

Exporting to CSV

Data Accuracy

​The /about Endpoint

​Request

​Parameters

​Response

​Response fields

​Audience Geography Workflow

​Cost

​Exporting to CSV

​Data Accuracy

​Related

The `/about` Endpoint

Request

Parameters

Response

Response fields

Audience Geography Workflow

Cost

Exporting to CSV

Data Accuracy

Related