API de geografia de audiência do Twitter: analise seguidores por país

Por Sorsa Editorial

Atualizado em julho de 2026: reverificamos os limites de geografia da API oficial do X contra o modelo atual de pagamento por uso (os antigos tetos de requisição por nível não valem mais para novos desenvolvedores, os rate limits agora são por endpoint), atualizamos a resposta do /about para o conjunto de campos atual (ela agora retorna a fonte de conexão, o status Premium e a conta de afiliação ao lado do campo country), revelamos o caminho inicial de 100 requisições grátis para o fluxo poder ser testado antes de pagar e reconferimos cada endpoint e preço contra a referência da Sorsa ao vivo.

Em resumo. A geografia de audiência do Twitter é a distribuição por país dos seguidores de uma conta do X. Você a constrói puxando a lista de seguidores, consultando o país que o X atribui a cada seguidor (o valor por trás do rótulo público "Conta com base em", não a localização autodeclarada da bio) e agregando. Funciona para a sua própria conta ou para qualquer conta pública.

O X (antigo Twitter) já expôs dados de país da audiência dentro do analytics nativo para a sua própria conta, e nunca deixou você ver isso para a de outra pessoa. Não há botão público que diga em quais países os seguidores de um influenciador moram, ou como o público de um concorrente se divide entre mercados. A API oficial do X só expõe geografia no nível do tweet, o que é raro já que a maioria dos usuários não faz geotag, ou pelo enriquecimento Profile Geo no nível Enterprise, que a maioria das equipes não pode pagar.

A Sorsa API, um provedor alternativo de API do Twitter (X), fecha essa lacuna com um único endpoint, /about, que retorna o país que o X associa a qualquer conta pública em preço fixo por requisição, sem OAuth e sem fila de aprovação. O fluxo inteiro pode ser testado com 100 requisições grátis, uma alocação única que dispensa cartão, nunca expira e cobre todos os 40 endpoints. Combine-o com o endpoint /followers e você constrói um recorte completo por país do público de qualquer conta, a sua ou a de um concorrente. Este guia cobre de onde esse valor de país realmente vem, por que ele vence processar o campo "Localização" da bio, quatro pipelines de produção em Python e quanto custa.

Rodamos pipelines de geografia de audiência para equipes de crescimento e pesquisa desde a era da v1.1 e migramos dezenas deles para fora da API oficial após as mudanças de preço de 2023. É um dos pedidos mais comuns que recebemos, e um dos mais fáceis de errar.

Índice

• Onde o X de fato guarda a geografia
• Por que a geografia de audiência é difícil de obter
• Quatro casos de uso reais
• Quão preciso é o dado de país
• A referência do endpoint /about
• Quatro pipelines em Python para geografia de audiência do Twitter
• Exportando e visualizando
• Quanto isso custa
• Na prática
• Perguntas frequentes
• Primeiros passos

