Como analisar temas de criadores do TikTok: um pipeline prático em Python

Quando uma equipe procura um tema para a próxima campanha, analisar manualmente dezenas de perfis rapidamente se transforma em um conjunto de anotações sem uma metodologia comum. Um analista registra visualizações, outro anota legendas de vídeos, e publicações com formulações semelhantes acabam em planilhas diferentes. Uma semana depois, é difícil saber o que se repete mais: o tema, o formato de apresentação ou apenas um vídeo que teve sucesso.

Uma abordagem prática é manter uma pequena lista de contas públicas, obter regularmente informações sobre seus vídeos em formato estruturado e guardar cada coleta como um registro separado. Em seguida, é possível comparar publicações e métricas disponíveis ao longo do tempo, usando um modelo de linguagem para agrupar legendas preliminarmente. A seguir, apresentamos um esquema desse pipeline de pesquisa em Python com a TikTok Scraper API da jsonscraper.

Defina a pergunta antes de coletar dados

Imagine uma equipe de marketing de uma pequena marca de suplementos esportivos. Ela quer descobrir quais temas aparecem regularmente entre os criadores selecionados do TikTok e quais vídeos vale a pena analisar manualmente. O objetivo é comparar as publicações de contas previamente escolhidas durante um período de observação, e não criar um ranking universal de popularidade do TikTok.

Isso define os limites da análise. Coletar o feed dos perfis selecionados ajuda a estudar o conteúdo e a frequência de publicações dessas contas. Os contadores públicos disponíveis podem ser registrados no momento da solicitação. Para avaliar os resultados da própria publicidade, são necessários dados separados, como despesas e conversões da plataforma de anúncios ou da ferramenta de análise da web.

Antes de conectar a API, registre o protocolo de pesquisa: lista de contas, data de início, frequência de coleta, campos analisados e critérios para incluir publicações. Anote o horário de cada solicitação. Assim, será possível distinguir a mudança de uma métrica em um vídeo das diferenças entre dois conjuntos de observações.

O que coletar e o que calcular

Um projeto pequeno precisa de três camadas de dados. A primeira é o identificador da conta e o horário de início da coleta. A segunda é a resposta original da API, guardada para verificação posterior. A terceira consiste em campos normalizados para consultas e relatórios: ID do vídeo, legenda, horário de publicação e contadores de engajamento disponíveis.

Os nomes dos campos e a estrutura aninhada devem ser determinados a partir de uma amostra da rota específica. Não presuma de antemão que a lista sempre se chama videos ou que o contador de visualizações é views. Primeiro, faça a solicitação documentada e examine o JSON recebido; depois, configure a conversão para seu próprio esquema.

Indicadores úteis incluem o número de novas publicações por intervalo, a distribuição de publicações por tema e a mudança nos contadores públicos entre registros do mesmo vídeo. Para este último caso, compare registros com o mesmo ID de vídeo. Dessa forma, a evolução de um vídeo já publicado fica separada dos indicadores de novas publicações.

Conectando à TikTok Scraper API

A descrição da TikTok Scraper API informa o endereço-base https://tiktok.evelode.com, e a referência de rotas confirma GET /getUserFeed e os parâmetros query, max_cursor, count, region, with_pinned_posts, sort_type e cache_timeout. Para a primeira solicitação, basta informar o perfil em query e, por exemplo, a quantidade de itens por meio de count. A chave license_key é enviada na query string; a configuração também está descrita na referência da API. Na coleção do Postman, é possível conferir o endpoint e verificar a resposta antes da integração.

Guarde a chave em uma variável de ambiente. Não a inclua no código-fonte, em um repositório, planilha ou aplicativo cliente. Faça a solicitação, salve um exemplo de JSON bem-sucedido com a data e o nome da rota e use-o como base para o adaptador de normalização e os testes.

Uma solicitação mínima funcional em Python

A referência informa que a resposta do feed de usuários contém um status externo e um objeto tiktok, no qual a lista de publicações fica em aweme_list. Os registros podem incluir ID, legenda, horário de publicação, autor e estatísticas. Os campos e valores concretos devem ser conferidos na resposta recebida: alguns dados podem estar ausentes.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
ENDPOINT_URL = "https://tiktok.evelode.com/getUserFeed"


