jsonscraper
Mercados
Voltar ao jornal

Como transformar a busca do TikTok em um registro semanal de alterações

Um script em Python salva novos vídeos encontrados, compara os IDs e gera um CSV para revisar temas regularmente

Política editorial Comunique um erro

Um relatório semanal de buscas no TikTok é útil quando mostra quais vídeos apareceram na coleta mais recente desde a execução anterior. Para isso, basta salvar os identificadores dos vídeos já encontrados e acrescentar ao CSV os novos resultados. A seguir, apresentamos um script reproduzível em Python com a TikTok Scraper API: ele busca vídeos por palavra-chave, interpreta os dois formatos de resposta documentados e mantém um banco de dados local de IDs.

Objetivo: identificar novos registros, em vez de revisar todos os resultados

Uma equipe de suporte, um pesquisador de mercado ou um analista de conteúdo pode precisar de uma coleta regular de vídeos públicos para uma busca relacionada a um produto. Se os resultados forem exportados por completo a cada execução, os vídeos repetidos dificultam a revisão, e os novos registros podem se perder entre os já processados. Um registro de identificadores torna comparáveis os resultados de cada execução: o CSV contém apenas vídeos novos para esse processo, além dos principais campos retornados pela resposta.

Esse registro responde a uma pergunta limitada, mas prática: quais itens apareceram na resposta da execução atual e não estavam no conjunto de IDs salvo? Isso é útil para organizar uma fila de revisão manual e transferir dados para uma planilha ou análise posterior. A coleta reflete os resultados da API para a busca especificada; por si só, não descreve todas as publicações do TikTok.

O que preparar

  • Python 3.8 ou mais recente.
  • Acesso à TikTok Scraper API e uma chave de licença.
  • Uma busca que possa ser repetida sem mudar de sentido, como o nome de um produto ou uma frase específica.

Salve a chave na variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, e não no arquivo do script. No exemplo abaixo, a chave é enviada como parâmetro de consulta license_key, de acordo com o esquema da API. Não a imprima no log de execução.

export JSONSCRAPER_TIKTOK_LICENSE_KEY="sua_chave"
python -m pip install requests

No Windows PowerShell, é possível definir a variável para a sessão atual assim: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="sua_chave". Não inclua segredos reais no Git nem em um CSV compartilhado.

Integração: fazer a busca e normalizar o JSON

Para buscar vídeos, a documentação descreve a rota GET /searchVideo, que exige o parâmetro keyword. A consulta também pode especificar count, região, ordenação, filtro de período e cursor para percorrer os resultados. Neste exemplo mínimo, usamos apenas a palavra-chave, o número de itens solicitados e a região dos EUA. O guia de rotas da API do TikTok lista os nomes exatos dos parâmetros.

A estrutura da resposta de busca exige atenção especial: o array aweme_list pode estar vazio, e os dados dos vídeos podem aparecer em search_item_list, com os dados aninhados em aweme_info. Por isso, o código verifica os dois caminhos, depois combina os itens e elimina duplicatas com base em aweme_id. Isso evita que um JSON interpretado corretamente seja convertido por engano em um relatório vazio.

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "nome do produto"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")

license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
    raise RuntimeError("Defina JSONSCRAPER_TIKTOK_LICENSE_KEY")

