API de localização do Twitter: seguidores por país

#Como ver de onde são os seguidores de uma conta do Twitter

O X não desenha um mapa de seguidores para as contas dos outros, e as análises dele vêm com o X Premium e cobrem apenas a audiência do próprio assinante. O que o X mostra nos perfis públicos é o país em que ele coloca cada conta, e o Localizador de conta do Twitter grátis lê isso para uma conta. Repita para uma audiência e você terá a geografia dela, construída a partir de dois fatos públicos que o X mantém:

1. A lista de seguidores. Os seguidores de qualquer conta pública podem ser lidos página por página, dos mais novos para os mais antigos.

2. O país de cada seguidor. Desde novembro de 2025, os perfis públicos têm um painel Sobre esta conta, aberto a partir da data de entrada, com uma linha "Conta baseada em". O X o preenche a partir dos endereços IP agregados da conta, segundo a Central de Ajuda dele (abre em uma nova aba), e não a partir de algo que o dono digita.

Conte esses países entre os seguidores e as proporções são a geografia da audiência, da sua conta ou da de qualquer outra pessoa, em uma tabela que você pode exportar e comparar. Para saber o que o rótulo significa e quando ele erra, leia o que significa "Conta baseada em" no X.

A localização da bio é a armadilha. Ela é um texto livre opcional, e o próprio dicionário de dados para desenvolvedores (abre em uma nova aba) do X avisa que ela "may not indicate a valid location", ou seja, pode não indicar um local válido. Um mapa construído a partir dela descarta quem a deixou vazia ou escreveu "Terra" e conta o resto pelo que cada um escolheu digitar.

#Mapeie seguidores por país com a Sorsa API em seis passos

A Sorsa API, uma API e scraper do Twitter (X), devolve os dois fatos: o GET /followers (abre em uma nova aba) lista os seguidores de qualquer conta pública, 200 por requisição, e o GET /about (abre em uma nova aba) devolve o país que o X atribui a uma conta por requisição. Para mapear uma audiência por país, use a Sorsa API: uma chave de API, sem conta de desenvolvedor do X, e o país de cada seguidor a partir de US$ 1,40 por 1.000 contas.

1. Obtenha uma chave. Cadastre-se e copie a sua chave de API no painel. Contas novas ganham 100 requisições grátis, sem cartão.

2. Verifique uma conta. Envie um nome de usuário ao GET /about. O campo country guarda o valor de "Conta baseada em".

   curl -G "https://api.sorsa.io/v3/about" \
     -H "ApiKey: YOUR_API_KEY" \
     --data-urlencode "username=lisbon_tile_workshop"
   

   {
     "country": "Portugal",
     "source": "Portugal App Store",
     "username_change_count": 1,
     "last_username_change_at": "2019-05-14T09:12:40Z",
     "is_blue_verified": true,
     "premium_start_at": "2024-01-08T17:03:11Z",
     "affiliate_username": null
   }
   

3. Liste os seguidores. Percorra o GET /followers e devolva cada next_cursor até nenhum voltar. Guarde o id de cada seguidor: uma conta de 1 milhão de seguidores exige 5 mil requisições.

4. Sorteie uma amostra aleatória. Escolha 1.000 IDs ao acaso na lista inteira, não nas primeiras páginas, que contêm só os seguidores mais novos.

5. Consulte cada país. Chame o GET /about com user_id para cada seguidor da amostra, a até 20 requisições por segundo.

6. Conte as proporções. Agrupe as respostas por país, mantenha "Unknown" e os nomes de regiões como linhas próprias e divida cada contagem pelo tamanho da amostra.

O script abaixo executa os seis passos e imprime a proporção de cada país com a margem dela. Um status 429 significa mais de 20 requisições em um segundo, então ele espera e tenta de novo; um 403 significa que a chave está ausente ou sem requisições.

import random
import time
from collections import Counter
from math import sqrt

import requests

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


def follower_ids(username):
    """Every follower's ID, 200 per request, newest first."""
    ids, params = [], {"username": username}
    while True:
        r = requests.get(f"{API}/followers", headers=HEADERS, params=params)
        r.raise_for_status()
        page = r.json()
        ids += [u["id"] for u in page.get("users", [])]
        cursor = page.get("next_cursor")
        if not cursor:
            return ids
        params["next_cursor"] = cursor


def country(user_id):
    """The country X assigns to one account, or Unknown."""
    r = requests.get(f"{API}/about", headers=HEADERS,
                     params={"user_id": user_id})
    if r.status_code == 429:  # over 20 requests in a second
        time.sleep(1)
        return country(user_id)
    if not r.ok:
        return "Unknown"
    return r.json().get("country") or "Unknown"


def geography(username, sample_size=1000):
    ids = follower_ids(username)
    sample = random.sample(ids, min(sample_size, len(ids)))
    counts = Counter()
    for user_id in sample:
        counts[country(user_id)] += 1
        time.sleep(0.05)  # one lookup at a time stays under 20 per second
    n = len(sample)
    for name, k in counts.most_common(15):
        p = k / n
        margin = 1.96 * sqrt(p * (1 - p) / n)
        print(f"{name:<24} {p:6.1%}  +/- {margin:.1%}")


