JSON ao vivo e sem chave: como usar a API do Hacker News

Como se usa a API do Hacker News?

Toda dúvida sobre como usar a API do Hacker News leva a um de dois hosts gratuitos: hacker-news.firebaseio.com/v0/ serve itens ao vivo, perfis de usuário e listas ranqueadas de histórias, e hn.algolia.com/api/v1/ serve a busca de texto completo. Os dois devolvem JSON puro via HTTPS, os dois aceitam requisições anônimas, e nenhum emite chaves de API ou aceita um token. Use o Firebase quando você já conhece o id de um item ou quer a página inicial atual, e use o Algolia quando você tem uma palavra-chave e nenhum id.

O que a API do Firebase devolve para um item?

A API do Firebase devolve um objeto JSON plano por item a partir de /v0/item/<id>.json, e id é o único campo que todo item carrega. O README de HackerNews/API lista deleted, type, by, time, text, dead, parent, poll, kids, url, score, title, parts e descendants como campos opcionais, com type assumindo um dos valores "job", "story", "comment", "poll" ou "pollopt". Escreva seu parser contra id mais o que mais você encontrar, porque um comentário carrega parent e text onde uma história carrega url, score e descendants.

curl "https://hacker-news.firebaseio.com/v0/item/8863.json?print=pretty"

{
  "by": "dhouston",
  "descendants": 71,
  "id": 8863,
  "kids": [9224, 8917, 8884, 8887],
  "score": 104,
  "time": 1175714200,
  "title": "My YC app: Dropbox - Throw away your USB drive",
  "type": "story",
  "url": "http://www.getdropbox.com/u/2/screencast.html"
}

Essa é a resposta ao vivo para o item 8863 com o array kids cortado para quatro ids; o real tem 33. time é um timestamp Unix em segundos, descendants conta a árvore inteira de comentários, e kids guarda só as respostas diretas, então percorrer um thread completo significa descer de forma recursiva por kids, uma requisição de cada vez.

Quais endpoints a API do Hacker News oferece?

A API do Firebase expõe dez caminhos, todos GET, todos terminando em .json. Cada caminho de lista devolve um array de ids de itens e não os itens em si, então ler uma lista custa uma requisição mais uma requisição por id que você resolver depois.

Os tamanhos documentados são tetos, não comprimentos fixos. Consultado em 10 de setembro de 2026, /v0/topstories.json devolveu os 500 ids completos enquanto /v0/askstories.json devolveu 28, e /v0/maxitem.json devolveu 49.649.544. Os ids são sequenciais a partir do item 1, uma história intitulada "Y Combinator" publicada pelo usuário pg com um time de 1160418111, então um crawler consegue percorrer todo o corpus contando para cima. Esse id sequencial também é o que torna as estatísticas do Hacker News que você pode tirar dos mesmos endpoints verificáveis em vez de ficarem de segunda mão.

Como buscar no Hacker News com a API do Algolia?

A busca roda em um host separado com dois caminhos: /api/v1/search ordena por relevância, depois por pontos, depois por número de comentários, e /api/v1/search_by_date ordena os mais novos primeiro. Os dois aceitam query para texto completo, tags para filtros de tipo, numericFilters para condições sobre created_at_i, points e num_comments, além de page e hitsPerPage para paginação. Filtre com tags antes de filtrar no seu próprio código, porque os valores válidos cobrem story, comment, poll, pollopt, show_hn, ask_hn, front_page, author_:USERNAME e story_:ID.

curl "https://hn.algolia.com/api/v1/search?query=postgres&tags=story&hitsPerPage=1"
curl "https://hn.algolia.com/api/v1/search_by_date?tags=story&numericFilters=created_at_i>1788998400"
curl "https://hn.algolia.com/api/v1/search?tags=comment,story_18717168"
curl "https://hn.algolia.com/api/v1/search?tags=front_page"

