Michael JohnsonDepois de lançar uma campanha, pode ser útil para a equipe verificar quais vídeos públicos aparecem nos resultados de pesquisa para determinados termos. É difícil repetir uma pesquisa manual e compará-la alguns dias depois. Um pequeno coletor pode executar as mesmas consultas em intervalos regulares e arquivar as respostas com a data e a frase de pesquisa, para que um analista possa verificar os registros e preparar seu próprio resumo.
Este guia apresenta um pipeline de arquivamento em Python para guardar os resultados de pesquisa de frases fixas. Ao contrário do monitoramento de hashtags ou contas específicas, a chave para a comparação aqui é repetir as mesmas frases de pesquisa e guardar um instantâneo separado de cada resposta. A página da API TikTok Scraper da jsonscraper indica o endereço-base e a rota GET /searchVideo; na documentação dessa rota, a frase de pesquisa é fornecida no parâmetro obrigatório keyword.
Objetivo e limites da medição
Suponha que um profissional de marketing queira coletar diariamente resultados para algumas frases fixas: o nome de um produto, uma categoria e uma formulação do problema do cliente. Para cada consulta, o sistema guarda o horário da coleta e a resposta da API. Depois de verificar um exemplo de resposta, é possível normalizar os campos que realmente aparecem no JSON, como o identificador do vídeo ou contadores públicos, se estiverem presentes.
O arquivo responde a uma pergunta específica: quais registros a pesquisa retornou para a frase guardada durante esta execução? Se a resposta contiver métricas, observações repetidas podem mostrar a diferença entre valores registrados em momentos distintos. Essa diferença diz respeito aos instantâneos observados e ao intervalo entre eles; para fazer a comparação, guarde os dois horários de coleta e o mesmo campo.
Guarde a consulta junto com a resposta. A composição dos resultados corresponde a uma frase de pesquisa e a um momento de coleta específicos. Portanto, o arquivo é útil para acompanhar resultados de consultas selecionadas, não para oferecer uma visão completa de todo o conteúdo do TikTok. Os identificadores, as respostas originais e os registros de data e hora ajudam a verificar a origem de cada linha da tabela subsequente.
Verifique a rota e seus parâmetros
O mapa de rotas da API do TikTok informa o endereço-base https://tiktok.evelode.com e GET /searchVideo. A especificação atual da API identifica keyword como parâmetro obrigatório de pesquisa; entre os parâmetros opcionais estão cursor, count, cache_timeout, date_posted, sort_by e region. Para autenticação, envie license_key. As informações sobre a rota também estão disponíveis na documentação do SDK para Python.
Os parâmetros count e date_posted ajudam a definir o tamanho da resposta e o filtro temporal; sort_by aceita os valores documentados most-liked, relevance ou date-posted. Se usar paginação, envie o cursor recebido na resposta anterior como um valor opaco, sem calculá-lo por conta própria. Para manter um arquivo diário comparável, guarde os parâmetros da consulta e a versão do seu próprio código junto com os dados.
O exemplo abaixo usa um valor baixo de count para uma execução de teste e a região fixa US. Antes da coleta diária, teste uma consulta, seu status HTTP e a estrutura do JSON. O esquema da resposta pode conter vídeos encontrados em tiktok.aweme_list ou em tiktok.search_item_list, onde o objeto do vídeo fica em aweme_info; o código aceita as duas formas observadas.
Prepare o projeto
Crie um ambiente virtual e instale requests:
python -m venv .venv
source .venv/bin/activate
pip install requestsNo PowerShell, ative o ambiente com o comando .venv\Scripts\Activate.ps1. Defina a chave e a lista de frases de pesquisa por meio de variáveis de ambiente. Para a API do TikTok, use o nome de variável documentado JSONSCRAPER_TIKTOK_LICENSE_KEY:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="sua_chave"
export TIKTOK_QUERIES="nome do produto,categoria do produto,problema do cliente"Coleta e armazenamento de instantâneos
O exemplo envia uma consulta para cada frase à rota documentada e, em seguida, guarda o JSON original, o horário da coleta e os parâmetros utilizados. O nome do arquivo inclui a data e a frase de pesquisa. A chave fica no ambiente e não é incluída no arquivo.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("A API retornou um status diferente de ok")
return payload
def extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Resposta salva para a consulta: {query}")
time.sleep(1)
print(f"Respostas salvas: {len(QUERIES)}")Este coletor mínimo faz uma consulta por frase com count=10. Para uma coleta mais abrangente, adicione paginação com cursor: continue as consultas, enviando o valor do cursor recebido na resposta, enquanto a API indicar que há mais resultados, e guarde cada resposta separadamente. O cursor e o número de resultados definem uma execução específica; o JSON armazenado permite verificar depois exatamente o que foi retornado em cada consulta.
O exemplo verifica o status externo e, em seguida, lê o objeto tiktok. Ele reúne itens de aweme_list e também de search_item_list[].aweme_info, quando essa forma está presente. Os campos possíveis do registro de vídeo incluem identificador, descrição, autor, link e estatísticas; alguns campos podem estar ausentes. Por isso, guarde a resposta completa e, ao normalizar os dados, verifique se cada campo existe.
O intervalo de um segundo é uma pausa entre as consultas do próprio script, não uma afirmação sobre os limites do serviço. Configure a frequência e as tentativas novamente de acordo com as condições de acesso e a documentação. O parâmetro cache_timeout está documentado para a pesquisa; ele permite definir o período de cache em segundos, e o valor 0 desativa o cache conforme a especificação. Inclua-o na consulta quando esse comportamento for adequado ao seu caso.
Adicione a normalização com base na resposta real
Após a primeira execução, abra o arquivo salvo e examine a estrutura de payload. A função extract_videos do exemplo reúne itens de dois locais documentados para as formas de resposta da pesquisa. Identifique as chaves exatas dos campos necessários para a análise. Se um campo estiver ausente em determinado registro, mantenha-o como ausente, em vez de preencher um número presumido.
Para o processamento posterior, é conveniente criar uma linha para cada objeto encontrado, acrescentando collected_at e query. Os campos confirmados podem ser salvos em CSV ou em um banco de dados, enquanto o JSON original permanece no arquivo. Esse par permite criar tabelas práticas e, ao mesmo tempo, verificar a origem de cada registro.
Se a API retornar o identificador do vídeo, use-o para associar observações do mesmo vídeo em diferentes execuções. Guarde cada observação separadamente, sem sobrescrever as anteriores. Se não houver um identificador estável, verifique primeiro quais atributos permitem associar os registros e não considere garantida uma correspondência baseada no texto da descrição.
Compare os instantâneos e prepare um relatório
Depois de normalizar os dados, agrupe os registros por um identificador verificado e ordene-os pelo horário de coleta. Para campos de contagem, a diferença entre dois valores consecutivos pode ser calculada com código comum. Por exemplo, passar de 12 400 para 18 900 significa que o valor do contador mudou em 6 500 entre esses instantâneos. No relatório, indique as datas das observações e o campo original para que o leitor possa verificar o cálculo.
Uma estrutura útil para a tabela final inclui a frase de pesquisa, o identificador da publicação, o horário da coleta e os campos selecionados da resposta. O resumo pode ser agrupado por consulta e ordenado por um contador confirmado. Isso oferece à equipe uma lista verificável dos registros retornados para análise posterior; crie a tabela ou a mensagem como uma etapa separada, depois de examinar o esquema real.
Comece guardando os arquivos JSON localmente. Quando a coleta se tornar regular, transfira as linhas normalizadas para PostgreSQL ou um repositório analítico, e as respostas originais para um armazenamento de objetos, com a data e a consulta no nome. Guardar o original é especialmente útil ao ajustar o analisador: ele pode ser executado novamente sobre dados históricos sem uma nova chamada à API.
Agende a coleta
Para criar um arquivo diário, execute o script por meio do cron ou de outro agendador disponível no seu ambiente. Por exemplo, uma tarefa pode iniciar um arquivo Python uma vez por dia, fornecendo a chave e as frases de pesquisa por meio de variáveis de ambiente. Antes de usar o agendamento regularmente, teste uma consulta, depois a lista inteira e só então configure a execução programada.
Para uma execução confiável, registre o status de cada consulta, limite o número de novas tentativas em caso de erros temporários e sinalize uma coleta incompleta se alguma frase falhar. Não inclua a chave nas mensagens de erro. Também é útil separar os arquivos por data e nome da consulta para que uma nova execução não sobrescreva um instantâneo anterior.
Escolha a frequência de acordo com a tarefa e o volume de consultas. Para uma visão geral diária, basta uma execução por dia; coletas mais frequentes fazem sentido quando a equipe precisa acompanhar mudanças ao longo do dia. Comece com uma pequena lista de frases, verifique a utilidade dos resultados retornados e depois amplie a coleta dentro das condições de acesso e das regras de uso dos dados.
Use IA para agrupar temas
Depois de confirmar o esquema da resposta, é possível enviar campos de texto selecionados a um modelo para agrupar descrições em temas predefinidos ou preparar um breve rascunho de resumo. Junto com a classificação, guarde o identificador original da publicação, a frase de pesquisa e o trecho de texto que fundamentou a categoria. Assim, o analista poderá passar da conclusão do modelo ao registro original.
Calcule diferenças numéricas, ordenação e deduplicação com código comum. Um modelo é adequado para processar texto e redigir o relatório; os contadores e os registros de data e hora devem vir das respostas guardadas. Separar essas operações deixa clara a origem de cada conclusão.
Verifique manualmente uma parte das categorias automáticas e guarde as correções como exemplos de teste. Se diferentes tipos de publicação forem parar repetidamente no mesmo grupo, refine as definições das categorias e faça uma nova verificação. Esse processo ajuda a avaliar a qualidade da classificação com base nos dados da sua tarefa.
Conclusão: arquivo reproduzível e resumo verificável
Depois de executar a consulta documentada com o parâmetro keyword, a equipe passa a ter um arquivo que registra quais frases foram consultadas, quando isso ocorreu e quais dados a API retornou para cada uma. Com base nele, é possível criar uma tabela de resultados, comparar campos confirmados entre instantâneos e preparar uma lista das publicações encontradas para análise manual.
Comece com uma consulta de teste e, em seguida, configure a lista de frases e o agendamento. A descrição da API TikTok Scraper apresenta o endereço-base e o mapa de rotas; os parâmetros de /searchVideo e o formato da resposta estão descritos na especificação da API. Arquivar respostas verificadas cria uma base para análises reproduzíveis com frases de pesquisa fixas.