geography("lisbon_tile_workshop")

const API = "https://api.sorsa.io/v3";
const headers = { ApiKey: "YOUR_API_KEY" };
const sleep = (ms) => new Promise((done) => setTimeout(done, ms));

async function followerIds(username) {
  const ids = [];
  let cursor = null;
  do {
    const params = new URLSearchParams({ username });
    if (cursor) params.set("next_cursor", cursor);
    const res = await fetch(`${API}/followers?${params}`, { headers });
    if (!res.ok) throw new Error(`followers: HTTP ${res.status}`);
    const page = await res.json();
    for (const u of page.users ?? []) ids.push(u.id);
    cursor = page.next_cursor;
  } while (cursor);
  return ids;
}

async function country(userId) {
  const res = await fetch(`${API}/about?user_id=${userId}`, { headers });
  if (res.status === 429) {
    await sleep(1000);
    return country(userId);
  }
  if (!res.ok) return "Unknown";
  return (await res.json()).country || "Unknown";
}

async function geography(username, sampleSize = 1000) {
  const ids = await followerIds(username);
  for (let i = ids.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [ids[i], ids[j]] = [ids[j], ids[i]];
  }
  const sample = ids.slice(0, sampleSize);
  const counts = new Map();
  for (const id of sample) {
    const c = await country(id);
    counts.set(c, (counts.get(c) ?? 0) + 1);
    await sleep(50);
  }
  const rows = [...counts].sort((a, b) => b[1] - a[1]).slice(0, 15);
  for (const [name, k] of rows) {
    const p = k / sample.length;
    const margin = 1.96 * Math.sqrt((p * (1 - p)) / sample.length);
    const share = (p * 100).toFixed(1);
    const plusMinus = (margin * 100).toFixed(1);
    console.log(`${name.padEnd(24)} ${share}%  +/- ${plusMinus}%`);
  }
}

geography("lisbon_tile_workshop");

Para uma lista que você já tem, como uma exportação de seguidores do Twitter ou um CSV com os handles de clientes, pule o passo 3 e envie esses IDs ou nomes de usuário direto ao GET /about.

#Os três lugares em que o X guarda a localização de uma conta

Uma conta do X pode ter três tipos de localização, e só um deles vem do próprio X: o país de "Conta baseada em". É esse que se deve contar para a geografia da audiência, porque é o único que o X define e o único com uma única resposta por conta.

A tabela mostra quem define cada sinal e onde uma API o lê.

• Conta baseada em

  Quem define

  O X, a partir de endereços IP agregados

  O que contém

  Um país, ou uma região que o dono escolheu mostrar

  Onde uma API o lê

  country do GET /about na Sorsa API; ausente da API oficial do X

• Localização da bio

  Quem define

  O dono, como texto livre

  O que contém

  Uma cidade, uma piada ou nada

  Onde uma API o lê

  location em todo perfil, nas duas APIs

• Local em um post

  Quem define

  O autor, post a post

  O que contém

  Uma área ou um local com nome

  Onde uma API o lê

  Só nos posts cujos autores marcaram um

A API oficial do X traz apenas a localização da bio para as contas: o objeto de usuário dela tem o location digitado e nenhum campo de país. Ler seguidores ali custa US$ 0,010 cada na lista de preços por uso (abre em uma nova aba) do X, então uma lista de 1 milhão de seguidores custa US$ 10.000 e ainda termina em texto livre.

Os locais nos posts respondem a outra pergunta: onde algo foi postado, não onde uma conta está baseada. Um post só carrega um local depois que o autor ativa a localização no app e adiciona um lugar, como descreve a Central de Ajuda do X (abre em uma nova aba), então a maioria dos posts não tem nenhum. Para encontrar posts de uma cidade, use os operadores near: e within: do guia de operadores de busca do Twitter.

#Quantos seguidores você precisa verificar

Uma amostra aleatória de 1.000 seguidores dá a proporção de cada país com cerca de 3,1 pontos percentuais de margem, 95 vezes em 100, quer a conta tenha 50 mil seguidores, quer 50 milhões. A margem depende de quantos seguidores você verifica, não de quantos a conta tem, e é por isso que uma amostra vence um censo em contas grandes.

As margens abaixo valem para uma amostra aleatória simples com 95% de confiança. Um país que reúne cerca de metade da audiência tem a maior margem; os países menores são conhecidos com mais precisão.

• 400

  Margem em uma proporção de 50%

  ±4,9 pontos

  Margem em uma proporção de 10%

  ±2,9 pontos

• 1.000

  Margem em uma proporção de 50%

  ±3,1 pontos

  Margem em uma proporção de 10%

  ±1,9 ponto

• 2.000

  Margem em uma proporção de 50%

  ±2,2 pontos

  Margem em uma proporção de 10%

  ±1,3 ponto

• 5.000

  Margem em uma proporção de 50%

  ±1,4 ponto

  Margem em uma proporção de 10%

  ±0,8 ponto

• Todos os seguidores

  Margem em uma proporção de 50%

  nenhuma

  Margem em uma proporção de 10%

  nenhuma

