Michael JohnsonA equipe de vendas recebe a mesma pergunta por diferentes canais: que problemas os clientes em potencial já estão tentando resolver? A busca manual no TikTok gera uma série de vídeos, mas é difícil repeti-la uma semana depois, comparar os resultados e explicar por que determinado vídeo entrou no relatório. Para uma pesquisa pequena, é possível transformar os resultados públicos de algumas consultas precisas em um fluxo de dados reproduzível: salvar a resposta original, extrair os campos do vídeo e do autor, remover duplicatas e avaliar separadamente os sinais de intenção de comprar ou escolher um produto.
A seguir, apresentamos um fluxo funcional em Python com a TikTok Scraper API da jsonscraper. Ele pode ser útil, por exemplo, para um serviço de edição de vídeo que queira entender como os criadores descrevem dificuldades com legendas, modelos e exportação. O script reúne os resultados de busca retornados; depois, um analista verifica a classificação e decide quais formulações podem ser usadas na pesquisa de público. É uma forma de organizar a observação de conteúdo público, não de contabilizar automaticamente todos os usuários com intenção de comprar.
O problema: há consultas do público, mas é difícil repetir a pesquisa
Uma pesquisa manual facilmente perde o contexto. Uma pessoa procura “como adicionar legendas”, outra, “legendas automáticas para Reels”, e uma terceira salva apenas os vídeos de que gostou. A tabela final mistura consultas, datas, métricas e critérios de seleção diferentes. Quando a gerência pede para repetir a análise ou comparar duas semanas, é preciso reconstruir não só os resultados, mas também o próprio processo de busca.
É mais útil definir previamente a unidade de observação: um vídeo encontrado, com texto de descrição, identificador, link, autor e métricas públicas disponíveis. Para cada vídeo, salve a consulta de busca original e o horário da coleta. Assim, é possível responder separadamente a perguntas como: que formulações aparecem, que problemas são mencionados, quais vídeos receberam mais reações públicas e o que mudou entre as capturas salvas.
Como exemplo, vamos considerar uma empresa que desenvolve uma ferramenta para criar legendas e vídeos curtos. Ela quer encontrar vídeos públicos em que os criadores falem diretamente sobre transcrição manual, erros de reconhecimento de fala, temporização das legendas ou preparação de conteúdo para várias plataformas. Não se deve classificar o autor como “lead” ou “comprador” com base em um único vídeo: o pesquisador pode ordenar o conteúdo segundo sinais observáveis e, em seguida, verificar as conclusões manualmente.
Estrutura da solução: busca, registro, limpeza e avaliação
O pipeline tem quatro etapas. Primeiro, a equipe elabora um pequeno vocabulário de consultas de busca, cada uma relacionada a uma tarefa específica do público. Em seguida, o script consulta a busca de vídeos e salva a resposta JSON completa. Na terceira etapa, normaliza diferentes estruturas de resposta em uma linha uniforme por vídeo e elimina duplicatas pelo identificador. Por fim, regras ou um classificador de IA separado atribuem uma prioridade para revisão manual, preservando o motivo da avaliação.
Separar essas etapas é importante para a reprodutibilidade. A resposta bruta ajuda a investigar alterações nos campos ou erros de normalização. A tabela normalizada facilita a filtragem e a visualização. Uma tabela de avaliações separada permite alterar as regras sem repetir a chamada à API, desde que os dados salvos sejam adequados a esse novo processamento e estejam dentro do período de retenção da equipe.
Como consultas iniciais, podemos usar “erros nas legendas automáticas”, “como adicionar legendas rapidamente” e “edição de vídeos curtos para empresas”. São apenas exemplos: adapte as formulações ao idioma do público e ao produto. As consultas devem ser armazenadas junto com os resultados, pois termos diferentes produzem amostras diferentes.
O que a TikTok Scraper API oferece
Na documentação publicada pela jsonscraper, a busca de vídeos usa a rota GET /searchVideo no endereço-base https://tiktok.evelode.com. O parâmetro obrigatório é keyword; entre os parâmetros adicionais documentados estão count, cursor, region, date_posted, sort_by e cache_timeout. Por exemplo, sort_by aceita os valores documentados most-liked, relevance e date-posted, enquanto date_posted aceita valores como this-week ou all-time. A lista exata de parâmetros e a finalidade da rota estão no guia de endpoints da TikTok API.
A chave é transmitida como o parâmetro de consulta license_key. No exemplo a seguir, ela é lida da variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, para que o segredo não fique armazenado no código nem apareça nos logs. Use as condições de acesso atuais para autenticação e seleção dos parâmetros; a página da TikTok Scraper API traz uma descrição do produto e links para uma demonstração e para a documentação.
A resposta de busca deve ser analisada considerando sua estrutura, sem presumir que há apenas um único array. No exemplo da API verificado, a resposta continha um status no nível superior e um objeto tiktok; os vídeos podem estar em tiktok.aweme_list, e nos resultados de busca também aparece tiktok.search_item_list[].aweme_info. Verifique os dois formatos. Quando disponíveis, os objetos encontrados incluem identificador do vídeo, descrição, link, data de publicação, informações do autor e estatísticas como visualizações, curtidas, comentários e compartilhamentos. Considere métricas e campos como opcionais: o código não deve preencher com zeros inventados os valores ausentes.
A paginação da busca usa cursor. Se o script continuar a busca, deverá transmitir o valor recebido como um token opaco para a próxima solicitação, sem calculá-lo por conta própria. Para um protótipo inicial, faz sentido limitar a coleta a uma página por consulta: isso simplifica a verificação e torna a carga previsível. Depois, é possível acrescentar paginação com um limite de páginas e proteção contra cursores repetidos.
Preparação do ambiente
O exemplo usa Python 3.8 ou mais recente e a biblioteca padrão. Defina a chave no ambiente, por exemplo, no shell do macOS ou Linux:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="sua_chave"
python tiktok_demand.pyNo Windows PowerShell, é possível definir a variável assim:
$env:JSONSCRAPER_TIKTOK_LICENSE_KEY="sua_chave"
python .\tiktok_demand.pyO script faz uma solicitação separada para cada palavra-chave. Ele verifica erros HTTP, a resposta JSON e o status externo, depois extrai os objetos das duas variantes de array confirmadas. As respostas brutas são gravadas linha a linha em um arquivo JSONL: cada registro contém a consulta, o horário da observação e a resposta original. A segunda parte gera um CSV com campos uniformizados. A chave não está no código, e o conteúdo do segredo não é exibido.
Exemplo: coleta e normalização dos resultados de busca
import csv
import json
import os
import time
from datetime import datetime, timezone
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE_URL = "https://tiktok.evelode.com/searchVideo"
QUERIES = [
"erros nas legendas automáticas",
"como adicionar legendas rapidamente",
"edição de vídeos curtos para empresas",
]
def extract_videos(payload):
"""Aceita as duas estruturas observadas na resposta de busca."""
tiktok = payload.get("tiktok") or {}
videos = []
aweme_list = tiktok.get("aweme_list") or []
if isinstance(aweme_list, list):
videos.extend(item for item in aweme_list if isinstance(item, dict))
search_items = tiktok.get("search_item_list") or []
if isinstance(search_items, list):
for item in search_items:
if not isinstance(item, dict):
continue
video = item.get("aweme_info")
if isinstance(video, dict):
videos.append(video)
return videos
def fetch(query, license_key):
params = {
"keyword": query,
"count": 20,
"sort_by": "relevance",
"date_posted": "this-month",
"region": "US",
"license_key": license_key,
}
url = BASE_URL + "?" + urlencode(params)
request = Request(url, headers={"Accept": "application/json"})
try:
with urlopen(request, timeout=45) as response:
payload = json.loads(response.read().decode("utf-8"))
except HTTPError as exc:
raise RuntimeError("A API retornou o status HTTP {}".format(exc.code)) from exc
except (URLError, TimeoutError, json.JSONDecodeError) as exc:
raise RuntimeError("Não foi possível concluir ou analisar a solicitação à API") from exc
if payload.get("status") != "ok":
raise RuntimeError("O status da resposta da API não era ok")
return payload
def metric(statistics, key):
value = statistics.get(key)
return value if isinstance(value, (int, float)) else ""
def main():
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise SystemExit("Defina JSONSCRAPER_TIKTOK_LICENSE_KEY no ambiente")
raw_path = Path("tiktok_raw.jsonl")
csv_path = Path("tiktok_videos.csv")
seen_ids = set()
rows = []
with raw_path.open("a", encoding="utf-8") as raw_file:
for query in QUERIES:
observed_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query, license_key)
raw_file.write(json.dumps({
"query": query,
"observed_at": observed_at,
"response": payload,
}, ensure_ascii=False) + "\n")
for video in extract_videos(payload):
video_id = video.get("aweme_id")
if not video_id or video_id in seen_ids:
continue
seen_ids.add(video_id)
author = video.get("author") or {}
stats = video.get("statistics") or {}
rows.append({
"query": query,
"observed_at": observed_at,
"video_id": video_id,
"created_at": video.get("create_time", ""),
"description": video.get("desc", ""),
"share_url": video.get("share_url", ""),
"author_username": author.get("unique_id", ""),
"author_nickname": author.get("nickname", ""),
"views": metric(stats, "play_count"),
"likes": metric(stats, "digg_count"),
"comments": metric(stats, "comment_count"),
"shares": metric(stats, "share_count"),
})
time.sleep(1)
columns = [
"query", "observed_at", "video_id", "created_at", "description",
"share_url", "author_username", "author_nickname", "views",
"likes", "comments", "shares",
]
with csv_path.open("w", newline="", encoding="utf-8") as csv_file:
writer = csv.DictWriter(csv_file, fieldnames=columns)
writer.writeheader()
writer.writerows(rows)
print("Salvos {} vídeos únicos retornados em {}".format(len(rows), csv_path))
if __name__ == "__main__":
main()O valor de count representa aqui o tamanho da amostra solicitado para cada consulta. O script não presume que a API retornará exatamente essa quantidade: o número efetivo de linhas depende da resposta. A pausa entre as solicitações é uma medida simples para controlar o ritmo de execução, não uma afirmação sobre limites ou requisitos do serviço. Para uma rotina de produção, acrescente novas tentativas limitadas, monitoramento de erros e regras para a frequência de solicitações permitida, de acordo com as condições do seu plano.
Como ler a tabela resultante
No CSV, cada linha representa um vídeo único retornado, encontrado por uma das consultas. O campo query indica a origem do registro, observed_at mostra o horário da captura e video_id é usado como chave de deduplicação. A descrição e o link ajudam o analista a verificar o contexto, enquanto os contadores públicos permitem avaliar a reação no momento da coleta. Para comparações de longo prazo, use observações separadas: não sobrescreva o histórico das métricas se precisar acompanhar sua evolução.
Os contadores de visualizações, curtidas, comentários e compartilhamentos são capturas da estatística pública retornada pela API no momento da solicitação. Eles podem estar ausentes em alguns objetos; portanto, um valor vazio no CSV indica que a resposta não continha um campo numérico. Isso é diferente de zero e deve ser tratado separadamente no cálculo de agregados. Além disso, os resultados encontrados refletem a amostra da busca para palavras específicas, região, filtro temporal e parâmetros da solicitação. Eles descrevem os vídeos efetivamente retornados, não a totalidade do conteúdo ou do público da plataforma.
Para uma avaliação inicial de relevância potencial, é possível criar uma tabela transparente de regras: correspondências com formulações de problemas, menções a ferramentas utilizadas, perguntas sobre preço ou comparação e presença de um caso de uso concreto. É melhor armazenar os indicadores separadamente e explicar a avaliação do que registrar apenas uma pontuação opaca. Por exemplo, um vídeo com uma pergunta sobre a precisão da transcrição automática pode ser marcado como “verificar: discute qualidade”, enquanto um vídeo com dicas gerais de conteúdo pode receber a marca “baixa relevância temática”.
Conecte a IA sem transformá-la em juíza
Com uma amostra acumulada, um modelo pode ajudar a classificar descrições segundo um esquema predefinido: problema, ferramenta mencionada, tom da pergunta e presença de um sinal de escolha de produto. Envie ao modelo apenas os campos necessários — por exemplo, o texto da descrição e o identificador do registro — e peça um JSON fixo com rótulos e uma justificativa curta. Salve a versão da instrução, o modelo e o resultado junto à linha original, para que a classificação possa ser repetida ou verificada por uma pessoa em uma amostra.
Uma solicitação útil ao classificador deve limitar as conclusões aos sinais observáveis. Peça que determine se o texto contém um problema explícito com legendas, um pedido de recomendação de ferramenta ou uma discussão sobre o fluxo de trabalho. Se os dados forem insuficientes, inclua a categoria “contexto insuficiente”. O modelo não deve inferir a identidade do autor, sua intenção de compra ou características demográficas com base em um único vídeo público. O resultado é uma fila de temas para análise, não uma lista de pessoas para contato automático.
Para avaliar a qualidade da classificação, selecione uma subamostra aleatória e atribua manualmente as mesmas categorias. Compare a concordância para cada rótulo e examine os erros: por exemplo, o modelo pode interpretar sarcasmo como reclamação ou confundir uma dica educativa com uma experiência pessoal. Ajustar o vocabulário de busca e as instruções costuma ser mais útil do que complicar o modelo de imediato. No relatório, mantenha os textos originais e os links de acordo com a política de retenção e acesso adotada.
Automação programada e controle de qualidade
Depois de uma execução manual bem-sucedida, é possível agendar o script com cron, com o agendador de tarefas de uma plataforma em nuvem ou com um orquestrador como o n8n. A sequência prática de etapas permanece a mesma: ler a lista de consultas, chamar a API, verificar o status, salvar a resposta bruta, normalizar os vídeos, registrar novas capturas e gerar um relatório. Transmita a chave por meio do mecanismo de segredos do ambiente de execução, não em uma tabela, no texto do workflow ou em uma mensagem de erro.
Uma tarefa automatizada se beneficia de quatro verificações. A primeira é confirmar que a solicitação foi concluída com sucesso e que a resposta é JSON. A segunda é verificar se o status externo corresponde ao esperado. A terceira é confirmar que o processador entende as duas variantes da estrutura de busca e lida corretamente com campos ausentes. A quarta é registrar nos logs a quantidade de novos vídeos únicos e de erros. Se não houver resultados de repente, o relatório deve indicar uma amostra vazia como estado da execução, sem apresentá-la como um relatório de sucesso comum e sem explicação.
Acrescente a paginação depois de verificar a primeira página. A documentação da rota de busca indica o parâmetro cursor; salve o token recebido e transmita-o sem alterações na próxima solicitação. Limite o número máximo de páginas por termo de busca e interrompa o ciclo se não houver novos itens, se não houver próximo cursor ou se um cursor já processado aparecer novamente. Esse limite mantém sob controle o tempo de execução e o tamanho da coleta. A existência de um cursor permite solicitar a continuação dos resultados, mas não garante que eles sejam completos em relação a todas as publicações.
Uma nova execução no mesmo dia pode retornar vídeos repetidos. Por isso, a chave de deduplicação deve ser um identificador estável do vídeo, enquanto o histórico das capturas deve ser armazenado separadamente com a data da observação. Se for necessária uma visão consolidada, construa-a sobre as capturas: assim, será possível distinguir um vídeo encontrado pela primeira vez de outro que apareceu em várias consultas ou foi recebido novamente mais tarde.
Métricas: o que pode ser comparado corretamente
Para o monitoramento operacional, são úteis a quantidade de vídeos únicos encontrados por consulta, a proporção de vídeos com descrição preenchida, a distribuição das reações disponíveis e a frequência de certos temas. Ao comparar consultas, mantenha os parâmetros e o período de execução iguais. Se uma execução usar this-week e outra, this-month, a diferença no volume pode ser explicada pela janela temporal; portanto, não se deve interpretá-la como uma mudança de interesse sem análise adicional.
Comparar as métricas de um vídeo ao longo do tempo exige várias capturas e um esquema de armazenamento uniforme. Mantenha os valores originais de cada data exatamente como foram recebidos e, depois, calcule a diferença entre as observações. Não chame a diferença de aumento diário se os intervalos entre as execuções efetivas forem diferentes. Da mesma forma, ordenar vídeos por curtidas ajuda a encontrar os mais destacados na amostra coletada, mas não mede a eficácia comercial do criador ou do produto.
O relatório final para a equipe de marketing pode reunir três níveis: exemplos de formulações do público com links clicáveis, grupos temáticos de problemas e uma descrição quantitativa da amostra obtida. Cada conclusão deve vir acompanhada da quantidade de observações, das consultas e do período de coleta. Isso fornece contexto à gerência e permite ao analista repetir a filtragem nos mesmos dados originais.
Erros comuns e como evitá-los
Tratar um campo vazio como valor zero
Se não houver estatísticas ou informações do autor, o código acima deixa a célula vazia. Isso preserva a diferença entre um valor desconhecido e um zero medido. Na análise, defina explicitamente como lidar com valores ausentes e indique a quantidade de linhas excluídas de cada cálculo.
Presumir que a busca sempre retorna um único array
Na resposta de busca, podem aparecer aweme_list e elementos aninhados em search_item_list[].aweme_info. O processador verifica os dois formatos e ignora elementos de tipo inadequado. Se o esquema mudar, as respostas brutas salvas ajudarão a identificar rapidamente a nova localização dos dados, enquanto arquivos JSON de teste permitirão verificar a correção antes da próxima execução.
Contar o mesmo vídeo novamente como um sinal separado
Um mesmo vídeo pode corresponder a várias palavras de busca. No exemplo, ele entra uma única vez no CSV final, e o campo de consulta indica a primeira correspondência na ordem atual. Se for importante preservar todas as correspondências entre “vídeo” e “consulta”, armazene uma tabela de associação separada ou uma lista de consultas por identificador, em vez de apagar a origem do registro.
Comparar amostras que não são comparáveis
A palavra, a região, o filtro temporal, a ordenação e a data de execução afetam a amostra. Salve os parâmetros junto com a resposta e altere um fator por vez quando a pesquisa comparar alternativas. Isso ajuda a determinar se a mudança nos resultados está relacionada ao comportamento da busca ou à alteração das configurações do experimento.
Confundir correlação com intenção de compra
A descrição do vídeo e os contadores públicos dão sinais sobre o conteúdo e as reações do público. Por si só, eles não mostram quem está pronto para comprar, se alguém viu um anúncio ou qual é a conversão. Use-os para formular hipóteses, verificar temas e preparar conteúdo. Avalie o desempenho de vendas com os dados próprios das campanhas, alinhados a esta pesquisa em termos de período e público.
Como ampliar o pipeline
Quando a versão básica estiver funcionando de forma estável, é possível acrescentar um arquivo de configuração com a lista de consultas e os parâmetros de execução, para alterar o vocabulário sem editar o Python. O próximo passo é criar uma tabela de correspondência entre consultas e agrupamentos temáticos, como “qualidade do reconhecimento”, “velocidade de edição” e “exportação”. A equipe deve definir essas categorias e verificá-las com exemplos; a API retorna dados de busca, mas cabe ao pesquisador definir o esquema de interpretação.
Em vez de CSV, pode-se usar um banco de dados relacional: uma tabela de execuções, uma tabela de vídeos e uma tabela de capturas de métricas. Um índice único para o identificador do vídeo evita duplicatas no catálogo, enquanto as capturas permitem acompanhar a evolução dos contadores disponíveis. Armazene a data da observação em UTC e a versão do normalizador. Se a lógica de extração mudar, será possível reprocessar o arquivo JSONL arquivado e comparar os resultados.
No n8n, a coleta pode ser agendada, enquanto o código de normalização pode ser executado em um serviço Python separado ou em um nó, se o ambiente escolhido oferecer suporte às operações necessárias. Não é obrigatório incorporar um modelo na primeira etapa: primeiro, estabilize a coleta; depois, meça quanto tempo a classificação manual leva e quais categorias se repetem. A IA faz sentido quando reduz um trabalho repetitivo específico e seus rótulos podem ser verificados.
Se a questão de trabalho for acompanhar regularmente uma conta específica, em vez de buscar por formulações, o guia oficial traz uma rota separada, /getUserFeed, com os parâmetros query, max_cursor e count. Para uma hashtag, há a rota /getHashtagFeed, que usa o parâmetro cursor. São cenários de coleta distintos: a escolha do endpoint deve partir da pergunta da pesquisa, sem substituir um tipo de amostra por outro.
Resultado: uma amostra reproduzível em vez de uma coleção de favoritos
Após a execução, a equipe obtém dois artefatos úteis: um arquivo das respostas originais e uma tabela de vídeos únicos com termo de busca, data da observação, link, descrição e métricas disponíveis. Com base neles, é possível agrupar manualmente as perguntas do público, enviar os textos para uma classificação controlada, criar um resumo semanal e comparar capturas repetidas. O código trata explicitamente os erros de solicitação, verifica o status externo, diferencia duas variantes da estrutura de busca e mantém as métricas ausentes como valores em branco.
O resultado prático para a equipe é uma decisão mais transparente sobre quais problemas vale a pena investigar em entrevistas, páginas de destino ou mensagens publicitárias. Se a pesquisa exigir outro tipo de dado, altere as consultas ou use a rota documentada correspondente. Para verificar os parâmetros antes de adaptar o pipeline, consulte a documentação da TikTok API; informações sobre o produto e o acesso à demonstração estão na página da TikTok Scraper API.
Essa abordagem responde ao problema inicial: transformar a busca no TikTok em um processo de pesquisa reproduzível. O script coleta vídeos específicos retornados, preserva a origem e as capturas, e uma pessoa ou um classificador verificável transforma o conteúdo em hipóteses sobre a demanda. A equipe obtém uma base para a próxima decisão, mantendo a distinção entre sinais públicos de conteúdo e resultados de vendas confirmados.
