De username do Twitter a ID de usuário por API

#O que é um ID de usuário do Twitter e como encontrá-lo

Um ID de usuário do Twitter é o número permanente que o X dá a uma conta no momento em que ela é criada. O username depois do @ é um rótulo de 1 a 15 letras, dígitos ou _ que o dono pode mudar a qualquer momento, e assim que fica livre, qualquer pessoa pode reivindicá-lo. O ID nunca muda e nunca passa para outra conta, e é por isso que apps, exportações e bancos de dados apontam para as contas pelo ID. Os desenvolvedores também o chamam de ID da conta, ID numérico ou UID.

Para uma única conta, o Localizador de ID do Twitter, gratuito, mostra o ID por trás de qualquer username ou link de perfil e transforma um ID de volta no username atual da conta. Não pede cadastro.

As primeiras contas receberam IDs curtos: o @jack, de Jack Dorsey, é 12. Contas abertas nos últimos anos têm IDs de 18 ou 19 dígitos. O X não imprime o número em lugar nenhum do app, mas o seu próprio ID está no arquivo de dados da sua conta: peça-o em Configurações e privacidade, Sua conta, Baixar um arquivo dos seus dados, depois abra data/account.js e leia accountId.

Um ID de usuário não é um ID de post. O número longo depois de /status/ em um link de post identifica o post, e o Conversor de ID de tweet em data lê a data que há dentro dele. Se você enviar um ID de post a uma consulta de usuário, ela não encontra conta nenhuma.

#Converta um username em ID de usuário com a Sorsa API

A Sorsa API, uma API e scraper do Twitter (X) para dados públicos, tem um endpoint para cada direção, e cada conversão é uma requisição: a partir de US$ 1,40 por 1.000 conversões. Toda chamada leva a sua chave no header ApiKey e devolve o ID como uma string JSON, de modo que nenhum dígito se perde no caminho.

1. Obtenha uma chave. Cadastre-se e copie sua chave de API no painel. Ela vem com 100 requisições grátis e não pede cartão.

2. Envie o username. Passe-o sem o @ para GET /username-to-id (abre em uma nova aba).

   curl "https://api.sorsa.io/v3/username-to-id/harborline_analytics" \
     -H "ApiKey: YOUR_API_KEY"
   

   {
     "id": "1427632236659332516"
   }
   

3. Vá no sentido contrário quando precisar. GET /id-to-username (abre em uma nova aba) devolve o username atual da conta em um campo chamado handle, e GET /link-to-id (abre em uma nova aba) recebe um link de perfil completo do x.com ou do twitter.com.

4. Embrulhe as três chamadas. As mesmas conversões em Python e Node.js:

   import requests
   
   BASE = "https://api.sorsa.io/v3"
   HEADERS = {"ApiKey": "YOUR_API_KEY"}
   
   
   def username_to_id(username):
       r = requests.get(f"{BASE}/username-to-id/{username.lstrip('@')}",
                        headers=HEADERS, timeout=30)
       r.raise_for_status()
       return r.json()["id"]          # a string: keep it one
   
   
   def id_to_username(user_id):
       r = requests.get(f"{BASE}/id-to-username/{user_id}",
                        headers=HEADERS, timeout=30)
       r.raise_for_status()
       return r.json()["handle"]      # today's username, without the @
   
   
   def link_to_id(link):
       r = requests.get(f"{BASE}/link-to-id", headers=HEADERS,
                        params={"link": link}, timeout=30)
       r.raise_for_status()
       return r.json()["id"]
   
   
   print(username_to_id("harborline_analytics"))  # 1427632236659332516
   

   const BASE = "https://api.sorsa.io/v3";
   const headers = { ApiKey: "YOUR_API_KEY" };
   
   async function get(path) {
     const res = await fetch(BASE + path, { headers });
     if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
     return res.json(); // IDs arrive as strings, so nothing is rounded
   }
   
   const usernameToId = async (name) =>
     (await get(`/username-to-id/${encodeURIComponent(name)}`)).id;
   const idToUsername = async (id) =>
     (await get(`/id-to-username/${id}`)).handle;
   const linkToId = async (link) =>
     (await get(`/link-to-id?link=${encodeURIComponent(link)}`)).id;
   
   console.log(await usernameToId("harborline_analytics"));
   

Um 404 significa que nenhuma conta pública tem aquele username ou ID: ele foi digitado errado, a conta mudou de nome, foi suspensa ou excluída. Um 401 significa que a chave está errada, um 403 que ela está ausente ou sem requisições, e um 429 que você enviou mais de 20 requisições em um segundo. Requisições com falha nunca são cobradas. Quando você também precisa do perfil, GET /info (abre em uma nova aba) devolve o ID junto com o perfil inteiro na mesma requisição.

