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
- A consulta retorna uma página de resultados de busca para a palavra-chave especificada.
- O normalizador reúne registros de
aweme_listesearch_item_list[].aweme_info. - O script elimina duplicatas dentro da resposta com base no ID do vídeo.
- Os identificadores são comparados com o registro JSON local.
- Os novos IDs são acrescentados ao CSV e, em seguida, o conjunto completo de IDs encontrados é salvo para a próxima execução.


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 campostatusde 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émsearch_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.jsonjunto 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.