Como detectar vídeos do TikTok com engajamento crescente sem comparar visualizações brutas

Para saber se um vídeo específico do TikTok está recebendo mais interação, compare suas métricas públicas com o registro anterior. Uma única busca mostra o total acumulado de visualizações e reações; coletar novamente os mesmos vídeos encontrados permite observar a mudança entre duas execuções. A seguir, um pipeline mínimo e funcional em Python: consulta a busca, salva métricas em CSV e calcula a variação.

O que esse monitoramento mede?

O script é útil para profissionais de marketing, analistas ou desenvolvedores que precisam de uma lista de vídeos encontrados sobre determinado tema e de um histórico de observações que possa ser verificado. Por exemplo, uma equipe pode acompanhar regularmente vídeos sobre o lançamento de um produto ou uma busca específica do público e identificar quais vídeos receberam mais visualizações, curtidas, comentários ou compartilhamentos desde a verificação anterior.

A unidade principal de comparação é o vídeo, identificado por aweme_id. Para cada registro, são salvos o horário da coleta, o identificador, a descrição, o URL, o nome do autor e os contadores disponíveis. Em seguida, os dois registros são associados pelo identificador. Assim, o aumento de visualizações de um vídeo não se confunde com o total acumulado de outro.

O resultado descreve apenas os vídeos retornados por uma consulta de busca específica em uma execução específica. Os resultados da busca podem mudar, e alguns campos de estatísticas podem estar ausentes. Por isso, é útil guardar os próprios registros e os horários da coleta, tratando o relatório como observação dos vídeos já encontrados, e não como um catálogo completo de publicações sobre o tema.

Como funciona a coleta pela API?

A documentação da TikTok Scraper API descreve a rota GET /searchVideo. A busca exige o texto keyword; entre os parâmetros opcionais estão count, region, sort_by e date_posted. A chave da API é transmitida como license_key. A referência informa o endereço-base https://tiktok.evelode.com.

A resposta contém um status externo e um objeto tiktok. Os vídeos dos resultados da busca podem estar em tiktok.aweme_list ou dentro de tiktok.search_item_list[].aweme_info. O processador abaixo aceita as duas estruturas. As métricas são obtidas de statistics, incluindo play_count, digg_count, comment_count e share_count; os valores ausentes são salvos em branco, em vez de substituídos por zero.

A referência das rotas lista cursor para percorrer os resultados da busca e informa as opções permitidas de date_posted e sort_by. Para um monitoramento simples e repetível, basta começar com uma página de resultados, registrar a resposta e adicionar paginação somente se necessário. Se precisar dela, envie o cursor recebido sem modificá-lo.

Exemplo funcional em Python

Instale a biblioteca de requisições com o comando python -m pip install requests e defina a chave na variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. O script recebe uma frase de busca como argumento e acrescenta os registros encontrados a um único arquivo CSV. O código é compatível com Python 3.8 ou superior.

import csv
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
CSV_PATH = Path("tiktok_video_snapshots.csv")
FIELDS = [
    "collected_at", "aweme_id", "author", "description", "share_url",
    "play_count", "digg_count", "comment_count", "share_count",
]


def extract_items(payload):
    """Support the observed search response layouts."""
    data = payload.get("tiktok") or {}
    items = data.get("aweme_list") or []
    if items:
        return items

    found = []
    for result in data.get("search_item_list") or []:
        info = result.get("aweme_info")
        if info:
            found.append(info)
    return found


