Michael JohnsonSe os clientes conversam sobre seu produto no TikTok, uma busca pelo nome da marca pode ajudar a equipe a reunir exemplos de perguntas recorrentes. O resultado prático é um CSV com a descrição do vídeo, o autor, o link e as métricas de engajamento disponíveis. Esse arquivo pode ser encaminhado à equipe de suporte ou usado como entrada para uma classificação temática.
Para o exemplo, vamos usar a pergunta “como usar a cafeteira Acme”. O script abaixo faz uma busca no TikTok, extrai cuidadosamente os vídeos de duas estruturas de resposta documentadas e salva os resultados encontrados. Depois, a equipe revisa as descrições manualmente, agrupa formulações semelhantes e as transforma em tópicos de FAQ ou sugestões para a página do produto.
Por que transformar a busca em uma tabela
Revisar manualmente os resultados da busca dificulta a conferência posterior: é preciso encontrar tudo de novo, e as anotações muitas vezes ficam no navegador ou em conversas. Uma tabela salva oferece uma lista de trabalho unificada: cada registro tem o ID do vídeo, o link, a descrição, o autor e as métricas disponíveis. A execução pode ser repetida em um cronograma, e o arquivo JSON permite verificar o que a API retornou naquela execução específica.
É importante entender os limites do método: a busca retorna resultados encontrados para a consulta, não um catálogo completo garantido de todas as menções. Portanto, a tabela serve para descobrir exemplos e observar perguntas recorrentes; para tirar conclusões sobre frequência, é melhor fazer execuções repetidas e uma revisão manual.
O que a busca retorna
Na documentação da TikTok Scraper API, a rota /searchVideo exige o parâmetro keyword. Entre os parâmetros compatíveis também estão count, cursor, date_posted, sort_by e region. Para este caso, basta definir a consulta e o número de resultados.
A resposta contém um status externo e um objeto tiktok. No esquema verificado, os vídeos podem estar em aweme_list ou nos itens de search_item_list, dentro do campo aweme_info. O código contempla os dois formatos e extrai apenas os campos que realmente estão presentes. Dependendo do resultado, podem estar disponíveis o ID do vídeo, a descrição, o link, o nome e o ID do autor, a data de publicação e as contagens de visualizações, curtidas, comentários e compartilhamentos.
Um coletor básico em Python
Instale a biblioteca de requisições e defina a chave na variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. O código é compatível com Python 3.8 ou superior. Ele salva a resposta original em JSON e os registros normalizados em CSV. A chave é enviada na requisição, mas não aparece na tela.
import csv
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme cafeteira"
response = requests.get(
"https://tiktok.evelode.com/searchVideo",
params={
"license_key": API_KEY,
"keyword": KEYWORD,
"count": 30,
"region": "US",
},
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("A API do TikTok retornou um status externo inesperado")
tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for result in tiktok.get("search_item_list") or []:
video = result.get("aweme_info")
if video:
items.append(video)
# Remove duplicatas, mantendo a ordem da primeira ocorrência.
unique = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
unique.setdefault(video_id, item)
stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
Path("data").mkdir(exist_ok=True)
Path(f"data/raw-{stamp}.json").write_text(
json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
)
columns = [
"video_id", "description", "share_url", "author", "author_id",
"created_at", "views", "likes", "comments", "collected_at"
]
with open("data/videos.csv", "w", newline="", encoding="utf-8") as file:
writer = csv.DictWriter(file, fieldnames=columns)
writer.writeheader()
for item in unique.values():
author = item.get("author") or {}
stats = item.get("statistics") or {}
created = item.get("create_time")
writer.writerow({
"video_id": item.get("aweme_id"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"author": author.get("nickname"),
"author_id": author.get("uid"),
"created_at": created,
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"collected_at": stamp,
})
print(f"Registros salvos: {len(unique)}")Instale a dependência com o comando python -m pip install requests. Se um campo estiver ausente em um registro, o código deixa a célula correspondente vazia. Isso é importante para as métricas: um valor vazio indica que o campo não foi retornado, sem substituí-lo por zero.
Como transformar o CSV em uma lista útil de perguntas
O primeiro passo é filtrar as descrições pelo conteúdo. Você pode buscar palavras como “como”, “por que”, “não funciona”, o nome do modelo e nomes específicos de peças. Esse filtro cria uma fila para revisão editorial, mas não determina, por si só, a intenção do autor: uma menção à marca pode ser uma avaliação, uma piada ou uma pergunta sobre compatibilidade.
Para agrupar os temas, forneça ao classificador apenas os campos de texto necessários: a descrição e, se fizer sentido para a tarefa, um identificador do registro sem dados pessoais. Peça que ele retorne categorias fixas, como “primeiro uso”, “limpeza”, “compatibilidade”, “defeito” e “compra”. Mantenha a descrição original junto da categoria para que um funcionário possa conferir a classificação e corrigir eventuais erros.
Um relatório de trabalho pode incluir o tema, o número de exemplos encontrados, links para alguns vídeos ilustrativos e uma coluna separada chamada “revisado por uma pessoa”. O número de exemplos no conjunto coletado descreve os resultados daquela consulta e daquele período de coleta; não corresponde à proporção de todos os clientes que enfrentam o problema.
Paginação e execução recorrente
Para obter a página seguinte de resultados, a documentação indica cursor como parâmetro de paginação: passe o valor do cursor da resposta anterior na próxima requisição. Trate-o como um token opaco e encerre a busca quando não houver mais resultados na resposta ou quando a API indicar que não há outra página. Em um piloto limitado, é razoável começar com uma única consulta, verificar os resultados e só então adicionar a paginação.
Para coletar dados regularmente, execute o script em um cronograma usando o agendador do sistema operacional ou o CI. Salve um arquivo JSON original separado para cada execução e inclua o horário da coleta na tabela. Com o histórico acumulado, remova duplicatas pelo ID do vídeo, mas mantenha snapshots separados se a tarefa incluir o acompanhamento de métricas variáveis. Só faz sentido comparar métricas quando há vários snapshots do mesmo registro.
Guarde a chave em um gerenciador de segredos do CI ou em uma variável de ambiente, restrinja o acesso ao arquivo de dados e defina um prazo interno de retenção. Antes de enviar o material para um sistema de classificação, verifique quais campos são realmente necessários. Isso reduz a cópia desnecessária de dados de usuários e simplifica o controle de acesso.
O que a equipe recebe
Ao final da execução, você terá um arquivo da resposta original e um CSV com os vídeos encontrados e os campos disponíveis. A equipe de suporte poderá verificar os links e reunir perguntas recorrentes; o marketing poderá identificar como o público descreve suas necessidades; e a pessoa responsável pela análise poderá repetir a coleta e comparar observações em datas diferentes.
Para começar, use uma consulta específica com o nome do produto e um problema concreto, revise manualmente de 20 a 30 registros encontrados e ajuste o vocabulário das categorias. Depois, você poderá acrescentar consultas por tema, um cronograma e a exportação para uma planilha ou banco de dados. Os recursos da rota e seus parâmetros estão descritos na página da TikTok Scraper API; confira a consulta escolhida antes de criar um monitoramento mais amplo.