{
  "hits": [
    {
      "objectID": "18717168",
      "title": "Bye Bye Mongo, Hello Postgres",
      "url": "https://www.theguardian.com/info/2018/nov/30/bye-bye-mongo-hello-postgres",
      "author": "philliphaydon",
      "points": 1562,
      "num_comments": 417,
      "created_at": "2018-12-19T17:08:53Z",
      "created_at_i": 1545239333,
      "story_id": 18717168,
      "_tags": ["story", "author_philliphaydon", "story_18717168"]
    }
  ],
  "nbHits": 14776,
  "page": 0,
  "nbPages": 1000,
  "hitsPerPage": 1,
  "processingTimeMS": 13
}

As tags são combinadas com AND por padrão e com OR dentro de parênteses, então author_pg,(story,poll) se lê como autor pg AND (story OR poll). Essa é toda a linguagem de consulta, e ela é mais estreita que os operadores de busca booleanos que você escreveria para um buscador, então a cobertura de palavras-chave tem que vir de várias consultas em vez de uma única engenhosa. hitsPerPage vale 20 por padrão.

Quais são os limites de uso da API do Hacker News?

As duas APIs publicam respostas diferentes sobre seus rate limits (limites de requisições por período). O README de HackerNews/API diz "There is currently no rate limit" para os endpoints do Firebase, e a documentação de hn.algolia.com/api diz que o Algolia limita um único IP a 10.000 requisições por hora e bloqueia os endereços que passam disso. Nenhum número publicado cobre o lado do Firebase, então trate essa folga como cortesia e não como garantia, e mantenha um polling razoável nos dois casos.

Faça o orçamento do lado do Algolia antes de escrever o loop:

requisições por hora = (3600 / intervalo de polling em segundos) x número de consultas salvas

Trinta consultas salvas com um intervalo de 60 segundos dão 3600 / 60 = 60 verificações por consulta por hora, e 60 x 30 = 1.800 requisições por hora, que são 18 por cento da cota de 10.000. Some uma atualização da página inicial no lado do Firebase e o custo é de 1 requisição para /v0/topstories.json mais 500 requisições de itens, ou 501 requisições por rodada. Quem já fez orçamento em torno dos rate limits da API do Reddit vai achar os dois números generosos em comparação.

O que a API do Hacker News não consegue fazer?

As duas APIs são somente leitura, então nenhum endpoint publica uma história, vota ou responde a um comentário, e nenhum caminho aceita credenciais que permitiriam isso. O Algolia também limita a paginação: nbPages multiplicado por hitsPerPage voltou como exatamente 1.000 em todo tamanho de página testado em 10 de setembro de 2026, e pedir a página 60 com 20 resultados por página devolveu um array hits vazio, o que significa que uma consulta chega a 1.000 resultados e não passa disso. Divida uma busca ampla em intervalos de datas com numericFilters sobre created_at_i quando você precisar de tudo o que fica atrás desse muro.

Nenhuma das duas APIs avisa você. Não há webhook, nem email, nem monitoramento de palavras-chave, nem deduplicação entre menções repetidas, nem julgamento sobre qual thread merece uma resposta. Essa lacuna é o trabalho que o RedReplier faz: ele recebe um site e um conjunto de palavras-chave, monitora o Hacker News junto com Reddit, X, Bluesky e Facebook em um só lugar, classifica cada menção pela intenção de compra, explica com IA por que ela foi sinalizada e envia um email para você no intervalo do seu plano. O mesmo produto também oferece acesso por API e um servidor MCP que funciona com Claude Code, Cursor e qualquer cliente MCP padrão, e essa é a diferença entre a coleta de dados de redes sociais bruta e uma fila de conversas que valem uma resposta.

Perguntas frequentes

A API do Hacker News precisa de uma chave de API?

Não. Nem hacker-news.firebaseio.com/v0/ nem hn.algolia.com/api/v1/ emitem chaves, e nenhum dos dois aceita um token. Um GET simples sem autenticação devolve JSON dos dois hosts, e por isso um único comando curl basta para testar qualquer endpoint desta página.