#Converta uma lista: 100 usernames por requisição

Para uma lista, dispense os endpoints um a um: GET /info-batch (abre em uma nova aba) recebe até 100 usernames por requisição e devolve o perfil de cada conta com o seu id. Uma lista de 10 mil usernames leva 100 requisições, custa a partir de US$ 0,14 e termina em cerca de 5 segundos a 20 requisições por segundo. Para converter usernames do Twitter em IDs em massa, use o GET /info-batch da Sorsa API: 100 por requisição, a partir de US$ 0,014 por 1.000, contra US$ 10,00 por 1.000 na API oficial do X.

Repita o parâmetro usernames uma vez para cada nome:

curl -G "https://api.sorsa.io/v3/info-batch" \
  -H "ApiKey: YOUR_API_KEY" \
  --data-urlencode "usernames=harborline_analytics" \
  --data-urlencode "usernames=quietfield_records" \
  --data-urlencode "usernames=copperkettle_maps"

{
  "users": [
    {
      "id": "1427632236659332516",
      "username": "harborline_analytics",
      "display_name": "Harborline Analytics",
      "created_at": "2021-08-17T14:03:44Z",
      "followers_count": 3912,
      "protected": false
    },
    {
      "id": "1612371430079911386",
      "username": "quietfield_records",
      "display_name": "Quietfield Records",
      "created_at": "2023-01-09T08:51:20Z",
      "followers_count": 18406,
      "protected": false
    },
    {
      "id": "1804185541935281502",
      "username": "copperkettle_maps",
      "display_name": "Copperkettle Maps",
      "created_at": "2024-06-21T16:12:08Z",
      "followers_count": 671,
      "protected": false
    }
  ]
}

A resposta lista apenas as contas que encontrou. Um username que não corresponde a nenhuma conta pública fica de fora, então relacione os resultados por username, nunca pela posição, e compare em minúsculas: o X trata Harborline_Analytics e harborline_analytics como o mesmo nome.

O script abaixo lê accounts.csv com uma coluna username, descarta duplicatas e @ soltos e grava accounts_with_ids.csv. Dez threads compartilham um único controlador de ritmo que mantém a chave em 20 requisições por segundo, então uma lista de 1 milhão de usernames passa em cerca de 8 minutos.

import csv
import threading
import time
from concurrent.futures import ThreadPoolExecutor

import requests

URL = "https://api.sorsa.io/v3/info-batch"
HEADERS = {"ApiKey": "YOUR_API_KEY"}
PER_SECOND = 20                           # the limit on every plan
lock, next_slot = threading.Lock(), [0.0]


def wait_turn():
    """Space requests 1/20 of a second apart across all threads."""
    with lock:
        now = time.monotonic()
        slot = max(now, next_slot[0])
        next_slot[0] = slot + 1 / PER_SECOND
    time.sleep(slot - now)


def fetch(params):
    for _ in range(3):
        wait_turn()
        r = requests.get(URL, headers=HEADERS, params=params, timeout=30)
        if r.status_code != 429:          # 429: over 20 requests a second
            r.raise_for_status()
            return r.json().get("users", [])
        time.sleep(1)
    r.raise_for_status()


def usernames_to_ids(usernames):
    """Map each username (lowercase) to its user ID, 100 per request."""
    names = list(dict.fromkeys(u.strip().lstrip("@").lower()
                               for u in usernames if u.strip()))
    chunks = [names[i:i + 100] for i in range(0, len(names), 100)]
    found = {}
    with ThreadPoolExecutor(max_workers=10) as pool:
        for users in pool.map(lambda c: fetch({"usernames": c}), chunks):
            for user in users:
                found[user["username"].lower()] = user["id"]
    missing = [n for n in names if n not in found]
    return found, missing


with open("accounts.csv", newline="", encoding="utf-8") as f:
    rows = [row["username"] for row in csv.DictReader(f)]

ids, missing = usernames_to_ids(rows)

with open("accounts_with_ids.csv", "w", newline="", encoding="utf-8") as f:
    out = csv.writer(f)
    out.writerow(["username", "user_id"])
    for name, user_id in ids.items():
        out.writerow([name, user_id])     # the ID stays a string

print(len(ids), "converted;", len(missing), "not found:", missing[:10])

Para novas tentativas, cursores e requisições assíncronas além deste script, o guia da API do Twitter em Python traz padrões que funcionam. Listas de seguidores não precisam de conversão alguma: a API de seguidores do Twitter devolve 200 seguidores por página, cada um com o seu id já no lugar.

