{"id":13834389,"url":"https://github.com/karan/HackerNewsAPI","last_synced_at":"2025-07-10T04:31:58.687Z","repository":{"id":62568879,"uuid":"12190067","full_name":"karan/HackerNewsAPI","owner":"karan","description":":newspaper: Unofficial Python API for Hacker News. RESTful API at https://github.com/karan/HNify","archived":false,"fork":false,"pushed_at":"2019-11-04T03:25:48.000Z","size":436,"stargazers_count":389,"open_issues_count":16,"forks_count":66,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-04-13T09:12:19.242Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-18T04:00:52.000Z","updated_at":"2024-03-21T01:54:52.000Z","dependencies_parsed_at":"2022-11-03T17:01:00.140Z","dependency_job_id":null,"html_url":"https://github.com/karan/HackerNewsAPI","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karan%2FHackerNewsAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karan%2FHackerNewsAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karan%2FHackerNewsAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karan%2FHackerNewsAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karan","download_url":"https://codeload.github.com/karan/HackerNewsAPI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225618830,"owners_count":17497589,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T14:00:33.463Z","updated_at":"2024-11-20T19:31:54.920Z","avatar_url":"https://github.com/karan.png","language":"Python","readme":"![Hacker News API](https://raw.github.com/karan/HackerNewsAPI/master/HN.jpg)\n\nUnofficial Python API for [Hacker News](https://news.ycombinator.com/).\n\n\n| Build Status | Test Coverage | Version | Downloads |\n| ------------ | ------------- | ------- | ------------------- |\n| [![Build Status](https://travis-ci.org/karan/HackerNewsAPI.png?branch=master)](https://travis-ci.org/karan/HackerNewsAPI) | [![Coverage Status](https://coveralls.io/repos/karan/HackerNewsAPI/badge.png)](https://coveralls.io/r/karan/HackerNewsAPI) | [![Latest Version](https://pypip.in/v/HackerNews/badge.png)](https://pypi.python.org/pypi/HackerNews/) | [![Downloads](https://pypip.in/d/HackerNews/badge.png)](https://pypi.python.org/pypi/HackerNews/) |\n\n\nFeatures\n========\n\n- Compatible with Python 2 (2.7+).\n- Supports 'top', 'news2','newest' and 'best' posts\n- Retrieve comments from posts (flat list for now) (`story.get_comments()`)\n- Pagination support for comments\n- Handles external posts, self posts and job posts\n- Get post details for any post (`Story.fromid(7024626)`)\n\n\nInstallation\n========\n\n    $ pip install HackerNews\n\n\nUsage\n========\n\n**NOTE:** Do not make a lot of requests in a short period of time. HN has it's own throttling system.\n\n\n    from hn import HN\n\n    hn = HN()\n\n    # print the first 2 pages of newest stories\n    for story in hn.get_stories(story_type='newest', limit=60):\n        print(story.rank, story.title)\n\n\nAPI Reference\n========\n\n## Class: `HN`\n\n### Get stories from Hacker News\n\n#### `get_stories`\n\n**Parameters:**\n\n| Name | Type | Required | Description | Default |\n| ---- | ---- | -------- | ----------- | ------- |\n| `story_type` | string | No | Returns the stories from this page. One of `(empty string)`, `news2`, `newest`, `best` | `(empty string)` (top) |\n| `limit` | integer | No | Number of stories required from the given page. Cannot be more than 30. | 30 |\n\n**Example:**\n\n\tfrom hn import HN\n\thn = HN()\n\thn.get_stories(story_type='newest', limit=10)\n\n#### `get_leaders`\n\n**Parameters:**\n\n| Name | Type | Required | Description | Default |\n| ---- | ---- | -------- | ----------- | ------- |\n| `limit` | integer | No | Number of top leaders to return | 10 |\n\n**Example:**\n\n    from hn import HN\n    hn = HN()\n\n    # get top 20 users of HN\n    hn.get_leaders(limit=20)\n\n## Class: `Story`\n\nEach `Story` has the following properties\n\n- **rank** - the rank of story on the page (keep pagination in mind)\n- **story_id** - the story's id\n- **title** - the title of the story\n- **is_self** - true for self/job stories\n- **link** - the URL it points to (`''` for self posts)\n- **domain** - the domain of the link (`''` for self posts)\n- **points** - the points/karma on the story\n- **submitter** - the user who submitted the story (`''` for job posts)\n- **submitter_profile** - the above user's profile link (can be `''`)\n- **published_time** - the published time\n- **num_comments** - the number of comments a story has\n- **comments_link** - the link to the comments page\n\n### Make an object from the ID of a story\n\n#### `fromid`\n\n**Parameters:**\n\n| Name | Type | Required | Description | Default |\n| ---- | ---- | -------- | ----------- | ------- |\n| `item_id` | integer | Yes | Initializes an instance of Story for given item_id. Must be a valid story id. |  |\n\n**Example:**\n\n\tfrom hn import Story\n\tstory = Story.fromid(6374031)\n\tprint story.title\n\n### Get a list of Comment's for this story\n\n#### `get_comments`\n\n**Parameters:**\n\n| Name | Type | Required | Description | Default |\n| ---- | ---- | -------- | ----------- | ------- |\n|  |  |  |  |  |\n\n**Example:**\n\n\tfrom hn import Story\n\tstory = Story.fromid(6374031)\n\tcomments = story.get_comments()\n\n## Class: `Comment`\n\nEach `Comment` has the following properties\n\n- **comment_id** - the comment's item id\n- **level** - comment's nesting level\n- **user** - user's name who submitted the post\n- **time_ago** - time when it was submitted\n- **body** - text representation of comment (unformatted)\n- **body_html** - html of comment, may not be valid\n\n## Class: `User`\n\nEach `User` has the following properties\n\n- **username** - user's profile name\n- **date_created** - when the profile was created\n- **karma** - user's e-points\n- **avg** - user's average karma per day\n\nExamples\n========\n\nSee [`my_test_bot.py`](https://github.com/karan/HackerNewsAPI/blob/master/my_test_bot.py)\n\n\nTests\n========\n\nTo run the tests locally just do:\n\n    $ chmod 777 runtests.sh\n    $ ./runtests.sh\n\nTo run individual tests,\n\n    $ python -m unittest tests.\u003cmodule name\u003e\n\nThe tests are run on a local test server with predownloaded original responses.\n\nDonations\n========\n\nIf HackerNewsAPI has helped you in any way, and you'd like to help the developer, please consider donating.\n\n**- BTC: [19dLDL4ax7xRmMiGDAbkizh6WA6Yei2zP5](http://i.imgur.com/bAQgKLN.png)**\n\n**- Flattr: [https://flattr.com/profile/thekarangoel](https://flattr.com/profile/thekarangoel)**\n\n\nContribute\n========\n\nIf you want to add any new features, or improve existing ones, feel free to send a pull request!\n","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaran%2FHackerNewsAPI","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaran%2FHackerNewsAPI","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaran%2FHackerNewsAPI/lists"}