Como criar um relatório semanal do TikTok sobre a reação do público ao lançamento de um produto

Após o lançamento de um aplicativo ou de um novo recurso, o feedback se dispersa rapidamente por vídeos curtos. Uma pessoa de marketing encontra alguns vídeos manualmente e encaminha os links no chat; mais tarde, a pessoa analista não consegue saber quais publicações já foram contabilizadas nem como as visualizações mudaram. Uma solução prática é coletar regularmente resultados de busca com algumas consultas estáveis, salvar as respostas originais e criar relatórios usando campos confirmados.

Neste guia, configuraremos essa coleta para um caso específico: uma equipe lançou um novo recurso e quer acompanhar semanalmente vídeos públicos do TikTok cuja descrição mencione o nome do produto, um recurso principal ou um problema típico dos usuários. Trata-se de monitorar uma amostra encontrada pela busca: a API retorna resultados conforme a consulta e os parâmetros, não uma lista garantida de todas as publicações sobre o lançamento.

Primeiro, defina qual sinal a equipe precisa

Um grande número de visualizações, por si só, explica pouco sobre o que fazer a seguir. É mais útil para a equipe saber quais perguntas se repetem, quais casos de uso as pessoas demonstram e quais vídeos recebem reações públicas relevantes. Portanto, comece formulando algumas consultas de busca e decidindo quais campos entrarão no relatório.

Por exemplo, para o lançamento de uma ferramenta de planejamento de publicações, é possível testar as consultas «nome do produto», «planejador de conteúdo» e «como agendar no TikTok». As frases devem refletir as diferentes formas como as pessoas podem descrever o mesmo tema. Registre-as junto com a data de início do monitoramento e a região para que as coletas posteriores possam ser comparadas com as mesmas configurações.

Uma tabela mínima pode conter o horário da coleta, a consulta de busca, o identificador do vídeo, o link, a descrição, o nome e o identificador do autor e os valores disponíveis de visualizações, curtidas e comentários. A TikTok Scraper API documenta campos como aweme_id, desc, share_url, dados do autor e parte das estatísticas nos resultados de busca. Verifique cada campo em cada objeto: algumas métricas podem estar ausentes.

Configure a busca documentada

Para buscar vídeos, use a rota GET /searchVideo no endereço-base https://tiktok.evelode.com. A documentação lista o parâmetro obrigatório keyword e os parâmetros opcionais count, cursor, date_posted, sort_by, region e cache_timeout. Os valores aceitos para o filtro de data incluem this-week, e os valores de ordenação incluem relevance, most-liked e date-posted. Consulte o guia de rotas da TikTok API para confirmar a finalidade e os nomes desses parâmetros.

A chave de licença é enviada como parâmetro de consulta license_key. Em um script de produção, leia-a da variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, não a inclua no código-fonte e não a imprima nos logs. Este exemplo é compatível com Python 3.8+ e usa o pacote requests:

import os
import requests

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