response = requests.get(
    BASE_URL,
    params={
        "license_key": license_key,
        "keyword": KEYWORD,
        "count": COUNT,
        "region": REGION,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

# O exemplo de resposta contém status externo e um objeto tiktok aninhado.
if "status" in data and data["status"] != "ok":
    raise RuntimeError("A API retornou um status diferente de ok")

tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
    info = entry.get("aweme_info")
    if isinstance(info, dict):
        items.append(info)

# Itens únicos da resposta atual, mantendo a ordem.
current = {}
for item in items:
    video_id = item.get("aweme_id")
    if video_id:
        current[str(video_id)] = item

if STATE_FILE.exists():
    seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
    seen = set()

new_items = [(video_id, item) for video_id, item in current.items()
             if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()

fields = ["collected_at_utc", "query", "aweme_id", "created_at",
          "author", "description", "share_url", "play_count",
          "digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=fields)
    if write_header:
        writer.writeheader()
    for video_id, item in new_items:
        author = item.get("author") or {}
        stats = item.get("statistics") or {}
        writer.writerow({
            "collected_at_utc": run_time,
            "query": KEYWORD,
            "aweme_id": video_id,
            "created_at": item.get("create_time"),
            "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"),
        })

seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"Na resposta: {len(current)} vídeos únicos; novos: {len(new_items)}")

O script grava células vazias quando os valores não estão presentes no JSON: determinados campos e métricas podem não aparecer em um registro específico. O código não substitui valores ausentes por zero nem interpreta zero como ausência de dados. O horário da coleta é registrado separadamente do horário de publicação, que a API retorna no campo create_time.

Como funciona a verificação de alterações

  1. A consulta retorna uma página de resultados de busca para a palavra-chave especificada.
  2. O normalizador reúne registros de aweme_list e search_item_list[].aweme_info.
  3. O script elimina duplicatas dentro da resposta com base no ID do vídeo.
  4. Os identificadores são comparados com o registro JSON local.
  5. Os novos IDs são acrescentados ao CSV e, em seguida, o conjunto completo de IDs encontrados é salvo para a próxima execução.
Artigo: Como transformar a busca do TikTok em um registro semanal de alterações
Resumo: Configure uma coleta recorrente de vídeos do TikTok por palavra-chave: processe os dois formatos de resposta da API, elimine duplicatas e salve apenas os novos registros para o relatório semanal.
Função da imagem: ilustração complementar 2 — um aspecto específico diferente
Seção: Como funciona a verificação de alterações
Tema visual: Infográfico claro em russo que mostra cinco etapas verificadas do fluxo de trabalho com os rótulos: Busca / Dois arrays de resposta / Eliminação de duplicatas por awe
O diagrama mostra o caminho da resposta da busca até o CSV de novos registros e o registro JSON da próxima execução.© jsonscraper · ilustração gerada por IA
Artigo: Como transformar a busca do TikTok em um registro semanal de alterações
Resumo: Configure uma coleta recorrente de vídeos do TikTok por palavra-chave: processe os dois formatos de resposta da API, elimine duplicatas e salve apenas os novos registros para o relatório semanal.
Função da imagem: capa — a ideia central
Seção: Como funciona a verificação de alterações
Tema visual: Natureza-morta editorial de uma revisão semanal de dados: cartões transparentes empilhados que representam resultados de busca de vídeos curtos públicos, com um cartão recém-aparecido ao lado de um compac
Os identificadores novos para o registro local são separados dos vídeos encontrados novamente.© jsonscraper · criado com IA

Visualizar esse processo é útil ao compartilhar o script com colegas: o CSV é um registro incremental, enquanto o JSON guarda o estado usado para eliminar duplicatas. Eles podem ser armazenados separadamente do código e incluídos no mesmo backup. Para uma execução em equipe ou na nuvem, substitua o arquivo JSON local por um armazenamento persistente adequado e preveja uma atualização atômica do estado para impedir que execuções paralelas sobrescrevam os dados umas das outras.

Execuções recorrentes e paginação

Agende a execução com um programador do sistema operacional, uma tarefa de CI ou um fluxo de automação. Não altere a palavra-chave sem registrar sua versão: buscas diferentes geram conjuntos diferentes, e misturá-los no mesmo registro dificulta a interpretação. Para simplificar, o script apresentado usa uma única busca; é possível processar uma lista de buscas em um loop, salvando o campo query em cada linha.

A API oferece suporte a cursor para percorrer os resultados da busca. Se você adicionar paginação, envie o cursor da resposta anterior, armazene-o como um valor opaco e interrompa a navegação quando não precisar de mais páginas. O limite count define o número de itens solicitados, mas a quantidade efetiva de registros deve ser determinada pela resposta. Mesmo com várias páginas, você terá páginas de resultados de busca, e não a garantia de cobrir toda a plataforma.

Este script não inclui intencionalmente classificação automática de texto nem declarações sobre “tendências”. O CSV facilita a identificação de novos registros encontrados; depois, um analista pode classificá-los por tema, intenção ou tipo de pergunta e verificar os exemplos manualmente. Se você integrar um modelo de linguagem, envie apenas os campos de texto necessários e peça que ele retorne as categorias junto com o ID original, para que o resultado possa ser conferido e associado ao registro.

Verificações e erros comuns

  • Erro HTTP. raise_for_status() interrompe a execução diante de um código HTTP fora do intervalo de sucesso. Verifique a disponibilidade da API, os parâmetros e a conta antes de atualizar o arquivo de estado.
  • O status da API é diferente de ok. O script para antes de gravar os resultados se a resposta contiver um campo status de nível superior com outro valor. Isso preserva o registro anterior e ajuda a evitar que uma resposta inválida seja confundida com resultados vazios.
  • Lista vazia em aweme_list. Verifique também search_item_list; o código considera as duas estruturas.
  • Vídeos repetidos entre execuções. Isso é esperado em páginas de resultados de busca que se sobrepõem: os vídeos não voltarão ao relatório se o ID já estiver salvo.
  • Métrica ausente. A célula permanece vazia. Nos cálculos, diferencie os valores ausentes dos zeros reais.
  • Estado perdido. O script considerará novos todos os IDs retornados. Faça backup de seen_video_ids.json junto com o CSV ou use um banco de dados persistente.

Ao automatizar o processo, salve informações de diagnóstico sem incluir a chave: horário da execução, código HTTP, status da API, quantidade de registros interpretados e número de IDs novos. Isso ajuda a distinguir a ausência de novos vídeos de uma falha na consulta. Se precisar rever o esquema posteriormente, arquive a resposta completa original separadamente; limite o acesso e o período de armazenamento de acordo com as necessidades da equipe.

Resultado

Após a execução, você terá um CSV com vídeos cujos IDs ainda não estavam no registro, descrições, links e campos públicos disponíveis, além do estado JSON para comparação na próxima execução. Esse resultado serve como uma fila compacta de entrada para equipes de suporte, análise ou conteúdo. Consulte a descrição da API e as opções de acesso na página da TikTok Scraper API; confira os parâmetros exatos de busca no guia oficial de rotas.

Pessoas

Nenhuma pessoa listada para este artigo ainda.

Continue lendoComo identificar perguntas recorrentes sobre um produto no TikTok
Leia o próximo artigo

Transforme o que lê numa integração funcional

Explore as APIs de dados sociais da jsonscraper, teste pedidos e crie o seu próximo fluxo de trabalho.

Explorar APIs