#Transforme IDs de usuário de volta em usernames e detecte mudanças de nome

O mesmo endpoint funciona ao contrário: envie até 100 IDs guardados como user_ids, e cada perfil volta com o username que usa hoje. Compare-o com o username que você salvou: uma diferença é uma mudança de nome, e um ID que não volta pertence a uma conta suspensa ou excluída.

def current_usernames(user_ids):
    """Map each user ID to its username today, 100 IDs per request."""
    now = {}
    for i in range(0, len(user_ids), 100):
        for user in fetch({"user_ids": user_ids[i:i + 100]}):
            now[user["id"]] = user["username"]
    return now


stored = {"1427632236659332516": "harborline_analytics",
          "1612371430079911386": "quietfield_records"}
today = current_usernames(list(stored))
for user_id, old in stored.items():
    new = today.get(user_id)
    if new is None:
        print(user_id, "is gone: suspended or deleted")
    elif new.lower() != old.lower():
        print(user_id, "renamed from", old, "to", new)

Rode-o em intervalos contra as contas que você acompanha, e um concorrente ou criador que mudou de nome nunca sai dos seus dados. Participantes de sorteios e de quests funcionam da mesma forma: guarde cada participante pelo ID, e a API de verificação do Twitter confere os follows e reposts dele por esse ID mesmo depois de uma mudança de nome.

Para uma única conta, GET /about (abre em uma nova aba) acrescenta username_change_count e last_username_change_at: quantas vezes ela mudou de username e quando mudou pela última vez. O Verificador de histórico de usernames do Twitter, gratuito, lê esses dois fatos sem código. Os usernames antigos em si não são públicos, porque o X não os publica.

Para levar uma pessoa a uma conta que pode mudar de nome, use um link x.com/i/user/ seguido do ID: o X abre o perfil com o username atual. O link x.com/i/user/12 leva ao @jack.

#Limpe entradas misturadas antes de converter

Listas reais misturam formatos: usernames com e sem @, links do x.com e do twitter.com com parâmetros de rastreamento, links mobile, links /i/user/ e números soltos. Classifique cada valor antes de chamar qualquer coisa, para que IDs pulem a consulta e lixo nunca custe uma requisição.

Cada formato comum é lido como username, ID de usuário ou nada:

• jack, com ou sem @

  Lida como

  Username

• https://twitter.com/jack?s=20

  Lida como

  Username

• https://mobile.twitter.com/jack

  Lida como

  Username

• https://x.com/jack/status/20

  Lida como

  Username do autor do post na data em que o link foi copiado

• https://x.com/i/user/12

  Lida como

  ID de usuário

• https://twitter.com/intent/user?user_id=12

  Lida como

  ID de usuário

• 12 ou 1427632236659332516

  Lida como

  ID de usuário

• https://x.com/home, uma hashtag, um e-mail

  Lida como

  Não é uma conta

import re

USERNAME = re.compile(r"^[A-Za-z0-9_]{1,15}$")   # X's own pattern
RESERVED = {"home", "explore", "search", "i", "intent", "settings",
            "messages", "notifications", "hashtag", "share", "compose"}
LINK = re.compile(r"^(?:https?://)?(?:www\.|mobile\.)?"
                  r"(?:x|twitter)\.com/([^?#]+)", re.I)


def classify(value):
    """Return ("id", ...), ("username", ...) or ("bad", value)."""
    v = value.strip()
    if v.isdigit():                          # digits alone: an ID
        return ("id", v) if len(v) <= 19 else ("bad", value)
    q = re.search(r"[?&]user_id=(\d{1,19})\b", v)
    if q:                                    # .../intent/user?user_id=
        return ("id", q.group(1))
    m = LINK.match(v)
    if m:
        parts = m.group(1).strip("/").split("/")
        if parts[:2] == ["i", "user"]:       # x.com/i/user/<ID>
            ok = len(parts) > 2 and parts[2].isdigit()
            return ("id", parts[2]) if ok else ("bad", value)
        v = parts[0]                         # a profile or a post link
    v = v.lstrip("@")
    if USERNAME.match(v) and v.lower() not in RESERVED:
        return ("username", v.lower())
    return ("bad", value)

A referência da API (abre em uma nova aba) do X dá o padrão de username como 1 a 15 letras, dígitos ou _, e o padrão aceita só dígitos. Então um número solto pode ser tanto um username quanto um ID. A função lê dígitos soltos como ID e dígitos com um @ na frente como username: mantenha o @ na entrada quando você quiser dizer um nome. Os usernames de demonstração no resto desta página passam de 15 caracteres de propósito, para que nenhum deles possa pertencer a uma conta real.