Onde o X de fato guarda a geografia {#where-x-actually-stores-geography}

O X carrega três sinais geográficos diferentes para uma conta, e eles não são intercambiáveis. A maioria dos artigos sobre o tema os confunde.

1. Campo "Localização" da bio. O texto livre que os usuários digitam no perfil. É não padronizado, muitas vezes uma piada ("a internet", "um porão em algum lugar"), muitas vezes vazio e nunca validado. Raspar esse campo é o que toda ferramenta legada de social listening fazia, e é por isso que os gráficos geográficos delas nunca foram precisos. Cerca de 30% a 40% das contas o deixam em branco ou o preenchem com texto não geográfico.

2. Dados de Place no nível do tweet. Quando um usuário faz geotag de um tweet, o payload carrega um objeto Place com um código de país. Pela própria documentação de desenvolvedor do X sobre filtrar tweets por localização, isso é opt-in no nível do tweet, e o recurso de localização precisa foi removido dos apps de iOS e Android em 2019. Menos de 3% dos tweets carregam metadados de geo, então é inútil para análise no nível de audiência.

3. O país da conta, mostrado como "Conta com base em". O X associa um país a cada conta a partir de sinais de nível de plataforma (histórico de IP, dados de dispositivo, métodos de pagamento, loja de aplicativos), não de qualquer coisa que o usuário digitou. Esse é o valor que o X revela publicamente como "Conta com base em" dentro do painel "Sobre esta conta" que chegou aos perfis no fim de 2025, e é o mesmo sinal que as extensões de navegador de selo de país leem. Para um detalhamento completo do que cada campo desse painel significa, veja nosso explicativo sobre o rótulo "Conta com base em" do X.

O endpoint /about da Sorsa retorna esse terceiro sinal como um campo country. É o mais confiável dos três para trabalho agregado: ele é preenchido para a grande maioria das contas ativas, é derivado da plataforma em vez de autodeclarado, e não depende de o usuário habilitar o geotag no nível do tweet.

Por que a geografia de audiência é difícil de obter {#why-audience-geography-is-hard-to-get}

Se o dado existe, por que nem toda ferramenta de analytics o mostra? Três motivos.

Primeiro, a API oficial do X não expõe esse valor de país como um campo simples e consultável para contas arbitrárias. Você pode lê-lo para um único perfil processando o painel público Sobre, mas não há endpoint v2 documentado para ele. O enriquecimento Profile Geo existe como um add-on Enterprise separado, com operadores só de enterprise como profile_country para filtrar tweets pelo país do autor, mas isso é um contrato anual de cinco dígitos e funciona no nível do fluxo de tweets, não no nível de audiência.

Segundo, o problema de volume. Para saber onde o público de um concorrente mora, você consulta o país de cada seguidor, não só da conta em si. Para uma conta com 100.000 seguidores, isso são 100.000 consultas mais algumas centenas de páginas de lista de seguidores. Os endpoints v2 oficiais continuam limitados por janela de 15 minutos, variando por endpoint e tipicamente na casa das poucas centenas de requisições no modelo atual de pagamento por uso, então uma única auditoria de concorrente nessa escala entra em muitas horas, muitas vezes dias, de chamadas limitadas antes mesmo de você contar o custo por recurso.

Terceiro, as ferramentas de consumo estão presas à sua própria conta. Ferramentas de analytics baseadas em login como Circleboom, TweepsMap, Fedica e Audiense autenticam via OAuth como você, então só conseguem mapear os seus próprios seguidores, nunca os de um concorrente. Elas também leem o campo "Localização" autodeclarado da bio e excluem os seguidores que o deixaram em branco, o que enviesa a amostra a favor de quem por acaso o preencheu.

A Sorsa contorna as três restrições. Ela retorna o país diretamente pelo /about, roda em planos mensais fixos em vez de cobrança por recurso, e funciona para qualquer perfil público sem uma autorização OAuth do lado do usuário. Para o quadro completo de custo, veja nossa análise de preços da API do Twitter em 2026.

Quatro casos de uso reais {#four-real-use-cases}

Estes são quatro cenários em que a geografia de audiência move uma decisão real. Os pipelines mais adiante neste guia mapeiam diretamente para eles.

Checagem de influenciador antes de uma campanha regional

Uma marca de tecnologia de consumo com quem trabalhamos estava prestes a colocar um orçamento de cinco dígitos médios em um lançamento nos EUA com seis criadores, cada um afirmando alcançar "profissionais de tecnologia dos EUA". A auditoria mostrou que vários tinham bem menos da metade dos seguidores de fato baseados nos EUA, e o maior deles ficava bem abaixo do que o número de seguidores dava a entender. Isso deslocou o orçamento para criadores menores com concentração mais apertada nos EUA antes de qualquer contrato ser assinado. Quem faz marketing de influência pago deveria checar a geografia de audiência antes de assinar, não depois.

Pesquisa de expansão de mercado

Antes de se comprometer com conteúdo localizado, um orçamento de anúncios pagos ou uma contratação regional, olhe o que o seu público já é. Uma equipe de B2B SaaS descobriu, por uma auditoria, que uma fatia relevante dos seguidores orgânicos deles ficava em um mercado que nunca tinham mirado com conteúdo ou anúncios, o bastante para justificar uma landing page localizada e um pequeno evento local. O padrão inverso também é útil: uma região com quase zero seguidores diz que você está começando do zero e deveria reservar orçamento para reconhecimento em vez de conversão. Essa é a metade geográfica da pesquisa de audiência; a metade de interesse e sobreposição de seguidores está coberta no nosso playbook de público-alvo.

Detecção de crescimento inorgânico

Se uma conta pequena ou média de repente ganha um grande grupo de seguidores de um país sem conexão óbvia com a atividade dela, isso é um forte sinal de crescimento inorgânico. Um grupo de pesquisa que assessoramos sinaliza contas cuja distribuição de país dos seguidores muda mais de cerca de 15 pontos em 30 dias; a maioria das contas sinalizadas se revela como tendo comprado seguidores ou sido alvo de uma campanha de amplificação. Para marcas, a mesma lógica pega concursos de seguidores comprados e astroturfing de concorrentes. A geografia é um sinal entre vários; o método completo no nível da conta está no nosso guia de auditoria de seguidores falsos.

Mapeamento de conversa transfronteiriça

Para pesquisa acadêmica e de políticas, você pode pegar qualquer tema, puxar tweets recentes pelo /search-tweets ou /mentions, e depois passar os autores únicos pelo /about para mapear como a conversa se distribui geograficamente. Vimos isso usado para estudar comunidades de diáspora, fluxos de desinformação e debates de política transfronteiriços. A distribuição por país de quem de fato está falando sobre um tema, ponderada pelo engajamento, diz muito sobre de quem a conversa realmente é.

Quão preciso é o dado de país {#how-accurate-is-the-country-data}

O país do /about é derivado da plataforma, então é muito mais confiável que processar a bio, mas não é perfeito, e vale ser honesto sobre os limites.

Uma pequena fatia de contas usa uma VPN consistente e é marcada com o país de saída da VPN em vez de onde o usuário mora. Para uma única consulta isso importa; para análise agregada em amostras de 500 seguidores ou mais, o ruído de VPN se dilui e a distribuição geral se sustenta dentro de alguns pontos.

Algumas contas não retornam país. Isso acontece quando o X não tem sinal suficiente para atribuir um com confiança, tipicamente para contas muito novas ou de atividade muito baixa. Os pipelines abaixo agrupam essas como "Unknown". Em uma amostra saudável de 1.000 seguidores, espere cerca de 1% a 5%. Uma fatia de Unknown bem mais alta em um grupo de seguidores recentes é útil em si: ela se correlaciona com fornecedores de seguidores comprados.

O país reflete a associação geográfica atual da conta, que pode mudar se o usuário genuinamente se muda ou troca de VPN, então trate um grupo de longa duração como uma fotografia em vez de uma identidade fixa.

Contra o campo "Localização" da bio, o contraste é gritante. As ferramentas de consumo que dominam esse espaço leem o texto autodeclarado da bio e descartam os seguidores que o deixaram em branco, enquanto o país do /about é inferido pelo X a partir de sinais de conexão e é preenchido para a maioria das contas ativas. Para dimensionamento de mercado, segmentação de anúncios, checagem de influenciadores e benchmark competitivo, essa precisão é mais que suficiente. Para identificação forense de uma única conta, trate qualquer consulta isolada como uma hipótese.

A referência do endpoint /about {#the-about-endpoint-reference}

A autenticação é um único cabeçalho: ApiKey: YOUR_API_KEY. Os detalhes completos estão na documentação de autenticação da Sorsa.

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

Resposta:

{
  "country": "United States",
  "username_change_count": 1,
  "last_username_change_at": "2021-01-01T00:00:00Z",
  "premium_start_at": "2025-06-18T16:28:44Z",
  "is_blue_verified": true,
  "source": "United States App Store",
  "affiliate_username": "X"
}

O campo que você quer para geografia é country. Você pode identificar a conta por um de três parâmetros: username (@ sem o arroba), user_id (ID numérico estável) ou user_link (URL completa do perfil). Para fluxos agregados usamos user_id, porque ele não muda se a conta rebatiza o @. A resposta também carrega username_change_count e last_username_change_at (útil para pontuação de estabilidade), source (o valor "Conectada via", web ou uma região de loja de aplicativos, que serve como um segundo sinal geográfico grosseiro), is_blue_verified e premium_start_at (status Premium e quando começou, embora o timestamp seja um espaço reservado para contas não Premium) e affiliate_username (a conta-mãe a que um perfil afiliado se liga). O explicativo de "Conta com base em" linkado acima detalha esses campos por completo. Uma requisição equivale a uma chamada de cota em qualquer plano, sem multiplicadores por endpoint.

Quatro pipelines em Python para geografia de audiência do Twitter {#four-python-pipelines-for-twitter-audience-geography}

Os quatro se apoiam em dois helpers: um que puxa uma lista de seguidores do GET /followers (até 200 perfis por página, veja Seguidores e Seguindo), e um que resolve o país de um único seguidor pelo GET /about.

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):
    """Paginate GET /followers (up to 200 profiles per page)."""
    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):
    """Return the country for a user_id, or 'Unknown' if X has no value."""
    try:
        resp = requests.get(f"{BASE_URL}/about", headers=HEADERS,
                            params={"user_id": user_id}, timeout=15)
        if resp.status_code == 200:
            return resp.json().get("country") or "Unknown"
    except requests.RequestException:
        pass
    return "Unknown"

Pipeline 1: consulta de conta única

O caso mais simples, útil como ponto de partida e para verificação pontual. Para uma checagem única sem código, o verificador de localização roda a mesma consulta pelo navegador.

def get_account_geo(identifier):
    """Country and stability metadata for one account (username, user_id, or URL)."""
    if identifier.startswith("http"):
        params = {"user_link": identifier}
    elif identifier.isdigit():
        params = {"user_id": identifier}
    else:
        params = {"username": identifier.lstrip("@")}
    resp = requests.get(f"{BASE_URL}/about", headers=HEADERS, params=params, timeout=15)
    resp.raise_for_status()
    return resp.json()


data = get_account_geo("elonmusk")
print(data["country"], data["username_change_count"])

Pipeline 2: geografia de audiência completa

O fluxo central. Puxe a lista de seguidores de qualquer conta pública, resolva o país de cada seguidor, agregue.

def audience_geography(username, max_pages=10):
    followers = get_followers(username, max_pages=max_pages)
    counts = Counter(get_country(f["id"]) for f in followers)
    return counts, len(followers)


counts, total = audience_geography("nasa", max_pages=5)
for country, n in counts.most_common(10):
    print(f"{country}: {n} ({n / total * 100:.1f}%)")

A 20 requisições por segundo, uma amostra de 1.000 seguidores resolve em cerca de um minuto sequencialmente. Para auditorias maiores, rode o get_country sobre um pool de threads de 15 a 18 workers para ficar sob o rate limit enquanto corta o tempo de relógio.

Pipeline 3: comparação de concorrentes

Rode a mesma auditoria por uma lista curta de contas e compare a participação de um mercado-alvo. A geografia de audiência é uma entrada em um fluxo mais amplo de análise de concorrentes no Twitter.

def compare_accounts(usernames, market="United States"):
    for u in usernames:
        counts, total = audience_geography(u, max_pages=5)
        share = round(counts.get(market, 0) / total * 100, 1) if total else 0
        print(f"{u}: {total} sampled, {market} {share}%, top {counts.most_common(3)}")


compare_accounts(["competitor_a", "competitor_b", "competitor_c"])

Pipeline 4: detecção de seguidores comprados por padrão de país

Grupos de seguidores comprados têm uma assinatura de país distintiva: uma fatia alta de Unknown e uma concentração inesperada em um único país.

def inorganic_signal(counts, total):
    unknown = counts.get("Unknown", 0) / total * 100 if total else 0
    known = [(c, n) for c, n in counts.items() if c != "Unknown"]
    top_country, top_n = max(known, key=lambda x: x[1], default=("none", 0))
    top_share = top_n / total * 100 if total else 0
    flags = []
    if unknown > 20:
        flags.append(f"high Unknown share ({unknown:.0f}%)")
    if top_share > 60:
        flags.append(f"single-country concentration ({top_country} {top_share:.0f}%)")
    return flags

É uma heurística, não uma prova. Fazendas sofisticadas conseguem mascarar o país, mas o padrão pega o grosso do crescimento inorgânico barato.

Exportando e visualizando {#exporting-and-visualising}

Com o objeto counts em mãos, exporte-o para relatório ou jogue-o direto em um mapa. Para levar o recorte a uma planilha compartilhada para públicos não técnicos, veja como exportar dados do X para o Google Sheets.

import csv

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

Os nomes de país que o /about retorna são nomes padrão em inglês, então mapeiam direto em um choropleth do Plotly sem uma consulta ISO. Isso produz o mesmo tipo de mapa que as ferramentas de consumo vendem, gerado a partir dos seus próprios dados e salvo como um arquivo HTML autônomo.

import plotly.express as px

def plot_choropleth(counts, path="audience_map.html"):
    rows = [{"country": c, "followers": n} for c, n in counts.items() if c != "Unknown"]
    fig = px.choropleth(rows, locations="country", locationmode="country names",
                        color="followers", color_continuous_scale="Blues")
    fig.write_html(path)

Quanto isso custa {#how-much-does-this-cost}

A geografia de audiência é um fluxo de alto volume, já que você faz uma chamada /about por seguidor. O preço é fixo por requisição em todos os planos, a partir de US$ 0,0018 por requisição, e as 100 requisições grátis deixam você testar o custo do pipeline antes de decidir. Números concretos no plano Pro da Sorsa (100.000 requisições por US$ 199 por mês, US$ 0,00199 por requisição):

Auditorias pontuais de uma única conta cabem no plano Starter (US$ 49 por mês, 10.000 requisições); trabalho regular de agência ou de analytics geralmente cai no Pro. A lista completa de níveis está na página de preços. A alavanca de otimização para verificação de campanha é que você não precisa de cada seguidor, só das contas que completaram a ação da campanha, que geralmente é duas ordens de grandeza menor que a lista completa de seguidores.

Na prática {#in-practice}

Uma agência de analytics com quem trabalhamos audita audiências de criadores para clientes na fase de negociação. Rodar o pipeline de audiência completa por uma lista curta de criadores, algumas centenas a alguns milhares de seguidores amostrados de cada, custa alguns dólares no Pro e termina em minutos, onde o mesmo trabalho na API oficial significaria um contrato Enterprise ou dias de chamadas v2 limitadas. Para equipes que rodam isso como um programa contínuo em vez de algo pontual, a geografia encaixa em um setup mais amplo de acompanhamento de concorrentes. A razão recorrente de eles confiarem nisso é a fonte de dados: o país vem do próprio sinal "Conta com base em" do X, não do campo de bio que as ferramentas de login leem, então a distribuição se sustenta quando um cliente contesta os números.

Perguntas frequentes {#faq}

Dá para ver de que país uma conta do Twitter está baseada sem uma API?

Sim para uma única conta, não em escala. O X mostra o país no painel público "Sobre esta conta" de cada perfil, e nosso explicativo sobre o rótulo "Conta com base em" percorre como lê-lo à mão. Para uma distribuição agregada por milhares de seguidores, você precisa de uma API como o /about da Sorsa, que retorna o mesmo valor de país em escala REST a um custo fixo por requisição.

Por que o campo "Localização" da bio é não confiável para geografia de audiência?

O campo "Localização" da bio é texto livre digitado pelo usuário, não validado, não padronizado e frequentemente vazio ou jocoso. Cerca de 30% a 40% das contas o deixam em branco ou o preenchem com texto não geográfico. Mesmo quando preenchido, "NYC", "New York City" e "Big Apple" são três strings que um script ingênuo trata como três lugares. O valor de país do /about é derivado da plataforma e evita todos esses modos de falha.

A API oficial do X expõe dados de país dos seguidores?

Não no nível por conta para contas arbitrárias nos níveis pagos da v2. O enriquecimento Profile Geo, que adiciona metadados de país aos tweets com base no perfil do autor, é um add-on só de Enterprise com preço de cinco dígitos. Os endpoints padrão de consulta de usuário da v2 não retornam o país "Conta com base em". Essa é a lacuna que o /about da Sorsa preenche: o mesmo sinal subjacente, exposto como uma chamada REST fixa.

Quanto tempo leva uma auditoria de geografia de audiência?

Para uma amostra de 1.000 seguidores no rate limit da Sorsa de 20 requisições por segundo, um script sequencial termina em cerca de um minuto. Uma auditoria de 10.000 seguidores leva de 8 a 12 minutos sequencialmente, ou de 1 a 2 minutos com um pool de threads de 15 a 18 workers simultâneos. A paginação da lista de seguidores é uma pequena fração do total; as chamadas /about por seguidor dominam.

O que acontece quando o /about não retorna país?

Quando o /about não retorna país, o X não teve sinal suficiente para atribuir um com confiança, geralmente para contas muito novas ou de atividade muito baixa. Os pipelines deste guia agrupam essas como "Unknown". Em uma amostra saudável de 1.000 seguidores, espere de 1% a 5%. Uma fatia de Unknown notavelmente mais alta em um grupo de seguidores recentes se correlaciona com padrões de crescimento inorgânico e fornecedores de seguidores comprados.

Dá para detectar seguidores comprados usando geografia de audiência?

Sim, com ressalvas. Fornecedores de seguidores comprados geralmente vêm de um conjunto estreito de países com pouca supervisão, e as contas deles tendem a ser de baixa atividade, o que produz uma assinatura de grupo distintiva: uma fatia alta de Unknown, uma concentração inesperada em um único país e uma rotatividade elevada de @. O Pipeline 4 deste guia implementa a heurística. Não é perfeito, já que fazendas sofisticadas conseguem mascarar o país, mas pega o grosso do crescimento inorgânico barato.

Qual alternativa à API do Twitter suporta consultas de geografia de audiência em escala?

A Sorsa API é uma das poucas alternativas que expõe o país "Conta com base em" por um endpoint REST documentado (/about), combina-o com extração de seguidores em massa a até 200 perfis por requisição, e cobra em planos mensais de taxa fixa em vez de por chamada. Para uma visão mais ampla das opções, veja nosso texto sobre alternativas à API do Twitter.

Primeiros passos {#getting-started}

A forma mais rápida de testar isso é pegar uma chave no painel da Sorsa e gastar parte das suas 100 requisições grátis (uma alocação única, sem cartão, que nunca expira e cobre todos os 40 endpoints) rodando o trecho de conta única contra qualquer @, depois escalar. A referência do /about está na documentação de endpoints, e o playground deixa você acertar o /about pelo navegador antes de escrever qualquer código. O preço é fixo por requisição em todos os planos, sem etapa de aprovação, então uma auditoria pontual de uma única conta cabe no Starter e o trabalho recorrente de agência cai no Pro. Se você está extraindo seguidores para a auditoria, nosso guia de puxar listas de seguidores tem os padrões de paginação e os casos de borda.

Revisado por Keksich, fundador da Sorsa, profissional de marketing e pesquisador da API do X.

Como isto foi preparado: este guia é construído sobre o nosso próprio trabalho operando uma API alternativa do Twitter (X), incluindo os endpoints /about e /followers que movem estes pipelines, com cada endpoint e preço reverificado contra a referência e os preços da Sorsa v3 ao vivo em julho de 2026. Para o comportamento geográfico do próprio X, nos apoiamos na documentação de desenvolvedor do X que cobre a filtragem de localização de tweets e os operadores Profile Geo do Enterprise; para o que é o rótulo público "Conta com base em" e quando chegou, o nosso próprio explicativo linkado na primeira seção. Os números de custo são calculados a partir da taxa por requisição atual do Pro, não estimados.