def fetch_user_feed(handle: str, count: int = 20) -> dict:
    response = requests.get(
        ENDPOINT_URL,
        params={
            "license_key": API_KEY,
            "query": handle,
            "count": count,
            "region": "US",
        },
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if not isinstance(payload, dict):
        raise ValueError("Era esperado um objeto JSON")
    if payload.get("status") != "ok":
        raise RuntimeError(f"A API retornou o status: {payload.get('status')!r}")
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise ValueError("O objeto tiktok não está presente na resposta")
    return payload


def save_raw(payload: dict, account: str, output_dir: str = "data/raw") -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_account = "".join(c for c in account if c.isalnum() or c in "-_@")
    path = Path(output_dir) / f"{safe_account}_{collected_at.replace(':', '-')}.json"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        json.dumps(
            {"collected_at": collected_at, "account": account, "payload": payload},
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return path


def normalize_items(payload: dict, account: str, collected_at: str) -> list:
    items = payload["tiktok"].get("aweme_list", [])
    if not isinstance(items, list):
        raise ValueError("O campo tiktok.aweme_list não é uma lista")

    observations = []
    for item in items:
        if not isinstance(item, dict):
            continue
        stats = item.get("statistics")
        stats = stats if isinstance(stats, dict) else {}
        author = item.get("author")
        author = author if isinstance(author, dict) else {}
        observations.append({
            "account_handle": account,
            "collected_at": collected_at,
            "video_id": item.get("aweme_id"),
            "caption": item.get("desc"),
            "published_at_epoch": item.get("create_time"),
            "author_handle": author.get("unique_id"),
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "shares": stats.get("share_count"),
        })
    return observations


if __name__ == "__main__":
    account = "creator_handle"
    payload = fetch_user_feed(account, count=20)
    collected_at = datetime.now(timezone.utc).isoformat()
    raw_path = save_raw(payload, account)
    observations = normalize_items(payload, account, collected_at)
    print(f"Salvo: {raw_path}; registros: {len(observations)}")

Antes de executar, defina JSONSCRAPER_TIKTOK_LICENSE_KEY no ambiente e instale a biblioteca requests. O código verifica a resposta HTTP, o status externo e a presença do objeto tiktok, e então lê aweme_list. Ele guarda o JSON bruto e extrai os campos confirmados pela documentação, mantendo vazios os valores ausentes. O feed obtido é o conjunto de resultados retornado pela API; por isso, o relatório deve estar associado ao horário da solicitação e ao perfil selecionado.

Guarde registros e compare publicações

SQLite ou PostgreSQL são boas opções para projetos pequenos. Guarde a resposta bruta separadamente dos registros normalizados. A tabela de observações pode usar este esquema:

CREATE TABLE IF NOT EXISTS video_observations (
    account_handle TEXT NOT NULL,
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    published_at_epoch INTEGER,
    caption TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    raw_file TEXT,
    PRIMARY KEY (account_handle, video_id, collected_at)
);

Cada execução acrescenta um novo registro em vez de sobrescrever o anterior. Ao comparar contadores, calcule a diferença apenas quando ambos os valores estiverem disponíveis para o mesmo vídeo. Inclua no relatório o intervalo entre as solicitações e o horário das observações: esses dados explicam em quanto tempo a mudança se acumulou.

Para agrupar por tema, comece com um pequeno vocabulário de categorias e, se necessário, acrescente um classificador ou modelo de linguagem. Envie ao modelo legendas limpas, IDs de publicações e categorias predefinidas. Um resultado estruturado com categoria e justificativa curta é mais fácil de comparar entre execuções do que uma análise aberta.

Adicione um modelo de linguagem com classificação verificável

O modelo pode distribuir preliminarmente as legendas por temas como “receitas”, “treinos”, “avaliações de produtos” e “histórias pessoais”. Para começar, classifique manualmente algumas dezenas de publicações. Compare as etiquetas automáticas com esses exemplos, refine as definições das categorias e repita a avaliação após alterar o prompt ou o modelo.

É mais confiável calcular com código comum o número de novas publicações, a mediana dos contadores e a diferença entre registros. Use o modelo para classificar o texto e preparar breves explicações. Mantenha as legendas originais e as observações numéricas disponíveis para conferência.

Guarde junto com cada etiqueta o ID da publicação, a versão do prompt, a data de processamento e o modelo utilizado. Se houver uma classificação incorreta, o analista poderá localizar a legenda e corrigir a regra. É útil armazenar separadamente a etiqueta inicial e a correção manual.

Automatize a execução

Depois de verificar uma execução manual, migre o script para cron, GitHub Actions, n8n ou Make. O agendador inicia a coleta conforme o cronograma, recebe a lista de contas, registra o resultado e envia o relatório para o armazenamento escolhido. Guarde a chave nos segredos do ambiente de execução. Primeiro, teste o processo com uma conta e só então amplie a lista.

Divida a automação em etapas: fila de contas, chamada à API, armazenamento da resposta bruta, normalização, gravação do registro e preparação do relatório. Uma falha em uma conta não deve apagar os resultados das demais. É possível tornar uma nova execução idempotente usando um ID de execução e restrições de unicidade no banco de dados.

Registre o horário, a conta, a rota, o status HTTP, a duração, o número de itens processados e a descrição do erro. Não grave a chave da API nos logs. O parâmetro cache_timeout está indicado para /getUserFeed; ele pode ser incluído na solicitação se for necessário definir o período de armazenamento em cache. A referência da API informa que o valor padrão é de 3600 segundos.

Verifique a qualidade antes de publicar o relatório

Compare alguns registros normalizados com o JSON original. Verifique se uma nova coleta identifica o mesmo vídeo pelo ID, se as datas são interpretadas como esperado, se os campos numéricos têm o tipo adequado e se a proporção de dados ausentes é conhecida. Depois, execute a coleta novamente e confirme que o banco manteve as observações antigas e acrescentou as novas.

Não misture contas nem períodos de coleta. Para comparar temas, use períodos de igual duração ou mostre explicitamente sua duração no relatório. Para analisar a evolução dos contadores, registre o intervalo entre as observações para que o leitor entenda a escala dos períodos comparados.

Guarde o texto original da legenda e crie uma versão limpa separadamente. Emojis, hashtags, links e particularidades linguísticas podem influenciar a classificação; campos separados ajudam a verificar o efeito da limpeza e a recalcular categorias sem uma nova chamada à API.

Que resultados o pipeline pode gerar

Após alguns ciclos, a equipe terá uma tabela de publicações e registros, um agrupamento preliminar das legendas por tema e um relatório das novas publicações no período selecionado. Isso ajuda a escolher vídeos para análise especializada, identificar temas recorrentes nas contas selecionadas e verificar mudanças nos contadores públicos entre as datas das observações.

Com base nesses dados, é possível formular hipóteses para o calendário editorial: comparar maneiras de apresentar uma mesma questão ou destacar temas para testar no próprio conteúdo. Para avaliar o impacto comercial, compare as observações com os dados internos das campanhas.

Para começar, selecione uma pequena lista de contas públicas e teste GET /getUserFeed na coleção de solicitações do Postman. Transfira para o código apenas os parâmetros e caminhos de campos confirmados pela documentação da rota e por sua resposta real.

Coleta responsável de dados públicos

Limite a lista de contas ao objetivo da pesquisa, colete apenas os campos necessários e defina um prazo para guardar as respostas brutas. Antes de usar os dados comercialmente, verifique os termos aplicáveis da plataforma e os requisitos de proteção de dados pessoais da sua jurisdição. O controle de acesso e a exclusão de registros antigos ajudam a manter o processo dentro dos limites da tarefa.

Antes de enviar dados a um serviço de IA, remova os campos de que o modelo não precisa. No relatório, informe o ID da publicação e a data da observação para que um funcionário possa localizar o registro e verificar a base da conclusão.

Lista rápida para iniciar

1. Defina o nicho, a lista de contas, o período e as perguntas da análise.
2. Confira os parâmetros de GET /getUserFeed na documentação e a resposta real no Postman.
3. Guarde um exemplo de JSON e configure o normalizador para os campos confirmados.
4. Registre a resposta bruta e os registros separados com o horário da coleta.
5. Calcule os indicadores numéricos com código; use IA para o agrupamento preliminar do texto.
6. Configure o agendamento, os logs, o tratamento de novas tentativas e o prazo de armazenamento.

Assim, o monitoramento se torna uma pesquisa reproduzível: cada conclusão está associada a uma publicação e ao horário da observação, e o código se baseia no esquema real da rota selecionada.