Como não perder resultados de busca do TikTok ao analisar JSON

Ao buscar vídeos no TikTok por meio de uma API, eles podem não estar no array que o processador espera encontrar primeiro. Em uma resposta verificada do jsonscraper à solicitação `\/searchVideo`, o campo `aweme_list` estava vazio, e os elementos com dados dos vídeos apareciam em `search_item_list[].aweme_info`. Se o código ler apenas `aweme_list`, salvará zero vídeos, embora a resposta contenha resultados. Para quem desenvolve, isso representa um desafio concreto de confiabilidade: extrair as duas formas de dados e normalizá-las em uma única lista antes de gravá-las no banco de dados ou enviá-las para um relatório.

Você pode conferir um exemplo real e a descrição do endpoint na especificação da API jsonscraper e na documentação do endpoint do TikTok. O registro do esquema na especificação é datado de 25 de outubro de 2026; ele demonstra a estrutura de uma resposta específica, mas não garante que todos os campos estarão presentes em todas as solicitações futuras.

Por que o analisador pode retornar uma lista vazia

O endpoint `GET https://tiktok.evelode.com/searchVideo` busca vídeos com base no parâmetro obrigatório `keyword`. A documentação também lista `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` e `region`. No esquema da resposta observada, o objeto externo contém `status` e o objeto aninhado `tiktok`; dentro dele estão `cursor`, `has_more`, `status_code`, `aweme_list` e `search_item_list`.

Na observação específica de uma solicitação com uma palavra-chave e `count=3`, o array `aweme_list` estava vazio. Ao mesmo tempo, `search_item_list` incluía itens com informações dos vídeos em `aweme_info`. Esses objetos podiam conter IDs de vídeo, legendas, URLs de publicação, dados do autor e estatísticas, como número de visualizações, curtidas ou comentários. Os campos descritos refletem o esquema observado; ainda assim, o processador deve aceitar valores ausentes.

A conclusão prática é que uma solicitação HTTP bem-sucedida e um array não vazio em um campo esperado são verificações diferentes. Primeiro, confira o status externo e a presença de `tiktok`; em seguida, reúna os vídeos de todos os locais documentados. Para análise, salve o ID e a resposta original: assim será possível rastrear como um registro específico foi extraído e normalizado.

Normalize a resposta antes de gravá-la no armazenamento

Uma fronteira conveniente entre a API e seu sistema é uma função que recebe o objeto `tiktok` aninhado e retorna itens uniformizados. Ela deve processar os dois arrays, ignorar elementos que não sejam dicionários ou que estejam vazios e eliminar vídeos repetidos com base em `aweme_id`. Mantenha os contadores vazios quando o provedor não os retornar: zero indicaria um valor medido, enquanto `None` sinaliza que o campo está ausente.

Abaixo está um exemplo mínimo para Python 3.8 ou superior. Ele faz uma solicitação, verifica o status de transporte e o status do nível superior, normaliza as duas variantes do resultado e imprime os campos selecionados. A chave é lida de uma variável de ambiente e não é exibida nos registros.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if isinstance(item, dict):
                candidates.append(item.get("aweme_info"))

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

Instale a dependência com o comando python -m pip install requests, defina `JSONSCRAPER_TIKTOK_LICENSE_KEY` no ambiente de execução e salve o arquivo, por exemplo, como `search_videos.py`. Os parâmetros da solicitação correspondem aos nomes documentados: `keyword`, `count` e `region`; `license_key` é enviado como parâmetro da query. O código pressupõe que a resposta contenha `status: "ok"`, como no exemplo registrado. Se a API retornar outro status, o processamento será interrompido antes que uma estrutura duvidosa siga adiante.

Como transformar o exemplo em uma coleta recorrente

Para uma exportação pontual, basta gravar os itens normalizados em JSON Lines ou em uma tabela. Em um processo contínuo, salve também a resposta original, junto com o horário de recebimento e a consulta de busca. Uma tabela separada para os vídeos normalizados pode usar `aweme_id` como chave: um resultado repetido atualiza o registro, e o mesmo ID presente nos dois arrays não cria uma duplicata.

Para solicitar a página seguinte, a documentação indica o parâmetro `cursor`: envie o valor recebido na resposta anterior. Trate-o como um token opaco — armazene-o e devolva-o sem alterações. O loop de paginação deve terminar quando não houver continuação indicada por `has_more` ou quando a API não fornecer um cursor válido; limite o número de páginas por execução para que uma lógica incorreta não crie um loop infinito. As fontes registradas confirmam o nome do parâmetro e a presença dos campos `cursor` e `has_more` no esquema observado, mas não garantem que os resultados sejam completos.

Para monitorar várias frases de busca, armazene cada frase junto com o ID do vídeo e o horário da coleta. Assim, você poderá criar recortes por consulta, comparar os resultados entre execuções e enviar novos IDs para uma fila de classificação posterior. Esse sistema descreve os resultados obtidos; o conjunto de dados depende da consulta, da região, do horário e dos elementos efetivamente retornados pela API.

Verifique a qualidade dos dados, não apenas o sucesso da solicitação

Após a normalização, é útil acompanhar indicadores técnicos simples do pipeline: número de registros de cada array, número de IDs exclusivos, proporção de elementos sem ID e proporção de elementos sem estatísticas. Essas métricas descrevem o processamento de uma resposta específica, não a popularidade dos vídeos. Por exemplo, um aumento no número de elementos sem `play_count` indica que a análise deve preservar o valor desconhecido e sinalizar a ausência do campo, em vez de substituí-lo por zero.

Não vincule os cálculos posteriores à expectativa de que todos os vídeos tenham o mesmo conjunto de estatísticas. Para armazenar os dados brutos, mantenha o JSON completo; para a tabela analítica, selecione apenas os campos necessários e permita `NULL`. Se o formato da resposta mudar, o arquivo original permitirá executar novamente o normalizador sem fazer outra solicitação.

Transmita a chave da API por meio dos segredos do CI ou das variáveis de ambiente do orquestrador. Não a inclua em URLs gravadas nos registros, não imprima o objeto com os parâmetros da solicitação e não salve o valor da chave junto com as respostas originais. Se o processo for agendado, inclua um limite de tempo para as solicitações, tratamento de erros HTTP e novas tentativas com intervalos; armazene o cursor somente junto da consulta de busca correspondente, para não misturar páginas de resultados diferentes.

Resultado: uma tabela unificada em vez de vídeos perdidos

Após a normalização, o código posterior recebe uma única lista de vídeos, independentemente de o elemento ter vindo de `aweme_list` ou de `search_item_list[].aweme_info`. O ID permite eliminar repetições, e os campos opcionais permanecem explicitamente vazios. Isso reduz o risco de relatórios vazios causados pela leitura de apenas um array e torna a etapa seguinte — exportação, filtragem ou classificação — mais previsível.

Você pode começar a verificação pela página da TikTok Scraper API, que apresenta o endpoint base da API e dá acesso à demonstração. Para a integração, use a documentação oficial e teste primeiro o processamento com um número pequeno de elementos; se necessário, aumente `count` e continue os resultados com o cursor documentado. O resultado será uma camada de dados organizada para suas tarefas, não uma suposição de cobertura completa do TikTok.