Hacker News API

Current Load: 0,0.004

About

This is an unofficial API for Y Combinator's HackerNews that was developed for iHackerNews.com (a mobile version of HN). It allows you to programmatically retrieve data and interact with news.ycombinator.com. Data is cached anywhere from 2 to 4 minutes. Requests to news.ycombinator.com are throttled at a resonable rate -- cache hits are not throttled.

Authentication is only required for voting and commenting. You should keep in mind that I’m not affiliated with Y Combinator in any way, I’m not evil, but you don’t know that. I do not store, and never will store, passwords or auth tokens – I only proxy them to ycombinator.

If you find this useful and would like to use it, please do. If you want to say “thanks”, please provide a link to my homepage or @ronnieroller.

Hacker News Database Download

I was able to compile the HN database. I'm making it available for download through bittorrent for the community to use. It's in XML format. As of November 7, 2010 there are 1,707,850 items in the database, which covers most of what's on HN. There's a few missing items, mostly deeply nested comments -- this will be fixed in time.

Below is an example of the XML for a post. AskHN has an empty Url field with the text in the Text field. Posts are type=1. Comments are type=2. Comments have an emtpy Url field with the comment stored in the Text field. Timestamps are accurate to the day.

                
<HackerNews>
    <row>
        <ID>1</ID> 
        <Url>http://ycombinator.com</Url> 
        <Title>Y Combinator</Title> 
        <Text /> 
        <Username>pg</Username> 
        <Points>39</Points> 
        <Type>1</Type> 
        <Timestamp>2006-10-09T20:33:12.700</Timestamp> 
        <CommentCount>15</CommentCount> 
        <ParentID /> 
    </row>
</HackerNews>
                
            

Download: The database download has been disabled.

Special thanks to Jonathan Keith, Joseph Turian (HN bravura), and Steve Morin for help in creating this database.

API Data Types

Data can be requested in JSON, JSONP, or XML formats. The default is JSON. To ask for another type, append the format to the querystring. Example:
JSON: http://api.ihackernews.com/page
JSONP: http://api.ihackernews.com/page?format=jsonp&callback=yourFunction
XML: http://api.ihackernews.com/page?format=xml

Find submitted articles by URL

• URL: http://api.ihackernews.com/getid?url={url} Note, {url} needs to be urlencoded.
• Method: GET
• Returns: Integer array of post IDs
  
• Test:  

Retrieve Front Page News

• URL: http://api.ihackernews.com/page or http://api.ihackernews.com/page/{nextId}
• Method: GET
• Returns: nextId: ID for next page of links
  items: array of links {commentCount, id, points, postedAgo, postedBy, title, url}
  cachedOnUTC: UTC date and time when request was cached

Retrieve Posts Submitted By User

• URL: http://api.ihackernews.com/by/{username} or http://api.ihackernews.com/by/{username}/{nextId}
• Method: GET
• Returns: nextId: ID for next page of links
  items: array of links {commentCount, id, points, postedAgo, postedBy, title, url}
  cachedOnUTC: UTC date and time when request was cached

Retrieve Newly Submitted Posts

• URL: http://api.ihackernews.com/new or http://api.ihackernews.com/new/{nextId}
• Method: GET
• Returns: nextId: ID for next page of links
  items: array of links {commentCount, id, points, postedAgo, postedBy, title, url}
  cachedOnUTC: UTC date and time when request was cached

Retrieve Newly Submitted Comments (Added this on Oct 9 2010)

• URL: http://api.ihackernews.com/newcomments
• Method: GET
• Returns: array of comments {comment, id, parentID, points, postedAgo, postedBy, postId}
  
• Source: http://news.ycombinator.com/newcomments

Retrieve AskHN Posts

• URL: http://api.ihackernews.com/ask or http://api.ihackernews.com/ask/{nextId}
• Method: GET
• Returns: nextId: ID for next page of links
  items: array of links {commentCount, id, points, postedAgo, postedBy, title, url}
  cachedOnUTC: UTC date and time when request was cached

Retrieve Post (includes url, title, comments, etc...)

• URL: http://api.ihackernews.com/post/{id}
{id} is the integer ID of the post.
• Method: GET
• Returns: commentCount, id, points, postedAgo, postedBy, title, url, text (ask hn text), array of comments {children, comment, id, parentID, points, postedAgo, postedBy, postId}
  

Deprecated - Retrieve Comments for Posts

• URL: http://api.ihackernews.com/comments/{id}
{id} is the integer ID of the post.
• Method: GET
• Returns: array of comments {children, comment, id, parentID, points, postedAgo, postedBy, postId}
  

Retrieve Comment Threads for a user

• URL: http://api.ihackernews.com/threads/{userID}
• Method: GET
• Returns: array of comments {children, comment, id, parentID, points, postedAgo, postedBy, postId}
  

Retrieve a user's profile

• URL: http://api.ihackernews.com/profile/{userID}
• Method: GET
• Returns: about, createdAgo, karma, username
  cachedOnUTC: UTC date and time when request was cached

Login - Retrieve a user's auth token (used for voting and commenting)

• This method is disabled until further notice
• URL: http://api.ihackernews.com/login
• Method: POST. {username}, {password}
• Returns: token

Vote on a post or comment

• This method is disabled until further notice
• URL: http://api.ihackernews.com/vote
• Method: POST. {username}, {token}, {id} integer id of comment or post, {direction} up or down, up is default
• Returns: true/false

Post a comment to a post or as a reply to a parent comment

• This method is disabled until further notice
• URL: http://api.ihackernews.com/comment
• Method: POST. {username}, {token}, {id} integer id of parent comment or post, {comment}
• Returns: true/false