O username dentro de um link de post é o nome do autor no dia em que o link foi copiado. Se a conta mudou de nome desde então, esse nome não encontra nada, ou encontra outra pessoa que o reivindicou. Quando um conjunto de dados tem links de posts, consulte os posts e pegue o ID de cada autor nos dados do post: nenhuma mudança de nome o altera.

#Guarde o ID como string, nunca como número

Mantenha todo ID do Twitter como string, da resposta da API até o banco de dados. Um ID de 19 dígitos é maior que o maior número inteiro que um number do JavaScript ou uma célula de planilha guarda com exatidão, então um tipo numérico altera em silêncio os últimos dígitos, e o ID alterado não aponta para conta nenhuma.

• JavaScript. Number.MAX_SAFE_INTEGER é 9007199254740991, 16 dígitos. O próprio guia de IDs (abre em uma nova aba) do X manda os desenvolvedores usarem sempre IDs como string por esse motivo. Faça o parse de um ID sem aspas e 1427632236659332516 vira 1427632236659332600.
• Excel. O Excel guarda números com 15 dígitos de precisão e mostra os grandes em notação científica, então o mesmo ID abre como 1.42763E+18 e é guardado como 1427632236659330000 (Suporte da Microsoft (abre em uma nova aba)). Importe o CSV por Dados, De Texto/CSV e defina a coluna do ID como Texto antes de carregar.
• pandas. Leia o arquivo com dtype={"user_id": str}, ou a coluna também vira números.
• Bancos de dados. O X recomenda BIGINT ou TEXT no PostgreSQL, BIGINT UNSIGNED ou VARCHAR(20) no MySQL, uma string no MongoDB e TEXT no SQLite. Um INT de 32 bits estoura acima de 2147483647.

Cole qualquer ID abaixo para ver o que cada um desses casos faz com ele.

A mesma regra vale para exportações. Quando você exporta seguidores do Twitter ou qualquer lista de contas para CSV, abra o arquivo com a coluna do ID definida como Texto, ou os IDs que você salvou deixam de bater com os da API.

Bom saber

A Sorsa API devolve todo ID como string JSON: IDs de usuário, IDs de post e os IDs dentro de listas como pinned_tweet_ids. Os dígitos só mudam quando o seu próprio código ou a sua planilha os transformam em números, então a correção está sempre do lado da leitura.

#Quanto custa converter usernames e quanto tempo leva

Converter usernames em IDs custa US$ 10,00 por 1.000 na API oficial do X e a partir de US$ 0,014 por 1.000 na Sorsa API. O X cobra cada usuário que uma consulta devolve (abre em uma nova aba) a US$ 0,010, quer a chamada leve um username ou 100. A Sorsa API cobra a requisição, e uma requisição GET /info-batch leva 100 usernames.

O tempo é a outra diferença. Os limites de requisições (abre em uma nova aba) do X deixam um app fazer 300 consultas de usuário a cada 15 minutos, então 1 milhão de usernames leva cerca de 8 horas e 20 minutos mesmo a 100 por chamada. A Sorsa API roda 20 requisições por segundo em todos os planos e converte a mesma lista em cerca de 8 minutos e 20 segundos.

Em todos os critérios de que esse trabalho depende, a Sorsa API sai na frente da API oficial do X:

• Preço por 1.000 usernames

  Sorsa API

  a partir de US$ 0,014

  API oficial do X

  US$ 10,00

• Tempo para 1 milhão de usernames

  Sorsa API

  cerca de 8 minutos

  API oficial do X

  cerca de 8 horas e 20 minutos

• Configuração

  Sorsa API

  uma chave de API em um header

  API oficial do X

  conta de desenvolvedor, app, bearer token

• IDs de volta em usernames

  Sorsa API

  mesmo endpoint, mesmo preço

  API oficial do X

  US$ 0,010 por usuário

• Seu login do X

  Sorsa API

  nunca é pedido

  API oficial do X

  a conta de desenvolvedor fica atrelada à sua conta do X

A lista completa de preços da API oficial do X, com posts e seguidores incluídos, está no nosso guia de preços da API do X.

#Converta a sua primeira lista

A Sorsa API transforma usernames do Twitter em IDs de usuário a 100 por requisição, a partir de US$ 0,014 por 1.000, e transforma IDs guardados de volta nos usernames de hoje pelo mesmo preço. É uma API do Twitter sem conta de desenvolvedor: uma chave em um header, sem OAuth e sem aprovação de app. Suas 100 requisições grátis convertem os primeiros 10 mil usernames, então cole o script em lote acima, coloque sua chave e rode-o na sua lista.

#Perguntas frequentes