def search_videos(keyword, cursor=None):
    params = {
        "license_key": API_KEY,
        "keyword": keyword,
        "count": 20,
        "date_posted": "this-week",
        "sort_by": "date-posted",
        "region": "US",
    }
    if cursor is not None:
        params["cursor"] = cursor

    response = requests.get(
        f"{BASE_URL}/searchVideo",
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("A TikTok API retornou um status diferente de ok")

    return payload["tiktok"]


result = search_videos("content planning app")
print("Objetos encontrados:", len(result.get("aweme_list", [])))

O script verifica erros HTTP e o status externo da resposta. Uma resposta HTTP bem-sucedida não garante, por si só, que a busca contenha vídeos: quando a amostra está vazia, a lista pode não ter itens. Na primeira execução, é útil salvar a resposta completa em um armazenamento protegido para comparar os objetos reais com a tabela de campos normalizados.

Trate os dois formatos de resposta da busca

Os resultados da busca têm uma particularidade estrutural importante. Os vídeos podem estar diretamente em tiktok.aweme_list ou dentro de tiktok.search_item_list[].aweme_info. Se o processador ler apenas a primeira lista, poderá deixar de fora resultados presentes no segundo formato.

Adicione um pequeno normalizador que aceite as duas estruturas e ignore sem problemas os itens sem um objeto de vídeo aninhado:

def extract_awemes(tiktok):
    items = list(tiktok.get("aweme_list") or [])

    for item in tiktok.get("search_item_list") or []:
        aweme = item.get("aweme_info")
        if aweme:
            items.append(aweme)

    return items


def normalize(aweme, keyword, collected_at):
    author = aweme.get("author") or {}
    stats = aweme.get("statistics") or {}

    return {
        "collected_at": collected_at,
        "keyword": keyword,
        "video_id": aweme.get("aweme_id"),
        "posted_at": aweme.get("create_time"),
        "description": aweme.get("desc"),
        "share_url": aweme.get("share_url"),
        "author_id": author.get("uid"),
        "author_name": author.get("nickname"),
        "views": stats.get("play_count"),
        "likes": stats.get("digg_count"),
        "comments": stats.get("comment_count"),
        "shares": stats.get("share_count"),
    }

Um valor ausente continua sendo None. Não o substitua por zero: zero significa um valor medido, enquanto None preserva a informação de que o campo não foi retornado. Essa diferença afeta médias, proporções e quaisquer conclusões da equipe.

Guarde o histórico, não apenas o retrato atual

Para acompanhar a evolução, armazene registros de observação separados. O identificador do vídeo é adequado para deduplicar publicações, mas não para apagar o histórico: quando o mesmo vídeo aparece novamente na coleta seguinte, ele gera um novo ponto de observação. Por exemplo, uma chave única para a tabela de observações pode ser composta por video_id e collected_at; salve o link e a descrição no registro para facilitar a verificação.

Um esquema mínimo em SQLite é útil para um protótipo:

import sqlite3

conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    keyword TEXT NOT NULL,
    posted_at INTEGER,
    description TEXT,
    share_url TEXT,
    author_id TEXT,
    author_name TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()

Na prática, normalize o horário da coleta para UTC, salve o JSON original separadamente e adicione uma coluna para a versão do esquema. A resposta original ajuda a conferir a transformação quando a estrutura de novos objetos difere da habitual. Para publicações encontradas por várias consultas, armazene as consultas correspondentes em uma tabela relacionada separada ou combine-as ao gerar o relatório.

Paginação: continue apenas com o cursor da resposta

O parâmetro cursor serve para continuar a busca. Seu valor vem da resposta anterior e deve ser enviado de volta sem alterações; a coleta termina quando has_more deixa de indicar que há mais resultados ou quando o limite definido é atingido. Trate o cursor como opaco: não o calcule por conta própria nem o substitua por um contador de páginas.

def collect_pages(keyword, max_pages=3):
    cursor = None
    collected = []

    for _ in range(max_pages):
        page = search_videos(keyword, cursor)
        collected.extend(extract_awemes(page))

        if not page.get("has_more"):
            break
        cursor = page.get("cursor")
        if cursor is None:
            break

    return collected

Limitar o número de páginas torna previsível o volume de solicitações da tarefa recorrente. Registre o número de páginas e o valor de has_more no log da execução: isso dá contexto ao relatório da amostra. Mesmo com paginação, o resultado descreve as respostas recebidas da API e o limite de coleta definido; não é uma estimativa de todas as publicações da plataforma.

Crie um relatório recorrente

Agende a coleta semanalmente ou com maior frequência, se a equipe precisar de sinais mais frequentes. Em cada execução, registre a lista de consultas, os parâmetros, o horário, o número de objetos recebidos e o número de identificadores únicos. Conte separadamente as publicações observadas pela primeira vez nessa execução e aquelas que já haviam aparecido.

Quatro visualizações simples são úteis no relatório:

• Novos vídeos: links, descrições, datas de publicação e a consulta pela qual cada vídeo foi encontrado.
• Temas recorrentes: agrupamento das descrições em categorias definidas manualmente, como «erro de configuração», «pedido de recurso» e «visão geral de um caso de uso».
• Reações públicas: visualizações, curtidas, comentários e compartilhamentos disponíveis, apresentados junto ao horário da observação.
• Sinais para verificar: novas formulações, perguntas frequentes ou vídeos que valha a pena uma pessoa da equipe analisar.

Não chame a diferença entre duas observações de «novas curtidas» sem verificar a semântica e a atualidade dos valores na resposta. Uma formulação correta é «valor da métrica na resposta mais recente recebida» e «diferença entre as observações armazenadas». Assim, a equipe vê exatamente o que foi calculado e pode abrir a publicação original antes de tomar uma decisão.

Use IA na etapa de classificação, não no lugar da coleta

Após a normalização, é possível enviar as descrições dos vídeos a um modelo para classificá-las em categorias predefinidas. Envie apenas os campos de texto necessários e solicite um resultado estruturado: categoria, breve justificativa, nível de confiança e trecho da descrição que fundamenta o rótulo. Mantenha a publicação original junto ao rótulo para que uma pessoa analista possa verificar os casos duvidosos.

O fluxo de trabalho continua simples: um agendador inicia a coleta; o Python verifica a resposta e salva o JSON; outra tarefa normaliza os novos registros; o classificador processa apenas as novas descrições; e o relatório é gerado a partir do banco de dados e enviado ao canal escolhido pela equipe. A TikTok Scraper API fornece os dados da busca; a classificação e o envio do relatório são lógicas de integração próprias, que podem ser implementadas em Python, n8n ou Make.

Para reduzir o ruído, defina um vocabulário de categorias antes de enviar os dados ao modelo e verifique periodicamente uma amostra rotulada manualmente. Para descrições curtas ou ambíguas, é útil ter o status «contexto insuficiente», em vez de forçar a escolha de uma categoria. Os rótulos da IA ajudam a organizar a fila de revisão, mas as conclusões sobre problemas dos usuários devem ser confirmadas pela leitura das publicações e pela comparação de várias observações.

Erros, novas tentativas e uso seguro da chave

Uma solicitação de rede pode terminar em timeout, erro temporário ou resposta que não pôde ser interpretada como JSON. Separe o tratamento em etapas: solicitação, verificação do código HTTP, análise do JSON, verificação do status externo, normalização e gravação. Para falhas temporárias, use um número limitado de novas tentativas com intervalos crescentes; registre os erros permanentes para análise posterior e não marque a execução como bem-sucedida.

Armazene a chave em um gerenciador de segredos do ambiente de execução ou em uma variável de ambiente. Como a API aceita license_key na string de consulta, evite registrar a URL completa e os parâmetros da solicitação: eles conterão o segredo. Para diagnóstico, registre a rota, o código de resposta, a duração, a consulta e o identificador da tarefa, removendo a chave dos logs.

Defina a frequência e o volume da amostra conforme a sua tarefa e os termos de uso da plataforma. A coleta de dados públicos deve se limitar ao que é realmente necessário para a análise; as regras internas da equipe devem especificar como descrições, links e identificadores de autores serão armazenados. As respostas da API e as métricas podem estar incompletas ou mudar entre observações; por isso, o relatório deve registrar o horário da coleta e a origem de cada linha.

Resultado: de links manuais a um histórico verificável

Depois da configuração, a equipe terá uma lista atualizada regularmente de vídeos encontrados, respostas originais para auditoria, uma tabela de métricas públicas disponíveis e um panorama de temas recorrentes. Isso ajuda a perceber mais rapidamente as dúvidas sobre um novo recurso, encontrar exemplos de casos de uso e selecionar publicações para análise manual. A comparação das observações mostra como mudam os valores armazenados dos vídeos já encontrados, enquanto o registro das consultas explica como a amostra foi formada.

Comece com uma consulta e um limite pequeno de páginas; verifique a estrutura real da resposta e, em seguida, adicione outras formulações e um agendamento. Antes de levar o protótipo para produção, defina regras de deduplicação, armazenamento e tratamento de erros. As rotas e os parâmetros atuais estão disponíveis na documentação oficial da API; a página da TikTok Scraper API descreve os recursos e permite iniciar os testes.