Existe um rate limit oficial da API do Hacker News?

O Algolia publica um e o Firebase não. A documentação de hn.algolia.com/api limita um único IP a 10.000 requisições por hora, e o README de HackerNews/API diz "There is currently no rate limit" para os endpoints do Firebase. Não existe número documentado para o Firebase, então quem cita um valor específico de requisições por segundo para ele está chutando.

Como pego todos os comentários de uma história do Hacker News?

Dois caminhos funcionam. No Firebase, leia o array kids da história e desça de forma recursiva em cada item filho, o que custa uma requisição por comentário. No Algolia, uma requisição para /api/v1/search?tags=comment,story_<ID> devolve os comentários como resultados de busca, sujeita ao teto de paginação de 1.000 resultados.

Qual é a diferença entre a API do Firebase e a API do Algolia?

O Firebase é o registro ao vivo e o Algolia é o índice sobre ele. O Firebase responde a "me dê o item 8863" e "o que está na página inicial agora" com campos como score, kids e descendants. O Algolia responde a "quais histórias mencionam postgres" com campos como points, num_comments e created_at_i, e é o único dos dois que faz busca de texto completo.

Posso publicar ou votar no Hacker News pela API?

Não. As duas APIs são somente leitura, e nenhuma documenta um caminho de escrita para enviar histórias, publicar comentários ou votar. Qualquer coisa que publique no Hacker News em seu nome está operando o site, não a API.

Até quando vão os dados da API do Hacker News?

Até o primeiro item do site. O item de id 1 é uma história intitulada "Y Combinator" publicada pelo usuário pg, com um time Unix de 1160418111, o que a coloca em outubro de 2006. A partir daí os ids seguem de forma sequencial até o valor que /v0/maxitem.json informa hoje.

Como pego a página inicial atual do Hacker News com a API?

O endpoint do Firebase /v0/topstories.json devolve até 500 ids ordenados da página inicial, e cada id precisa depois de uma requisição separada a /v0/item/<id>.json para resolver título, pontuação e url. O Algolia oferece um atalho para a mesma lista: /api/v1/search?tags=front_page devolve a página inicial como resultados de busca em uma única requisição. O Firebase serve quando se precisa do ranking ao vivo com todos os campos, e o Algolia quando uma chamada basta.

Dá para filtrar os resultados de busca do Hacker News por pontuação ou número de comentários?

A API do Algolia aceita numericFilters para condições sobre points e num_comments, além de created_at_i para intervalos de data. Uma consulta como numericFilters=points>500 restringe /api/v1/search a histórias acima dessa pontuação, e os filtros se combinam com vírgula. O Firebase carrega os mesmos campos score e descendants em cada item, mas não tem parâmetro de filtro, então filtrar por lá significa buscar os itens e checar os campos por conta própria.

Como acompanho as publicações novas do Hacker News assim que elas saem?

Consultar /v0/newstories.json no Firebase devolve os ids mais recentes, até 500 de cada vez, e comparar cada consulta com a anterior revela os ids novos. Juntando isso com /v0/maxitem.json, que dá o teto atual de todo o acervo, um salto nesse número aponta itens novos antes mesmo de listá-los. O README diz "There is currently no rate limit", o que significa que consultar esse endpoint com frequência não tem custo documentado, mas a conta de orçamento do Algolia deste artigo continua valendo quando se misturam buscas.

Dá para ver tudo o que um usuário específico do Hacker News já publicou?

/v0/user/<id>.json no Firebase devolve um perfil com o campo submitted, um array com todos os ids de itens que aquele usuário publicou, comentários incluídos. Cada id se resolve com /v0/item/<id>.json para obter título, texto e pontuação, o mesmo padrão de uma requisição por id usado para percorrer uma árvore de comentários. A tag author_:USERNAME do Algolia também filtra resultados por autor, mais rápido quando só interessam histórias e não o histórico completo.