def main():
    key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if not key:
        raise SystemExit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY first")
    if len(sys.argv) < 2:
        raise SystemExit('Usage: python collect.py "search phrase"')

    params = {
        "license_key": key,
        "keyword": sys.argv[1],
        "count": 20,
        "region": "US",
        "sort_by": "relevance",
        "date_posted": "this-week",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API returned a non-ok outer status")
    data = payload.get("tiktok") or {}
    items = extract_items(payload)
    collected_at = datetime.now(timezone.utc).isoformat()

    rows = []
    for item in items:
        stats = item.get("statistics") or {}
        author = item.get("author") or {}
        rows.append({
            "collected_at": collected_at,
            "aweme_id": item.get("aweme_id"),
            "author": author.get("unique_id") or author.get("nickname"),
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "play_count": stats.get("play_count"),
            "digg_count": stats.get("digg_count"),
            "comment_count": stats.get("comment_count"),
            "share_count": stats.get("share_count"),
        })

    write_header = not CSV_PATH.exists()
    with CSV_PATH.open("a", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=FIELDS)
        if write_header:
            writer.writeheader()
        writer.writerows(rows)

    print("Saved", len(rows), "returned videos")
    print("has_more:", data.get("has_more"), "cursor:", data.get("cursor"))


if __name__ == "__main__":
    main()

Por exemplo, execute python collect.py "consulta sobre um produto". A biblioteca inclui a chave nos parâmetros do URL; o script não a exibe no terminal. Não salve o URL completo da consulta em registros públicos, pois ele contém a chave. Em um sistema de produção, use um gerenciador de segredos e restrinja o acesso ao arquivo de registros.

Como calcular o aumento entre execuções?

O script grava intencionalmente todas as observações, sem substituir os valores anteriores. O pequeno analisador a seguir associa os dois registros mais recentes de cada vídeo e exibe a diferença entre os contadores. Se uma métrica não tiver valor em um dos dois registros, o resultado será indicado como indisponível.

import csv
from collections import defaultdict
from pathlib import Path

rows_by_video = defaultdict(list)
with Path("tiktok_video_snapshots.csv").open(encoding="utf-8", newline="") as file:
    for row in csv.DictReader(file):
        if row["aweme_id"]:
            rows_by_video[row["aweme_id"]].append(row)

metrics = ("play_count", "digg_count", "comment_count", "share_count")
for video_id, snapshots in rows_by_video.items():
    snapshots.sort(key=lambda row: row["collected_at"])
    if len(snapshots) < 2:
        continue
    previous, latest = snapshots[-2], snapshots[-1]
    changes = {}
    for metric in metrics:
        old, new = previous[metric], latest[metric]
        changes[metric] = int(new) - int(old) if old and new else None
    print(video_id, changes, latest["share_url"])

A variação é a diferença entre dois valores salvos, não uma taxa de crescimento com periodicidade garantida. Se as execuções ocorrerem em intervalos diferentes, inclua o cálculo do tempo transcorrido entre collected_at e compare o aumento pelo intervalo real. Os contadores podem mudar entre as observações; os horários salvos mostram quando os valores utilizados foram obtidos.

Como automatizar e interpretar o relatório?

Para gerar um relatório diário, programe a coleta em um servidor ou em um sistema de integração contínua, defina uma lista fixa de frases de busca e salve o CSV ou carregue as linhas em um banco de dados. Em execuções repetidas, remova duplicatas dentro de cada registro de coleta pelo aweme_id, caso os resultados contenham repetições. Para manter o histórico, guarde o JSON original junto com as colunas normalizadas: isso facilita o reprocessamento se o esquema do relatório mudar.

É útil exibir na tabela o ID e o URL do vídeo, o autor, a descrição, o horário da coleta e as variações de cada métrica. Ordenar pelo aumento de visualizações ajuda a avaliar a disseminação, enquanto o aumento de comentários ou compartilhamentos pode destacar outro tipo de reação. Não combine esses indicadores em uma classificação única sem definir uma regra explícita: cada contador tem um significado próprio.

O agendador pode enviar o relatório por e-mail, para uma planilha ou para um canal interno, mas essa etapa fica a cargo da sua infraestrutura — o exemplo acima apenas coleta e analisa os dados. Para uma coleta mais abrangente, é possível percorrer as páginas de resultados, guardar o cursor e interromper o ciclo quando a API informar que não há páginas seguintes. O cursor de busca é um valor opaco recebido na resposta; não o calcule por conta própria. Mesmo percorrendo as páginas, os dados descrevem os resultados retornados, sem garantir uma lista completa de todas as publicações relevantes.

O resultado prático esperado é um registro reproduzível de observações e uma tabela de alterações dos vídeos encontrados. Isso ajuda a perceber quais publicações tiveram mudanças nos contadores públicos entre as verificações e a encaminhar links específicos a um especialista para uma análise de conteúdo. Mais detalhes sobre o produto e o acesso à API estão na página da TikTok Scraper API.

O que verificar antes de programar as execuções?

• Confirme que o status externo da resposta é ok antes de processar tiktok.
• Verifique as duas estruturas possíveis dos itens de busca; a ausência de uma lista deve resultar em uma coleta vazia, não em um erro.
• Guarde os valores originais e os registros de data e hora. Uma métrica vazia deve continuar vazia.
• Use as mesmas consultas e os mesmos parâmetros para tornar a comparação dos registros mais clara; anote junto ao relatório as mudanças nessas configurações.
• Monitore a frequência das execuções, os erros HTTP e o tamanho do histórico, além de cumprir as regras aplicáveis da plataforma e os requisitos de tratamento de dados.

Em resumo, para obter um resultado observável, basta repetir a mesma busca, identificar os vídeos pelo aweme_id e comparar as métricas salvas ao longo do tempo. Essa abordagem responde a uma questão prática específica — quais dos vídeos já encontrados tiveram mudanças nos contadores públicos entre duas verificações — e mantém os dados originais disponíveis para auditoria e processamento posterior.