How to use the Hacker News API: endpoints, items and users

What the Hacker News API provides

The API exposes public Hacker News data. Stories, comments, jobs, Ask HNs and polls are all stored as items, and user profiles are available for users who have public activity on the site.

This repository is documentation and samples for the API, not a ready-made app or client. The README describes only reading public data, so the API offers no write access.

• Items: stories, comments, jobs, Ask HNs, polls and poll options
• Users: profiles with a case-sensitive id, creation time, karma, optional about text and a list of submissions
• Access through Firebase client libraries for Android, iOS, the web and servers

Understand the base URI and versioning

Every request starts with the v0 base URI: https://hacker-news.firebaseio.com/v0/. The README warns that future changes may not be backward compatible, which is why versioning is used.

Only removal of a non-optional field or a change to an existing field counts as an incompatible change. Clients should ignore fields they do not expect, so your code should not break when new fields appear. The README also states that there is currently no rate limit.

Fetch an item: stories, comments, jobs and polls

Items live under /v0/item/<id>.json, where the id is a unique integer. The examples in the README add ?print=pretty to the URL to make the JSON readable in a browser.

Key fields include id, type (one of job, story, comment, poll or pollopt), by for the author, time as Unix time, and text as HTML. Stories also carry title, url and score, while stories and polls include descendants for the total comment count. A comment has a parent, and kids lists the ids of its child comments in ranked display order.

Fetching a child means loading its id as a separate item, so reading a full thread takes multiple requests. The README notes that the total comment count is not returned directly for every item; you count it by traversing the tree.

• kids: ids of an item's comments, in ranked display order
• parent: either another comment or the relevant story
• descendants: total comment count for stories or polls
• parts: related pollopts for a poll, in display order

Fetch a user profile

User profiles live under /v0/user/. The id is the username and is case-sensitive, so jl and JL are not the same request. Only users with public activity, such as comments or story submissions, are available.

The profile includes created (Unix time), karma, an optional about field in HTML, and submitted, which lists the ids of the user's stories, polls and comments.

Use a Firebase client library instead of raw requests

The README recommends using a Firebase client library where you can. The libraries handle networking efficiently and can raise events when data changes, which suits a feed or reader that updates over time.

The repository's install method is listed as clone-based. The only install command given in the source is to clone the repository, so start there and then consult the linked Firebase setup guides for Android, iOS, the web or servers.

• Clone the repository to read the documentation and samples

Know the limits of the design

The README is frank that the v0 API is essentially a dump of internal data structures and is not the ideal public API. Some operations take extra work. For example, the newest page starts at the maximum item id and walks backward, keeping only top-level stories.

The README says it is still possible to implement most of Hacker News with the API. Plan for multi-step requests and for ignoring fields you do not recognize. For bugs, the README asks you to email api@ycombinator.com.