Michael JohnsonA equipe de marketing percebe que estão surgindo vídeos sobre um novo produto no TikTok, mas é difícil verificar manualmente várias hashtags todos os dias. Para comparar publicações e indicadores visíveis ao longo do tempo, é necessário fazer uma coleta repetível, com registro de data e hora, arquivo das respostas originais e verificação de alterações.
Para esse protótipo, a TikTok Scraper API da jsonscraper é uma opção: a página do produto lista rotas para hashtags, usuários, vídeos e pesquisa. O primeiro passo é verificar a rota necessária e o formato da resposta no Postman e, em seguida, transferir a configuração confirmada para Python. Assim, é possível criar um processo repetível, extraindo apenas os campos que realmente aparecem na resposta.
O objetivo: acompanhar a evolução, não apenas um vídeo popular
Uma publicação com muitas visualizações pode chamar a atenção, mas, para planejar uma campanha, é mais útil entender quantos vídeos novos são encontrados sobre o tema e como os indicadores públicos das publicações já encontradas se alteram. Por exemplo, uma loja virtual de artigos esportivos precisa avaliar o fluxo de vídeos sobre um tipo específico de treino antes de preparar peças criativas relacionadas a ele.
A verificação manual dificulta as comparações: o conjunto de resultados muda, os indicadores se acumulam e os funcionários podem registrá-los em formatos diferentes. Se cada execução for salva com o horário da coleta e o JSON original, a equipe terá um histórico de suas próprias observações e poderá reprocessar os dados quando o esquema de análise mudar.
A automação consiste em várias etapas: verificar a rota e os parâmetros, solicitar dados segundo uma programação, salvar a resposta, confirmar sua estrutura e, em seguida, extrair os campos necessários. A tabela resultante pode ser usada para gráficos, classificação temática ou relatórios.
O que a documentação da API confirma
A página da TikTok Scraper API informa o endereço-base https://tiktok.evelode.com e lista as rotas da categoria Hashtag: GET /getHashtagInfo, GET /getHashtagFeed e GET /getHashtagFeedByID. A página também mostra um exemplo de solicitação a outra rota com o parâmetro license_key e descreve como configurar a chave na coleção do Postman.
Para GET /getHashtagFeed, a especificação oficial das rotas indica o parâmetro obrigatório query (URL da hashtag ou nome da tag), além dos parâmetros opcionais cursor, count, region e cache_timeout. Espera-se que a resposta do feed contenha a matriz tiktok.aweme_list; entre os campos listados para cada item estão aweme_id, desc, create_time, share_url, dados do autor e statistics. Alguns campos podem estar ausentes, portanto, verifique o JSON efetivamente recebido antes de processá-lo.
Na coleção da jsonscraper no Postman, é fácil executar uma solicitação de teste, conferir a resposta efetiva e obter um exemplo de teste para verificar o código posteriormente. Para autenticação, envie license_key; guarde a chave em uma variável de ambiente e não a inclua nos registros.
Primeiro, teste a solicitação no Postman
Comece com uma hashtag de teste. Na coleção, selecione a rota do feed de hashtags, defina license_key conforme indicado na documentação e informe o nome da tag em query. Se necessário, adicione count e o código do país em region. Execute a solicitação e verifique o status HTTP, o campo de nível superior status e o conteúdo de tiktok.aweme_list.
Salve a resposta bem-sucedida como um arquivo JSON de teste. Use-o para verificar se há um identificador da publicação, descrição, horário de publicação, link e estatísticas. Inclua um campo no esquema de análise somente depois de confirmar que ele é recebido no tipo esperado.
Guarde a chave da API em uma variável de ambiente, não no arquivo-fonte. Se a chave for enviada na URL, oculte-a ao registrar a solicitação para que o endereço completo não apareça nos logs.
Cliente Python para solicitar e arquivar
A rota e os nomes dos parâmetros abaixo correspondem à especificação publicada: para hashtags, usa-se query, e a autenticação é enviada por meio de license_key. O exemplo é compatível com Python 3.8+ e salva a resposta original junto com os metadados da execução.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("A API retornou um status diferente de ok")
return payload
def archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#exemplodetema"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"Arquivo salvo: {saved_path}")
Antes de executar, defina a variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. A solicitação usa o query confirmado e limita o número de itens solicitados por meio de count. A resposta é verificada quanto ao status HTTP e ao status no JSON; o arquivo preserva os dados efetivamente recebidos para processamento posterior. Teste a execução com uma hashtag antes de adicionar uma programação e análises.
Como adicionar normalização sem pressupostos frágeis
Na resposta do feed, a documentação indica a matriz tiktok.aweme_list. Antes da conversão, verifique se tiktok é um objeto e se aweme_list é uma lista. Para cada item, extraia apenas os campos confirmados, como aweme_id, desc, create_time, share_url e valores de statistics, quando estiverem presentes.
A tabela interna pode conter a hashtag da solicitação, o horário da coleta, o identificador do vídeo e as métricas selecionadas. Para um indicador opcional ou ausente, armazene um valor vazio: a ausência de uma métrica é diferente de um zero medido. Mantenha as respostas originais separadas para poder reconstruir a tabela sem fazer uma nova solicitação.
Se o formato da resposta mudar, a verificação de tipos deve interromper o processamento incorreto e gerar uma mensagem de diagnóstico. Guarde o JSON de teste junto com o teste do analisador: ele ajudará a verificar se a nova versão do código continua processando o esquema conhecido.
Métricas com base em observações repetidas
Se a resposta fornecer contadores, salve cada observação com um registro de data e hora. Para uma publicação, compare os valores em duas execuções e calcule a variação observada durante o intervalo. Para fazer a correspondência, use aweme_id, indicado na especificação, e verifique se ele está presente em cada item.
O número de publicações encontradas pela primeira vez em um dia pode ser calculado com base nos resultados das suas execuções. Essa métrica descreve o fluxo retornado por solicitações específicas, com determinados parâmetros e horários. Ela permite comparar as próprias observações, desde que o método de coleta permaneça consistente.
Um relatório básico pode mostrar o número de novas publicações encontradas por dia, a distribuição dos contadores disponíveis e a variação dos valores em vídeos encontrados novamente. Inclua o horário da solicitação e o nome do arquivo de origem para que o analista possa verificar a procedência de cada registro.
Programação e tratamento de erros
Quando a solicitação e a análise estiverem verificadas, execute o script segundo uma programação — por exemplo, com cron, GitHub Actions ou um orquestrador de dados. Mantenha a lista de hashtags em uma configuração separada para adicionar e remover temas sem alterar a lógica do cliente.
Para a execução automatizada, defina um tempo limite, um número limitado de novas tentativas para erros temporários de rede e o registro do status HTTP e da duração da solicitação. Não grave a chave nos logs. Em caso de erro de análise, salve informações de diagnóstico seguras e notifique a pessoa responsável.
A especificação oferece suporte à paginação pelo parâmetro cursor para o feed de hashtags. Se ela for necessária, salve o cursor da resposta e envie-o na solicitação seguinte sem transformá-lo; processe apenas os resultados retornados e monitore has_more, se estiver presente. Se as solicitações de várias hashtags retornarem a mesma publicação, escolha uma chave de deduplicação de acordo com o objetivo: contabilizar a publicação separadamente em cada hashtag ou contar apenas vídeos únicos.
Classificação e automação de relatórios
Depois de obter linhas verificadas, é possível acrescentar uma classificação das descrições dos vídeos segundo temas definidos: o campo desc está indicado no esquema do item. Um modelo pode agrupar publicações por formato — por exemplo, tutoriais, avaliações ou experiências de usuários. Salve o texto original, o rótulo, a versão das instruções e o resultado; encaminhe casos duvidosos para revisão humana.
Calcule os indicadores numéricos com código convencional para que execuções repetidas produzam resultados aritméticos reproduzíveis. Um classificador é útil para processar texto; o relatório final deve relacionar suas conclusões a linhas específicas e às datas das observações.
Em um fluxo sem código, as mesmas etapas podem ser conectadas em uma ferramenta de automação: programação, solicitação HTTP com a configuração verificada, validação da resposta, salvamento do JSON, transformação dos campos confirmados e notificação de erros. Primeiro, valide o contrato no Postman; depois, transfira-o para Python, n8n ou Make.
Resultado esperado e próximo passo
Após a configuração, a equipe terá um arquivo das respostas da API e uma tabela de observações para as hashtags selecionadas. Eles ajudarão a encontrar novas publicações, comparar indicadores disponíveis ao longo do tempo e selecionar materiais para uma análise mais aprofundada. Para obter resultados comparáveis, mantenha a mesma programação, os mesmos parâmetros de solicitação e as mesmas regras de normalização.
Comece com uma rota e uma resposta real: faça uma solicitação a /getHashtagFeed com o parâmetro query, salve o JSON e, em seguida, acrescente a análise dos campos e a programação. A página da TikTok Scraper API apresenta o endereço-base e o mapa de rotas, enquanto a especificação das rotas contém os nomes dos parâmetros para implementar o cliente.