Unofficial Python API for Hacker News.

Build Status	Test Coverage	Version	Downloads

Features

• Compatible with Python 2 (2.7+).
• Supports ‘top’, ‘news2’,‘newest’ and ‘best’ posts
• Retrieve comments from posts (flat list for now) (story.get_comments())
• Pagination support for comments
• Handles external posts, self posts and job posts
• Get post details for any post (Story.fromid(7024626))

Installation

$ pip install HackerNews

Usage

NOTE: Do not make a lot of requests in a short period of time. HN has it’s own throttling system.

from hn import HN

hn = HN()

# print the first 2 pages of newest stories
for story in hn.get_stories(story_type='newest', limit=60):
    print(story.rank, story.title)

API Reference

Class: HN

Get stories from Hacker News

get_stories

Parameters:

Name	Type	Required	Description	Default
story_type	string	No	Returns the stories from this page. One of (empty string), news2, newest, best	(empty string) (top)
limit	integer	No	Number of stories required from the given page. Cannot be more than 30.	30

Example:

from hn import HN
hn = HN()
hn.get_stories(story_type='newest', limit=10)

get_leaders

Parameters:

Name	Type	Required	Description	Default
limit	integer	No	Number of top leaders to return	10

Example:

from hn import HN
hn = HN()

# get top 20 users of HN
hn.get_leaders(limit=20)

Class: Story

Each Story has the following properties

• rank - the rank of story on the page (keep pagination in mind)
• story_id - the story’s id
• title - the title of the story
• is_self - true for self/job stories
• link - the URL it points to ('' for self posts)
• domain - the domain of the link ('' for self posts)
• points - the points/karma on the story
• submitter - the user who submitted the story ('' for job posts)
• submitter_profile - the above user’s profile link (can be '')
• published_time - the published time
• num_comments - the number of comments a story has
• comments_link - the link to the comments page

Make an object from the ID of a story

fromid

Parameters:

Name	Type	Required	Description	Default
item_id	integer	Yes	Initializes an instance of Story for given item_id. Must be a valid story id.

Example:

from hn import Story
story = Story.fromid(6374031)
print story.title

Get a list of Comment’s for this story

get_comments

Parameters:

Name	Type	Required	Description	Default

Example:

from hn import Story
story = Story.fromid(6374031)
comments = story.get_comments()

Class: Comment

Each Comment has the following properties

• comment_id - the comment’s item id
• level - comment’s nesting level
• user - user’s name who submitted the post
• time_ago - time when it was submitted
• body - text representation of comment (unformatted)
• body_html - html of comment, may not be valid

Class: User

Each User has the following properties

• username - user’s profile name
• date_created - when the profile was created
• karma - user’s e-points
• avg - user’s average karma per day

Examples

See my_test_bot.py

Tests

To run the tests locally just do:

$ chmod 777 runtests.sh
$ ./runtests.sh

To run individual tests,

$ python -m unittest tests.<module name>

The tests are run on a local test server with predownloaded original responses.

Donations

If HackerNewsAPI has helped you in any way, and you’d like to help the developer, please consider donating.

- BTC: 19dLDL4ax7xRmMiGDAbkizh6WA6Yei2zP5

- Flattr: https://flattr.com/profile/thekarangoel

Contribute

If you want to add any new features, or improve existing ones, feel free to send a pull request!