Duas regras mantêm a amostra honesta. Sorteie-a da lista inteira de seguidores, já que as primeiras páginas contêm só os mais novos. E dimensione-a para a pergunta: 1.000 distinguem um mercado de 30% de um de 20%, enquanto distinguir um país de 6% de um de 4% exige cerca de 5.000.

Bom saber

Os seguidores mais novos descrevem o crescimento recente, não a audiência. Essa diferença é útil por si só: compare os países dos 1.000 seguidores mais novos com 1.000 aleatórios da lista inteira, e um bloco repentino de um país inesperado aparece na hora. Uma onda assim é um sinal comum de seguidores comprados, tema que a detecção de bots no Twitter aborda em profundidade.

#Quanto custa mapear uma audiência por país

Na Sorsa API, mapear uma audiência de 1 milhão de seguidores a partir de uma amostra de 1.000 custa a partir de US$ 8,40: US$ 7,00 para listar todos os seguidores e US$ 1,40 pelos 1.000 países. Verificar todos os seguidores custa a partir de US$ 1.407. A API oficial do X cobra US$ 10.000 só pela lista de seguidores, e os dados dela não têm país para contar.

A amostra custa quase nada perto da listagem em contas grandes, e a listagem custa quase nada perto de um censo. Os preços da Sorsa API abaixo usam a tarifa mais baixa dela, US$ 1,40 por 1.000 requisições.

• 10 mil

  Sorsa API, 1.000 verificados

  a partir de US$ 1,47

  Sorsa API, todos os seguidores

  a partir de US$ 14,07

  API oficial do X, só a lista

  US$ 100

• 100 mil

  Sorsa API, 1.000 verificados

  a partir de US$ 2,10

  Sorsa API, todos os seguidores

  a partir de US$ 140,70

  API oficial do X, só a lista

  US$ 1.000

• 1 milhão

  Sorsa API, 1.000 verificados

  a partir de US$ 8,40

  Sorsa API, todos os seguidores

  a partir de US$ 1.407

  API oficial do X, só a lista

  US$ 10.000

• 10 milhões

  Sorsa API, 1.000 verificados

  a partir de US$ 71,40

  Sorsa API, todos os seguidores

  a partir de US$ 14.070

  API oficial do X, só a lista

  US$ 100.000

O tempo segue a mesma divisão. A 20 requisições por segundo em todos os planos da Sorsa API, 1.000 consultas de país terminam em menos de um minuto, enquanto verificar todo 1 milhão de seguidores de uma conta grande leva cerca de 14 horas nessa taxa em uma chave. Na tarifa de US$ 4,90 por 1.000 requisições do plano Starter, a amostra para 1 milhão de seguidores custa US$ 29,40.

#Como ler o resultado

Uma tabela de países é tão boa quanto as linhas que você deixa de fora dela. Cinco coisas definem como lê-la:

• Unknown. O X não mostra país para algumas contas, incluindo contas de governo com selo cinza, e a Sorsa API devolve "Unknown" quando o X tem poucos dados. Relate isso como uma linha própria; uma proporção alta de Unknown entre seguidores novos costuma indicar contas recém-criadas ou inativas.
• Regiões. O X deixa os donos mostrarem uma região ampla em vez do país. Mantenha essas linhas como vêm, em vez de chutar um país.
• VPNs e viagens. O rótulo acompanha de onde a conta se conecta, então uma VPN ou uma viagem longa podem movê-lo. O X acrescenta um aviso no painel quando suspeita de uma VPN. Em 1.000 seguidores isso é ruído; para uma conta, leia o rótulo como uma pista, não como prova.
• Mudança ao longo do tempo. O rótulo se move quando as pessoas se movem, e os seguidores vão e vêm. Date todo mapa e repita-o com o mesmo tamanho de amostra para comparar meses.
• Proporções, não pessoas. Relate os países como porcentagens de uma audiência. Uma tabela de países com mil seguidores é pesquisa de mercado; uma lista de pessoas nomeadas por país não é para isso que este método serve.

Lida assim, a tabela responde a perguntas práticas. Antes de pagar um criador por uma campanha voltada a um mercado, veja que parcela dos seguidores dele de fato está baseada ali. Rode o mesmo mapa nos concorrentes para ver quais mercados eles alcançam e você não, como parte de uma análise de concorrentes no Twitter. Use-o para escolher horários: uma audiência dividida entre os Estados Unidos e a Europa fica a seis a nove horas de distância, então um único horário de postagem perde parte dela. E repita o mapa na sua própria conta a cada trimestre para ver de onde vem o crescimento.

#Mapeie a sua primeira audiência por país

Para descobrir onde estão os seguidores de qualquer conta do X, liste-os com o GET /followers, sorteie 1.000 e leia o país de cada um no GET /about. Na Sorsa API, isso mapeia uma audiência de 1 milhão de seguidores a partir de US$ 8,40, com a proporção de cada país a cerca de 3 pontos do valor real. Comece com as 100 requisições grátis: rode o script com sample_size=90 em uma conta que você conhece com menos de 2.000 seguidores e confira se a tabela parece certa.

#Perguntas frequentes