> ## 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.

# Localização da audiência

Consulte o país associado a uma conta pública do X e agregue a distribuição geográfica de seus seguidores.

> Veja exemplos e análise de distribuição no [guia do blog](https://api.sorsa.io/blog/twitter-audience-geography-api).

## Endpoint /about

Retorna metadados da seção About: país, histórico de mudanças de nome, status e início do X Premium (Blue), origem e afiliação organizacional.

### Requisição

```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())
```

### Parâmetros

| Parâmetro   | Tipo   | Obrigatório | Descrição               |
| :---------- | :----- | :---------- | :---------------------- |
| `username`  | string | Um dos três | Nome sem @.             |
| `user_id`   | string | Um dos três | ID numérico do usuário. |
| `user_link` | string | Um dos três | URL completa do perfil. |

### Resposta

```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
}
```

### Campos

| Campo                     | Tipo                      | Descrição                                                                                                                |
| :------------------------ | :------------------------ | :----------------------------------------------------------------------------------------------------------------------- |
| `country`                 | string                    | País associado à conta por sinais da plataforma, não pelo campo livre Location. Retorna `"Unknown"` quando faltam dados. |
| `username_change_count`   | integer                   | Total de mudanças de nome de usuário.                                                                                    |
| `last_username_change_at` | string (ISO 8601) ou null | Data da última mudança; null se nunca mudou.                                                                             |
| `premium_start_at`        | string (ISO 8601) ou null | Início do X Premium; null se não for assinante.                                                                          |
| `is_blue_verified`        | boolean                   | Se possui selo Blue do X Premium.                                                                                        |
| `source`                  | string                    | Origem exibida em About, como região da loja ou aplicativo de cadastro; exemplo: `"US App Store"`.                       |
| `affiliate_username`      | string ou null            | Nome da organização ou conta principal afiliada; null sem afiliação.                                                     |

Para a distribuição geográfica, basta `country`. Os demais campos vêm na mesma chamada.

## Fluxo de análise

1. Obtenha seguidores com `GET /v3/followers`.
2. Consulte `GET /v3/about` para cada `user_id`.
3. Agrupe os valores de `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)
```

### Custo

Cada consulta `/about` consome uma requisição. Uma amostra de 1.000 seguidores exige cerca de 1.005 chamadas: 1.000 países e 5 páginas de seguidores. As 100 gratuitas, sem cartão, permitem testar uma amostra menor. Veja [preços](https://api.sorsa.io/pricing).

## Exportar para 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)])
```

## Precisão e interpretação

`country` é o país retornado por `/about`; `location` é outro campo, de texto livre. Apresente o país como um rótulo da conta, não como residência verificada ou localização precisa.

* Mantenha `"Unknown"` separado e informe sua proporção. Não invente um país nem classifique falhas de requisição como país desconhecido.
* As primeiras páginas são uma amostra ordenada. Informe tamanho e data da coleta; não suponha que representam toda a audiência.
* Compare distribuições obtidas pelo mesmo método. Uma amostra maior não elimina o viés de seleção.

## Relacionados

* [Seguidores](https://docs.sorsa.io/pt-BR/followers-and-following)
* [Público-alvo](https://docs.sorsa.io/pt-BR/target-audiences-Discovery)
* [Concorrentes](https://docs.sorsa.io/pt-BR/Competitor-Analysis)
* [Campanhas](https://docs.sorsa.io/pt-BR/Marketing-Campaign-Verification)
* [Referência de Account About Info](https://docs.sorsa.io/pt-br/api-reference/usu%C3%A1rios/informa%C3%A7%C3%B5es-da-conta)