Como Usar a API de Hashtags do Mastodon para Consultar Tendências

Você quer recuperar hashtags em tendência de uma instância do Mastodon de forma programática, mas a interface web padrão mostra apenas algumas tags sem filtro ou automação. A API do Mastodon fornece um endpoint dedicado que retorna as hashtags em tendência atuais, junto com seu histórico de uso e metadados, permitindo criar painéis personalizados, ferramentas de monitoramento de conteúdo ou fluxos de postagem automatizados. Este artigo explica como autenticar, solicitar o endpoint de tags em tendência, analisar a resposta e lidar com erros comuns ao usar a API de hashtags do Mastodon para consultar tendências.

Entendendo o Endpoint da API de Hashtags em Tendência do Mastodon

A API do Mastodon expõe um endpoint dedicado em GET /api/v1/trends/tags que retorna um array de objetos de hashtag atualmente em tendência na instância. Cada objeto inclui o nome da tag, uma URL para sua timeline local e um array history com contagens de uso diário dos últimos sete dias. O endpoint é projetado para refletir o algoritmo de tendências local da instância, que considera fatores como o número de postagens usando a tag em uma janela de tempo recente, a taxa de novas postagens e a contagem total de postagens para aquela tag.

Para usar este endpoint, você precisa de um token de acesso válido com o escopo read:trends. Sem autenticação, algumas instâncias podem retornar um array vazio ou um erro 401 Não Autorizado. O token pode ser obtido registrando um aplicativo em sua instância do Mastodon e usando OAuth 2.0 para autorizá-lo. O formato da resposta é JSON, e cada objeto de tag segue esta estrutura:

{
  "name": "mastodon",
  "url": "https://mastodon.social/tags/mastodon",
  "history": [
    {
      "day": "2025-03-20",
      "uses": "1234",
      "accounts": "567"
    },
    {
      "day": "2025-03-19",
      "uses": "1100",
      "accounts": "520"
    }
  ]
}

O array history contém objetos para cada um dos últimos sete dias. O campo uses é o número total de postagens que usaram a tag naquele dia, e o campo accounts é o número de contas únicas que postaram com a tag. O campo day é uma string de data no formato AAAA-MM-DD. O endpoint retorna até 10 tags em tendência por padrão, mas este limite pode ser ajustado usando o parâmetro de consulta limit.

Passos para Realizar uma Consulta de Hashtag em Tendência via API do Mastodon

1. Registre um aplicativo Mastodon
   Vá em Preferências > Desenvolvimento > Novo Aplicativo na sua instância do Mastodon. Dê um nome ao seu aplicativo, por exemplo “Monitor de Hashtags em Tendência”. Em Escopos, habilite pelo menos read:trends. Clique em Enviar. Copie os valores de Client Key e Client Secret mostrados na próxima página.
2. Obtenha um token de acesso via OAuth
   Use as credenciais do cliente para solicitar um token de acesso. Envie uma requisição POST para https://suainstancia.com/oauth/token com os seguintes parâmetros: client_id, client_secret, grant_type=client_credentials e scope=read:trends. A resposta conterá uma string access_token. Salve este token com segurança.
3. Envie uma requisição GET para o endpoint de tendências
   Usando sua linguagem de programação preferida ou cliente de API, envie uma requisição GET para https://suainstancia.com/api/v1/trends/tags. Inclua um cabeçalho Authorization com o valor Bearer SEU_TOKEN_DE_ACESSO. Opcionalmente, adicione o parâmetro de consulta limit para controlar o número de tags retornadas, por exemplo ?limit=5.
4. Analise a resposta JSON
   O corpo da resposta é um array JSON. Itere sobre cada objeto para extrair os campos name e url. Para análise de tendências, processe o array history: some os uses de todos os dias para obter o uso total, ou compare o uso do dia mais recente com o do dia anterior para detectar tendências de alta ou queda.
5. Lide com limites de taxa e erros
   Verifique o código de status HTTP da resposta. Um status 200 indica sucesso. Um status 401 significa que seu token é inválido ou expirou. Um status 429 significa que você excedeu o limite de taxa da sua instância. Nesse caso, aguarde o tempo especificado no cabeçalho Retry-After antes de tentar novamente.

Armadilhas Comuns ao Usar a API de Tendências do Mastodon

Resposta vazia ou erro 401 Não Autorizado

Se você receber um array vazio ou um erro 401, verifique se seu token de acesso inclui o escopo read:trends. Algumas instâncias exigem autenticação mesmo para endpoints públicos. Confirme também que o token não expirou. Gere um novo token se necessário.

Tags em tendência diferem entre instâncias

Cada instância do Mastodon calcula tags em tendência de forma independente com base em suas próprias postagens locais. Tags em tendência em uma instância grande como mastodon.social podem não aparecer em uma instância menor. Para obter uma visão mais ampla, consulte várias instâncias e agregue os resultados.

Limitação de taxa causa falhas intermitentes

As instâncias do Mastodon impõem limites de taxa nas requisições à API. O limite padrão é 300 requisições a cada 5 minutos por endereço IP, mas isso pode variar. Para evitar atingir o limite, armazene em cache os dados de tendências localmente e atualize apenas a cada poucos minutos. Use o cabeçalho Retry-After para respeitar os períodos de espera.

Dados do histórico usam strings para números

Os campos uses e accounts no array history são strings, não inteiros. Ao realizar cálculos, converta-os para números usando parseInt ou Number() para evitar erros de concatenação de strings.

API do Mastodon vs Serviços de Tendências de Terceiros

Item	API do Mastodon (Integrada)	Serviços de Terceiros (ex.: Trendsmap)
Fonte de dados	Postagens locais de uma única instância do Mastodon	Agregado de várias instâncias ou plataformas
Autenticação	Requer token OAuth com escopo read:trends	Pode exigir chave de API ou assinatura paga
Granularidade do histórico	Uso diário dos últimos 7 dias	Geralmente fornece dados por hora ou em tempo real
Limites de taxa	Específico da instância, tipicamente 300 req/5 min	Varia por serviço, geralmente limites mais altos
Custo	Gratuito (recursos da instância)	Geralmente pago ou freemium

Agora você pode recuperar programaticamente hashtags em tendência de qualquer instância do Mastodon usando o endpoint /api/v1/trends/tags. Comece registrando um aplicativo e obtendo um token de acesso com o escopo read:trends. Para construir uma análise de tendências mais abrangente, considere consultar várias instâncias e agregar os dados do histórico para detectar padrões de tendências entre instâncias. Para uso avançado, combine o endpoint de tags em tendência com a API de busca para buscar postagens recentes de cada tag em tendência e analisar seu conteúdo.