Para estudar uma discussão sobre um problema no TikTok, primeiro encontre vídeos relevantes e, em seguida, peça os comentários de cada vídeo selecionado. Para uma equipa de produto, o resultado pode ser um conjunto de respostas JSON originais, associadas à pesquisa e ao link do vídeo. Antes de criar uma fila de temas, verifique a estrutura real dos comentários: a documentação confirma a rota e os respetivos parâmetros, mas não descreve os campos dos registos devolvidos.
Esta é uma etapa importante de um pipeline analítico. Os resultados da pesquisa ajudam a reunir contexto sobre o produto, e os comentários podem conter relatos de erros, perguntas ou soluções alternativas. Para garantir que a classificação se baseia em dados reais, guarde primeiro a resposta da API sem a transformar e, depois, compare os campos com o esquema efetivamente recebido.
Por que a pesquisa de vídeos não basta
O nome de uma aplicação ou dispositivo ajuda a encontrar vídeos, mas a descrição mostra sobretudo a perspetiva de quem publicou. Os espectadores podem discutir avarias concretas e formas de utilização nos comentários. Por isso, recolher comentários acrescenta um segundo nível de dados à amostra de pesquisa, associado ao vídeo original.
Materiais anteriores abordaram a monitorização da pesquisa no TikTok, a extração de perguntas das descrições e o processamento das respostas de pesquisa. Aqui, o objetivo é mais específico: recolher as respostas da rota de comentários e verificar a respetiva estrutura antes de desenvolver uma classificação. Isto pode ser útil para programadores de integrações analíticas, investigadores da experiência do utilizador e equipas de apoio.
Da frase de pesquisa a um conjunto de dados verificável
Defina algumas pesquisas específicas, por exemplo, o nome do produto combinado com o nome de uma funcionalidade ou modelo. Guarde a resposta da pesquisa e os URLs dos vídeos selecionados. Em seguida, peça os comentários usando os URLs e guarde cada resposta original num ficheiro separado. Depois de verificar o esquema, poderá normalizar os campos necessários, remover duplicados e agrupar os textos por tema.

- Pesquisa: peça vídeos com uma palavra-chave e verifique as duas estruturas de resultados suportadas.
- Seleção: escolha vídeos relevantes e guarde os respetivos identificadores e URLs.
- Recolha de comentários: envie o URL para a rota de comentários; para continuar a paginação, utilize o cursor devolvido.
- Verificação: guarde o JSON bruto e determine os nomes reais dos campos a partir da resposta.
- Análise: depois de verificar o esquema, agrupe os textos e peça a uma pessoa que reveja exemplos.
Que rotas utilizar
A documentação da TikTok Scraper API descreve GET \/searchVideo, que requer o parâmetro keyword. Os parâmetros opcionais incluem count, cursor, date_posted, sort_by e region. Para os comentários, existe GET \/getCommentsByUrl, que requer video_url; entre os parâmetros opcionais estão cursor, count e region. A chave é enviada no parâmetro license_key.
Na resposta da pesquisa, os vídeos podem encontrar-se em tiktok.aweme_list ou em tiktok.search_item_list[].aweme_info. O exemplo trata ambos os formatos, verifica o estado externo e guarda os objetos encontrados. Para a resposta dos comentários, não presume o nome de um array nem dos campos: guarda e apresenta o JSON recebido para que possa ser inspecionado.
Um coletor mínimo em Python
O código é compatível com Python 3.8 ou posterior. Instale requests e defina a chave na variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. O script grava as respostas de pesquisa e de comentários em ficheiros JSON separados, associando cada resposta de comentários à pesquisa e ao URL do vídeo. Os campos dos comentários não são extraídos até que verifique a estrutura real da resposta.

