Como Rastrear Tendências de Hashtags no Mastodon ao Longo do Tempo com a API

Você quer monitorar a frequência com que uma hashtag é usada no Mastodon ao longo de dias ou semanas. O Mastodon não oferece um gráfico de tendências integrado para hashtags na interface web. A API do Mastodon fornece os dados brutos necessários para construir seu próprio sistema de rastreamento. Este artigo explica como usar a API para coletar contagens de uso de hashtags e armazená-las para análise de tendências.

Entendendo a API do Mastodon para Rastreamento de Hashtags

O Mastodon expõe uma API RESTful que retorna dados JSON. Para rastreamento de hashtags, dois endpoints são relevantes. O endpoint /api/v1/trends/tags retorna uma lista de hashtags em tendência no momento com um array history que contém contagens de uso diário dos últimos 7 dias. Cada entrada do histórico inclui day (timestamp Unix), uses (número de postagens) e accounts (número de contas únicas).

O endpoint /api/v1/timelines/tag/:hashtag retorna postagens individuais para uma hashtag específica. Você pode paginar por elas para contar o total de postagens por dia. No entanto, o endpoint de tendências é mais eficiente para rastreamento de tendências, pois fornece contagens diárias pré-agregadas.

Para rastrear tendências por um período maior que 7 dias, você deve coletar capturas do endpoint de tendências em intervalos regulares, como uma vez por dia. Armazene os dados históricos retornados em um banco de dados ou arquivo CSV. Com o tempo, você acumulará um conjunto de dados que mostra como o uso da hashtag muda.

Pré-requisitos para Usar a API

Você precisa de uma conta no Mastodon em qualquer instância. Gere um token de acesso em Preferências > Desenvolvimento > Nova Aplicação. Defina o escopo como read:search e read:statuses para acesso à linha do tempo da hashtag. Para o endpoint de tendências, o escopo read:trends é necessário. Nenhum escopo de escrita é necessário, pois você está apenas lendo dados públicos.

Você também precisa de um ambiente de programação. Este guia usa Python 3 com a biblioteca requests. Instale-a com pip install requests. Você também precisará de uma forma de armazenar dados, como SQLite ou um arquivo de texto simples.

Passos para Coletar Dados de Tendências de Hashtags Usando a API

O método a seguir usa o endpoint /api/v1/trends/tags para obter contagens de uso diário de hashtags em tendência. Você escreverá um script Python que busca os dados, extrai o histórico da sua hashtag alvo e anexa a um arquivo CSV.

1. Crie um novo arquivo de script Python
   Abra um editor de texto e crie um arquivo chamado track_hashtag.py. Este script conterá toda a lógica para buscar e armazenar dados de tendências.
2. Defina a URL da sua instância e o token de acesso
   No topo do script, defina variáveis para sua instância do Mastodon e o token de acesso que você gerou. Exemplo: instance = 'https://mastodon.social' e token = 'seu_token_aqui'. Nunca compartilhe ou envie este token para um repositório público.
3. Defina o endpoint da API para tags em tendência
   Monte a URL completa: url = f'{instance}/api/v1/trends/tags'. Adicione o cabeçalho de autorização: headers = {'Authorization': f'Bearer {token}'}.
4. Envie uma requisição GET para o endpoint
   Use o método requests.get: response = requests.get(url, headers=headers). Verifique se response.status_code == 200 antes de processar os dados.
5. Analise a resposta JSON
   A resposta é uma lista de objetos de tag. Cada objeto tem um campo name e um campo history. Percorra a lista para encontrar sua hashtag alvo. Exemplo: for tag in response.json(): if tag['name'] == 'mastodon': data = tag.
6. Extraia o histórico diário da hashtag alvo
   O array history contém objetos com day, uses e accounts. Converta o timestamp Unix day para uma data legível usando datetime.datetime.fromtimestamp(int(day)). Armazene a contagem de uses de cada dia.
7. Anexe os dados a um arquivo CSV
   Abra um arquivo CSV no modo de anexação. Escreva uma linha de cabeçalho se o arquivo não existir. Cada linha deve conter a data, o nome da hashtag e a contagem de usos. Exemplo: 2025-03-20,mastodon,142. Feche o arquivo após escrever.
8. Agende o script para executar diariamente
   Use o agendador de tarefas do seu sistema operacional. No Windows, use o Agendador de Tarefas. No Linux ou macOS, use o cron. Configure o script para executar uma vez por dia no mesmo horário para capturar capturas diárias consistentes.

Depois de executar o script por vários dias, abra o arquivo CSV com um software de planilha. Você pode criar um gráfico com a coluna de data contra a coluna de usos para visualizar a linha de tendência.

Problemas Comuns ao Rastrear Tendências de Hashtags com a API

Hashtag Não Aparece no Endpoint de Tendências

O endpoint /api/v1/trends/tags retorna apenas hashtags que estão em tendência no momento na instância. Se sua hashtag tem baixo uso, ela pode não aparecer. Mude para o endpoint da linha do tempo /api/v1/timelines/tag/:hashtag e conte as postagens você mesmo. Pagine por todas as páginas usando o cabeçalho Link até chegar ao final. Some o número total de postagens retornadas. Este método é mais lento, mas funciona para qualquer hashtag.

Limites de Taxa Bloqueando Requisições Frequentes

As instâncias do Mastodon impõem limites de taxa, tipicamente 300 requisições a cada 5 minutos por IP ou token. Se você fizer muitas requisições, a API retorna HTTP 429. Verifique os cabeçalhos de resposta X-RateLimit-Remaining e X-RateLimit-Reset. Aguarde o tempo de redefinição antes de fazer outra requisição. No seu script, adicione um atraso time.sleep entre as requisições se você estiver paginando por muitas páginas.

Dados do Histórico Cobrem Apenas 7 Dias

O endpoint de tendências fornece histórico dos últimos 7 dias. Para rastrear períodos mais longos, você deve coletar dados diariamente e mesclá-los. Mantenha seu arquivo CSV e anexe novas linhas a cada dia. Ao analisar, remova entradas de data duplicadas para a mesma hashtag mantendo apenas a captura mais recente para cada dia.

Item	Endpoint de Tendências	Endpoint da Linha do Tempo
Caminho do endpoint	/api/v1/trends/tags	/api/v1/timelines/tag/:hashtag
Dados fornecidos	Contagens diárias pré-agregadas apenas para hashtags em tendência	Postagens individuais para qualquer hashtag, requer contagem manual
Duração do histórico	7 dias	Depende da paginação, até 40 postagens por página
Impacto no limite de taxa	1 requisição por verificação	Múltiplas requisições para paginar por todas as postagens
Melhor caso de uso	Rastrear hashtags populares com alto uso	Rastrear hashtags de baixo uso ou nicho

Agora você pode coletar dados de uso de hashtags do Mastodon usando a API e armazená-los para análise de tendências. Comece com o endpoint de tendências para hashtags populares e obtenha contagens diárias pré-agregadas. Para hashtags de nicho, use o endpoint da linha do tempo e pagine pelos resultados. Para visualizar tendências, importe seu CSV para uma ferramenta de gráficos ou planilha. Como passo avançado, configure o script para executar várias vezes ao dia e calcule a média das contagens para suavizar flutuações horárias.