> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 受众地理分布

本页介绍如何获取公开 X 账号关联的国家，以及如何根据粉丝列表汇总受众地理分布。

> **注意：** 更多实例和国家分布分析请参阅博客上的 [Twitter 受众地理 API：按国家分析粉丝](https://api.sorsa.io/blog/twitter-audience-geography-api)。

***

## `/about` 端点

返回公开 X 账号“关于”部分的元数据：国家、用户名变更历史、X Premium（Blue）状态和开始日期、账号来源，以及组织关联信息。

### 请求

```bash theme={null}
curl "https://api.sorsa.io/v3/about?username=elonmusk" \
  -H "ApiKey: YOUR_API_KEY"
```

```python theme={null}
import requests

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

### 参数

| 参数          | 类型     | 必需  | 说明         |
| :---------- | :----- | :-- | :--------- |
| `username`  | string | 三选一 | 不含 @ 的用户名。 |
| `user_id`   | string | 三选一 | 数字用户 ID。   |
| `user_link` | string | 三选一 | 完整资料 URL。  |

### 响应

```json theme={null}
{
  "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
}
```

### 响应字段

| 字段                        | 类型                        | 说明                                                         |
| :------------------------ | :------------------------ | :--------------------------------------------------------- |
| `country`                 | string                    | 由平台层面信号推断的账号关联国家，不是简介中的 Location 字段。平台数据不足时返回 `"Unknown"`。 |
| `username_change_count`   | integer                   | 账号用户名累计变更次数。                                               |
| `last_username_change_at` | string (ISO 8601) or null | 最近一次用户名变更的时间戳。未更改过则为 `null`。                               |
| `premium_start_at`        | string (ISO 8601) or null | X Premium（Blue）订阅开始日期。没有订阅则为 `null`。                       |
| `is_blue_verified`        | boolean                   | 是否具有 Blue（X Premium）认证标记。                                  |
| `source`                  | string                    | 关于部分显示的来源，例如账号注册时的应用商店地区或客户端，如 `"US App Store"`。           |
| `affiliate_username`      | string or null            | 关联组织或母账号的用户名。无关联则为 `null`。                                 |

分析受众地理分布只需要 `country`。其他字段会在同一调用中返回，这里一并列出以供参考。

***

## 受众地理分析流程

构建任意账号受众的国家分布：

1. 使用 `GET /v3/followers` 提取粉丝列表。
2. 通过各粉丝的 `user_id` 调用 `GET /v3/about`。
3. 汇总 `country` 值，得到分布。

```python theme={null}
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)
```

### 成本

每次 `/about` 调用扣除一次请求配额。1,000 位粉丝样本约需 1,005 次请求：1,000 次国家查询，加上 5 页粉丝列表（每页 200 位）。新账号有 100 次免费请求，无需信用卡，可先用更小样本测试，再选择套餐。各套餐费率见[价格](https://api.sorsa.io/pricing)。

***

## 导出到 CSV

```python theme={null}
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)])
```

***

## 数据准确性

`country` 是 `/about` 返回的账号国家，资料中的 `location` 是单独的自由文本字段。请把国家报告为账号层面的标签，而非经过验证的居住地或精确位置。

* 将 `"Unknown"` 保留为独立类别，并报告其在已获取样本中的占比。不要自行替换国家，也不要把请求失败当作国家未知。
* 粉丝列表前几页属于有序样本。说明样本量和采集日期，不要假设它代表全部受众。
* 比较采用相同抽样方式得到的分布。仅增大样本量不能消除选择偏差。

***

## 相关内容

* [粉丝与关注](https://docs.sorsa.io/zh-Hans/followers-and-following)
* [发现目标受众](https://docs.sorsa.io/zh-Hans/target-audiences-Discovery)
* [竞品分析](https://docs.sorsa.io/zh-Hans/Competitor-Analysis)
* [营销活动验证](https://docs.sorsa.io/zh-Hans/Marketing-Campaign-Verification)
* [API 参考：账号详细信息](https://docs.sorsa.io/zh-Hans/api-reference/users-data/account-about-info)