import json
import os
from pathlib import Path
import requests
BASE = "https:\/\/tiktok.evelode.com"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
OUT = Path("tiktok_raw")
OUT.mkdir(exist_ok=True)
def get_json(path, params):
response = requests.get(
BASE + path,
params={**params, "license_key": KEY},
timeout=30,
)
response.raise_for_status()
data = response.json()
if data.get("status") != "ok":
raise RuntimeError("API returned non-ok status")
return data
def videos_from_search(data):
tiktok = data.get("tiktok") or {}
found = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = (item or {}).get("aweme_info") or {}
if aweme:
found.append(aweme)
unique = {}
for video in found:
video_id = video.get("aweme_id")
video_url = video.get("share_url")
if video_id and video_url:
unique[video_id] = video
return list(unique.values())
for index, keyword in enumerate(("APP_NAME erro", "APP_NAME não funciona")):
search = get_json("\/searchVideo", {"keyword": keyword, "count": 10})
(OUT \/ f"search_{index}.json").write_text(
json.dumps(search, ensure_ascii=False, indent=2), encoding="utf-8"
)
for video in videos_from_search(search):
video_id = video["aweme_id"]
video_url = video["share_url"]
comments = get_json(
"\/getCommentsByUrl",
{"video_url": video_url, "count": 30},
)
filename = f"comments_{video_id}.json"
record = {
"keyword": keyword,
"video_id": video_id,
"video_url": video_url,
"response": comments,
}
(OUT \/ filename).write_text(
json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8"
)
print(json.dumps(record, ensure_ascii=False, indent=2))
O script verifica o estado externo da resposta e, em seguida, grava o objeto JSON completo. Assim, é possível inspecionar as chaves reais, os tipos de valores e a estrutura hierárquica antes de criar uma tabela de comentários. Se a API devolver um erro, o código interrompe a execução e informa-o, em vez de guardar silenciosamente um resultado inválido.
Do JSON bruto a uma fila de temas
Depois de verificar uma ou mais respostas, crie um normalizador com base no esquema efetivamente encontrado. Guarde o JSON original junto às linhas normalizadas para poder verificar a transformação e voltar a processar os dados se o código mudar. É útil manter no registo o link do vídeo, o registo original do comentário, a hora da recolha e a versão da regra de classificação aplicada.
Para classificar os temas, pode começar com etiquetas como «erro», «dúvida sobre utilização», «pedido de funcionalidade», «opinião» e «não relacionado com o produto». Regras baseadas em palavras-chave ou um classificador podem ajudar a ordenar a amostra; guarde a etiqueta atribuída separadamente do texto original. Antes de criar uma tarefa, um especialista deve verificar o contexto do comentário e o vídeo original.
Na deduplicação, utilize o campo de identificador apenas depois de confirmar que existe na resposta. Se os dados não incluírem um identificador, uma chave temporária pode combinar o URL do vídeo com o texto normalizado; este método agrupa formulações idênticas no mesmo vídeo, mas não permite concluir que os registos pertencem à mesma pessoa.
Automação e proveniência dos dados
Execute a recolha de forma agendada através de cron, GitHub Actions ou n8n. Guarde a chave nos segredos do ambiente de execução e não a inclua no repositório, nos ficheiros de resultados ou nos registos. Mantenha as respostas JSON originais disponíveis para verificação; defina um prazo de retenção e permissões de acesso de acordo com os requisitos da equipa e as regras aplicáveis da plataforma.
Para monitorizar o funcionamento do pipeline, registe o número de pesquisas concluídas com sucesso, vídeos únicos encontrados, respostas de comentários guardadas e erros da API. Estas métricas técnicas indicam em que etapa o resultado mudou. Uma resposta vazia, um erro no pedido e a ausência de correspondências após a classificação temática são estados diferentes, pelo que devem ser registados separadamente.
Para a base de dados, é útil separar as entidades de recolha, vídeos, respostas originais de comentários e decisões de classificação temática. A ligação à pesquisa e ao vídeo permite abrir a fonte para uma verificação manual. Depois de confirmar o esquema, pode acrescentar paginação por cursor: a rota aceita cursor, e o pedido seguinte deve enviar o valor devolvido pela API sem tentar interpretá-lo.
O que esta abordagem permite
A equipa obtém um processo de recolha reproduzível e um conjunto de fontes verificável a partir do qual pode criar uma fila de temas. O analista pode rastrear qual pesquisa levou a um vídeo e que resposta de comentários foi guardada. Depois de verificar a estrutura, o programador pode acrescentar a normalização e o agrupamento temático sem substituir um esquema desconhecido por suposições.
No relatório, indique as frases de pesquisa, a data de execução, os critérios de seleção e o número de respostas processadas. As conclusões dizem respeito às pesquisas específicas e aos dados devolvidos; ajudam a investigar as discussões encontradas e a planear a sua análise, preservando a respetiva proveniência e contexto.
Comece com um produto e algumas pesquisas de diagnóstico: guarde as respostas, verifique a estrutura dos comentários e, em seguida, acrescente ao normalizador apenas os campos confirmados. Os parâmetros das rotas estão descritos na documentação da API, e as informações sobre o produto encontram-se na página da TikTok Scraper API.