Michael JohnsonHTTP 200 não garante que o monitoramento diário do TikTok coletou vídeos. Os resultados da busca podem estar em aweme_list ou em search_item_list[].aweme_info; um script que lê apenas o primeiro array pode terminar sem erros e gravar um relatório vazio. Uma verificação confiável confirma separadamente o status de transporte e o status da aplicação, extrai as duas estruturas compatíveis e registra quantos vídeos únicos foram extraídos nesta execução.
O que vale a pena diagnosticar
Imagine a tarefa: todas as manhãs, a equipe coleta vídeos públicos para várias consultas, a fim de identificar novas publicações sobre um produto. Um resultado importante desse processo é uma lista reproduzível de registros encontrados, com descrição, autor, data de publicação e métricas disponíveis. Se o relatório ficar vazio de repente, a causa pode estar no processamento do JSON, em uma mudança no conjunto de resultados, na recuperação de vídeos já conhecidos ou em uma falha real da solicitação. Um único número — por exemplo, o tamanho de aweme_list — não ajuda a distinguir esses casos.
No TikTok Scraper API do jsonscraper, a rota de busca /searchVideo aceita o parâmetro obrigatório keyword e os parâmetros adicionais count, cursor, date_posted, sort_by e region. A documentação da rota descreve a paginação por meio de cursor; esse valor deve ser enviado como um dado opaco recebido na resposta anterior. O parâmetro count define o número desejado de resultados, não garante a cobertura completa das publicações.
Separe a verificação em quatro sinais
Um diagnóstico útil combina quatro verificações independentes. A primeira: a solicitação HTTP foi concluída com sucesso. A segunda: o status externo da resposta é igual a ok, e o tiktok.status_code interno corresponde a uma resposta bem-sucedida. A terceira: o objeto tiktok está presente e os registros são extraídos dos dois locais documentados na resposta. A quarta: após a deduplicação, restam registros com identificadores adequados para armazenamento. No log, registre a quantidade de itens extraídos antes e depois da deduplicação: a diferença mostra se houve repetições na etapa de normalização.
Campos ausentes devem permanecer vazios, em vez de serem preenchidos com valores inventados. Por exemplo, a contagem de visualizações pode estar ausente em um registro específico. Salvar o JSON original junto à linha normalizada ajuda a verificar posteriormente se a informação foi perdida durante a análise ou se não estava na resposta original.
Solicitação mínima e normalização em Python
A especificação do jsonscraper define o endereço-base https://tiktok.evelode.com e o envio da chave no parâmetro de solicitação license_key. O exemplo abaixo usa os parâmetros documentados; a chave é lida de uma variável de ambiente e não é exibida no log. Instale a dependência com o comando python -m pip install requests e, em seguida, defina JSONSCRAPER_TIKTOK_LICENSE_KEY no ambiente.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def extract_videos(payload):
"""Reunir vídeos das duas estruturas conhecidas da resposta de busca."""
tiktok = payload.get("tiktok") or {}
videos = []
for item in tiktok.get("aweme_list") or []:
if isinstance(item, dict):
videos.append(item)
for item in tiktok.get("search_item_list") or []:
if isinstance(item, dict):
aweme = item.get("aweme_info")
if isinstance(aweme, dict):
videos.append(aweme)
return videos
def main():
params = {
"license_key": KEY,
"keyword": "exemplo de consulta sobre um produto",
"count": 20,
"region": "US",
}
response = requests.get(BASE_URL, params=params, timeout=30)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("A API retornou um status externo diferente de ok")
tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
raise RuntimeError("O objeto tiktok está ausente na resposta")
if tiktok.get("status_code") != 0:
raise RuntimeError("O status_code interno não é igual ao valor de sucesso 0")
raw_videos = extract_videos(payload)
unique = {}
for video in raw_videos:
video_id = video.get("aweme_id")
if video_id:
unique.setdefault(str(video_id), video)
snapshot = {
"collected_at": datetime.now(timezone.utc).isoformat(),
"keyword": params["keyword"],
"status": payload.get("status"),
"status_code": tiktok.get("status_code"),
"raw_items": len(raw_videos),
"unique_items": len(unique),
"has_more": tiktok.get("has_more"),
"cursor": tiktok.get("cursor"),
"videos": list(unique.values()),
}
Path("snapshots").mkdir(exist_ok=True)
stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
Path(f"snapshots/{stamp}.json").write_text(
json.dumps(snapshot, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print({
"status": snapshot["status"],
"status_code": snapshot["status_code"],
"raw_items": snapshot["raw_items"],
"unique_items": snapshot["unique_items"],
"has_more": snapshot["has_more"],
})
if __name__ == "__main__":
main()O script verifica a camada de transporte por meio de raise_for_status() e, em seguida, verifica o status externo, a presença do objeto tiktok e o status_code interno. Depois, extrai registros das duas estruturas de busca, elimina duplicatas por aweme_id e salva um snapshot com o horário da coleta. Se não houver registros adequados, o arquivo ainda conterá informações sobre a execução, permitindo distinguir um resultado vazio salvo de um relatório ausente.
Como transformar snapshots em um sinal para a equipe
Execute o script em uma programação definida usando cron, CI ou um agendador de fluxo de trabalho. Armazene snapshots separados para cada consulta ou inclua a palavra-chave no nome do arquivo. Basta registrar na tabela de estado o horário da execução, o status, o número de registros extraídos e únicos, além do sinalizador has_more. É útil enviar um alerta quando uma solicitação gerar uma exceção, quando partes obrigatórias da resposta estiverem ausentes ou quando o número de registros extraídos mudar drasticamente em relação ao histórico próprio.
Essa comparação detecta uma anomalia no pipeline, mas, por si só, não explica sua causa. Um número menor de resultados pode refletir a composição atual dos resultados da busca, e não uma falha da API ou do parser. Por isso, é útil salvar o JSON original, comparar os mesmos parâmetros e verificar os identificadores encontrados. Escolha o limite de alerta com base nas observações da sua própria consulta, não em um número universal.
Para paginar, use o cursor da resposta e interrompa a busca quando a API informar que não há mais resultados. Salve os cursores usados e os parâmetros da solicitação para que a execução possa ser reproduzida. Os parâmetros date_posted e sort_by permitem definir um filtro temporal e uma ordenação; se a tarefa exigir comparações reproduzíveis, mantenha-os fixos entre as execuções.
Como interpretar o resultado
Depois da implementação, a equipe terá respostas verificáveis para três perguntas práticas: a solicitação foi concluída, onde estão os resultados no JSON e quantos vídeos únicos foram incluídos no snapshot salvo. Isso encurta o caminho entre uma tabela vazia e o diagnóstico: primeiro, verificam-se os status e a estrutura; depois, os parâmetros, as duplicatas e o conteúdo da resposta original.
O esquema da resposta e os campos disponíveis podem variar entre registros. Em uma verificação ao vivo do jsonscraper em 25 de outubro de 2026, a busca retornou campos de identificador, descrição, autor e estatísticas; os valores de um registro específico devem ser considerados opcionais. Um relatório funcional armazena os dados efetivamente recebidos e não substitui campos ausentes por zeros.
É possível começar pela página do TikTok Scraper API e conferir as rotas e os parâmetros exatos na documentação oficial da API. Essa verificação é útil antes de iniciar o monitoramento: o relatório passa a ser um resultado observável cuja qualidade pode ser diagnosticada.
