> ## 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 Audience Geography 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 | 3つのうち1つ | @なしのユーザー名。    |
| `user_id`   | string | 3つのうち1つ | 数値のユーザーID。    |
| `user_link` | string | 3つのうち1つ | 完全なプロフィール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                    | プラットフォーム側の情報から判断されたアカウントの国。自己紹介の「場所」とは別です。十分な情報がない場合は`"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回につき割り当て量を1リクエスト消費します。1,000人の標本なら、国情報1,000回とフォロワー一覧5ページ（各200人）で、約1,005リクエストです。新規アカウントのカード不要の無料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/ja/followers-and-following)
* [ターゲット層の発見](https://docs.sorsa.io/ja/target-audiences-Discovery)
* [競合分析](https://docs.sorsa.io/ja/Competitor-Analysis)
* [マーケティングキャンペーンの確認](https://docs.sorsa.io/ja/Marketing-Campaign-Verification)
* [APIリファレンス：アカウントの詳細情報](https://docs.sorsa.io/ja/api-reference/users-data/account-about-info)