Documentation and Samples for the Official HN API

Overview

Hacker News API

Overview

In partnership with Firebase, we're making the public Hacker News data available in near real time. Firebase enables easy access from Android, iOS and the web. Servers aren't left out.

If you can use one of the many Firebase client libraries, you really should. The libraries handle networking efficiently and can raise events when things change. Be sure to check them out.

Please email [email protected] if you find any bugs.

URI and Versioning

We hope to improve the API over time. The changes won't always be backward compatible, so we're going to use versioning. This first iteration will have URIs prefixed with https://hacker-news.firebaseio.com/v0/ and is structured as described below. There is currently no rate limit.

For versioning purposes, only removal of a non-optional field or alteration of an existing field will be considered incompatible changes. Clients should gracefully handle additional fields they don't expect, and simply ignore them.

Design

The v0 API is essentially a dump of our in-memory data structures. We know, what works great locally in memory isn't so hot over the network. Many of the awkward things are just the way HN works internally. Want to know the total number of comments on an article? Traverse the tree and count. Want to know the children of an item? Load the item and get their IDs, then load them. The newest page? Starts at item maxid and walks backward, keeping only the top level stories. Same for Ask, Show, etc.

I'm not saying this to defend it - It's not the ideal public API, but it's the one we could release in the time we had. While awkward, it's possible to implement most of HN using it.

Items

Stories, comments, jobs, Ask HNs and even polls are just items. They're identified by their ids, which are unique integers, and live under /v0/item/<id>.

All items have some of the following properties, with required properties in bold:

Field Description
id The item's unique id.
deleted true if the item is deleted.
type The type of item. One of "job", "story", "comment", "poll", or "pollopt".
by The username of the item's author.
time Creation date of the item, in Unix Time.
text The comment, story or poll text. HTML.
dead true if the item is dead.
parent The comment's parent: either another comment or the relevant story.
poll The pollopt's associated poll.
kids The ids of the item's comments, in ranked display order.
url The URL of the story.
score The story's score, or the votes for a pollopt.
title The title of the story, poll or job. HTML.
parts A list of related pollopts, in display order.
descendants In the case of stories or polls, the total comment count.

For example, a story: https://hacker-news.firebaseio.com/v0/item/8863.json?print=pretty

{
  "by" : "dhouston",
  "descendants" : 71,
  "id" : 8863,
  "kids" : [ 8952, 9224, 8917, 8884, 8887, 8943, 8869, 8958, 9005, 9671, 8940, 9067, 8908, 9055, 8865, 8881, 8872, 8873, 8955, 10403, 8903, 8928, 9125, 8998, 8901, 8902, 8907, 8894, 8878, 8870, 8980, 8934, 8876 ],
  "score" : 111,
  "time" : 1175714200,
  "title" : "My YC app: Dropbox - Throw away your USB drive",
  "type" : "story",
  "url" : "http://www.getdropbox.com/u/2/screencast.html"
}

comment: https://hacker-news.firebaseio.com/v0/item/2921983.json?print=pretty

{
  "by" : "norvig",
  "id" : 2921983,
  "kids" : [ 2922097, 2922429, 2924562, 2922709, 2922573, 2922140, 2922141 ],
  "parent" : 2921506,
  "text" : "Aw shucks, guys ... you make me blush with your compliments.<p>Tell you what, Ill make a deal: I'll keep writing if you keep reading. K?",
  "time" : 1314211127,
  "type" : "comment"
}

ask: https://hacker-news.firebaseio.com/v0/item/121003.json?print=pretty

{
  "by" : "tel",
  "descendants" : 16,
  "id" : 121003,
  "kids" : [ 121016, 121109, 121168 ],
  "score" : 25,
  "text" : "<i>or</i> HN: the Next Iteration<p>I get the impression that with Arc being released a lot of people who never had time for HN before are suddenly dropping in more often. (PG: what are the numbers on this? I'm envisioning a spike.)<p>Not to say that isn't great, but I'm wary of Diggification. Between links comparing programming to sex and a flurry of gratuitous, ostentatious  adjectives in the headlines it's a bit concerning.<p>80% of the stuff that makes the front page is still pretty awesome, but what's in place to keep the signal/noise ratio high? Does the HN model still work as the community scales? What's in store for (++ HN)?",
  "time" : 1203647620,
  "title" : "Ask HN: The Arc Effect",
  "type" : "story"
}

job: https://hacker-news.firebaseio.com/v0/item/192327.json?print=pretty

{
  "by" : "justin",
  "id" : 192327,
  "score" : 6,
  "text" : "Justin.tv is the biggest live video site online. We serve hundreds of thousands of video streams a day, and have supported up to 50k live concurrent viewers. Our site is growing every week, and we just added a 10 gbps line to our colo. Our unique visitors are up 900% since January.<p>There are a lot of pieces that fit together to make Justin.tv work: our video cluster, IRC server, our web app, and our monitoring and search services, to name a few. A lot of our website is dependent on Flash, and we're looking for talented Flash Engineers who know AS2 and AS3 very well who want to be leaders in the development of our Flash.<p>Responsibilities<p><pre><code>    * Contribute to product design and implementation discussions\n    * Implement projects from the idea phase to production\n    * Test and iterate code before and after production release \n</code></pre>\nQualifications<p><pre><code>    * You should know AS2, AS3, and maybe a little be of Flex.\n    * Experience building web applications.\n    * A strong desire to work on website with passionate users and ideas for how to improve it.\n    * Experience hacking video streams, python, Twisted or rails all a plus.\n</code></pre>\nWhile we're growing rapidly, Justin.tv is still a small, technology focused company, built by hackers for hackers. Seven of our ten person team are engineers or designers. We believe in rapid development, and push out new code releases every week. We're based in a beautiful office in the SOMA district of SF, one block from the caltrain station. If you want a fun job hacking on code that will touch a lot of people, JTV is for you.<p>Note: You must be physically present in SF to work for JTV. Completing the technical problem at <a href=\"http://www.justin.tv/problems/bml\" rel=\"nofollow\">http://www.justin.tv/problems/bml</a> will go a long way with us. Cheers!",
  "time" : 1210981217,
  "title" : "Justin.tv is looking for a Lead Flash Engineer!",
  "type" : "job",
  "url" : ""
}

poll: https://hacker-news.firebaseio.com/v0/item/126809.json?print=pretty

{
  "by" : "pg",
  "descendants" : 54,
  "id" : 126809,
  "kids" : [ 126822, 126823, 126993, 126824, 126934, 127411, 126888, 127681, 126818, 126816, 126854, 127095, 126861, 127313, 127299, 126859, 126852, 126882, 126832, 127072, 127217, 126889, 127535, 126917, 126875 ],
  "parts" : [ 126810, 126811, 126812 ],
  "score" : 46,
  "text" : "",
  "time" : 1204403652,
  "title" : "Poll: What would happen if News.YC had explicit support for polls?",
  "type" : "poll"
}

and one of its parts: https://hacker-news.firebaseio.com/v0/item/160705.json?print=pretty

{
  "by" : "pg",
  "id" : 160705,
  "poll" : 160704,
  "score" : 335,
  "text" : "Yes, ban them; I'm tired of seeing Valleywag stories on News.YC.",
  "time" : 1207886576,
  "type" : "pollopt"
}

Users

Users are identified by case-sensitive ids, and live under /v0/user/. Only users that have public activity (comments or story submissions) on the site are available through the API.

Field Description
id The user's unique username. Case-sensitive. Required.
created Creation date of the user, in Unix Time.
karma The user's karma.
about The user's optional self-description. HTML.
submitted List of the user's stories, polls and comments.

For example: https://hacker-news.firebaseio.com/v0/user/jl.json?print=pretty

{
  "about" : "This is a test",
  "created" : 1173923446,
  "delay" : 0,
  "id" : "jl",
  "karma" : 2937,
  "submitted" : [ 8265435, 8168423, 8090946, 8090326, 7699907, 7637962, 7596179, 7596163, 7594569, 7562135, 7562111, 7494708, 7494171, 7488093, 7444860, 7327817, 7280290, 7278694, 7097557, 7097546, 7097254, 7052857, 7039484, 6987273, 6649999, 6649706, 6629560, 6609127, 6327951, 6225810, 6111999, 5580079, 5112008, 4907948, 4901821, 4700469, 4678919, 3779193, 3711380, 3701405, 3627981, 3473004, 3473000, 3457006, 3422158, 3136701, 2943046, 2794646, 2482737, 2425640, 2411925, 2408077, 2407992, 2407940, 2278689, 2220295, 2144918, 2144852, 1875323, 1875295, 1857397, 1839737, 1809010, 1788048, 1780681, 1721745, 1676227, 1654023, 1651449, 1641019, 1631985, 1618759, 1522978, 1499641, 1441290, 1440993, 1436440, 1430510, 1430208, 1385525, 1384917, 1370453, 1346118, 1309968, 1305415, 1305037, 1276771, 1270981, 1233287, 1211456, 1210688, 1210682, 1194189, 1193914, 1191653, 1190766, 1190319, 1189925, 1188455, 1188177, 1185884, 1165649, 1164314, 1160048, 1159156, 1158865, 1150900, 1115326, 933897, 924482, 923918, 922804, 922280, 922168, 920332, 919803, 917871, 912867, 910426, 902506, 891171, 807902, 806254, 796618, 786286, 764412, 764325, 642566, 642564, 587821, 575744, 547504, 532055, 521067, 492164, 491979, 383935, 383933, 383930, 383927, 375462, 263479, 258389, 250751, 245140, 243472, 237445, 229393, 226797, 225536, 225483, 225426, 221084, 213940, 213342, 211238, 210099, 210007, 209913, 209908, 209904, 209903, 170904, 165850, 161566, 158388, 158305, 158294, 156235, 151097, 148566, 146948, 136968, 134656, 133455, 129765, 126740, 122101, 122100, 120867, 120492, 115999, 114492, 114304, 111730, 110980, 110451, 108420, 107165, 105150, 104735, 103188, 103187, 99902, 99282, 99122, 98972, 98417, 98416, 98231, 96007, 96005, 95623, 95487, 95475, 95471, 95467, 95326, 95322, 94952, 94681, 94679, 94678, 94420, 94419, 94393, 94149, 94008, 93490, 93489, 92944, 92247, 91713, 90162, 90091, 89844, 89678, 89498, 86953, 86109, 85244, 85195, 85194, 85193, 85192, 84955, 84629, 83902, 82918, 76393, 68677, 61565, 60542, 47745, 47744, 41098, 39153, 38678, 37741, 33469, 12897, 6746, 5252, 4752, 4586, 4289 ]
}

Live Data

The coolest part of Firebase is its support for change notifications. While you can subscribe to individual items and profiles, you'll need to use the following to observe front page ranking, new items, and new profiles.

Max Item ID

The current largest item id is at /v0/maxitem. You can walk backward from here to discover all items.

Example: https://hacker-news.firebaseio.com/v0/maxitem.json?print=pretty

9130260

New, Top and Best Stories

Up to 500 top and new stories are at /v0/topstories (also contains jobs) and /v0/newstories. Best stories are at /v0/beststories.

Example: https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty

[ 9129911, 9129199, 9127761, 9128141, 9128264, 9127792, 9129248, 9127092, 9128367, ..., 9038733 ]

Ask, Show and Job Stories

Up to 200 of the latest Ask HN, Show HN, and Job stories are at /v0/askstories, /v0/showstories, and /v0/jobstories.

Example: https://hacker-news.firebaseio.com/v0/askstories.json?print=pretty

[ 9127232, 9128437, 9130049, 9130144, 9130064, 9130028, 9129409, 9127243, 9128571, ..., 9120990 ]

Changed Items and Profiles

The item and profile changes are at /v0/updates.

Example: https://hacker-news.firebaseio.com/v0/updates.json?print=pretty

{
  "items" : [ 8423305, 8420805, 8423379, 8422504, 8423178, 8423336, 8422717, 8417484, 8423378, 8423238, 8423353, 8422395, 8423072, 8423044, 8423344, 8423374, 8423015, 8422428, 8423377, 8420444, 8423300, 8422633, 8422599, 8422408, 8422928, 8394339, 8421900, 8420902, 8422087 ],
  "profiles" : [ "thefox", "mdda", "plinkplonk", "GBond", "rqebmm", "neom", "arram", "mcmancini", "metachris", "DubiousPusher", "dochtman", "kstrauser", "biren34", "foobarqux", "mkehrt", "nathanm412", "wmblaettler", "JoeAnzalone", "rcconf", "johndbritton", "msie", "cktsai", "27182818284", "kevinskii", "wildwood", "mcherm", "naiyt", "matthewmcg", "joelhaus", "tshtf", "MrZongle2", "Bogdanp" ]
}
Issues
  • Update your API!

    Update your API!

    You don't have issues enabled, so here's me trying to communicate that you guys never updated and newer SDKs can't readily consume your API

    opened by ZacSweers 11
  • /updates is about title/url changes (Item) and about changes (User)

    /updates is about title/url changes (Item) and about changes (User)

    That's what I understand right now, but just starting out with the API so I might be wrong.

    opened by localhostdotdev 4
  • 401 while requesting for /v0/item for comments

    401 while requesting for /v0/item for comments

    Hi please ignore the changes in this PR, I just use it as a way to log issue since the repo does not support issues.

    It looks like a lot of comment items returns 401 while being requested, and I have received multiple reports from my client's users.

    E.g.: Story returns 200: https://hacker-news.firebaseio.com/v0/item/10963401.json Comment under this story returns 401: https://hacker-news.firebaseio.com/v0/item/10963624.json

    {
        "error": "Permission denied"
    }
    

    A sample curl:

    $ curl --verbose https://hacker-news.firebaseio.com/v0/item/10963624.json
    *   Trying 104.197.145.189...
    * Connected to hacker-news.firebaseio.com (104.197.145.189) port 443 (#0)
    * TLS 1.2 connection using TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
    * Server certificate: *.firebaseio.com
    * Server certificate: Google Internet Authority G2
    * Server certificate: GeoTrust Global CA
    > GET /v0/item/10963624.json HTTP/1.1
    > Host: hacker-news.firebaseio.com
    > User-Agent: curl/7.43.0
    > Accept: */*
    >
    < HTTP/1.1 401 Unauthorized
    < Content-Length: 36
    < Content-Type: application/json; charset=utf-8
    < Cache-Control: no-cache
    < Strict-Transport-Security: max-age=31556926; includeSubDomains; preload
    <
    {
      "error" : "Permission denied"
    }
    
    opened by hidroh 3
  • Specify both story and job can be return from list

    Specify both story and job can be return from list

    A small documentation update, to be clear that those "stories" endpoint may return item that is not type "story".

    No. 78 is a job, not a story

    (:point_up: no. 78 is a job, not a story. Taken on 2019/07/14)

    Or is it possible for those endpoints to return any type of item? if that's the case, I think it'd still be nice to point it out.

    opened by louis993546 3
  • Explicitly include a job type response

    Explicitly include a job type response

    Was working on a Go client implementation and noticed that a Job example was not provided.

    opened by munrocape 2
  • clarify title may use HTML encoded entities

    clarify title may use HTML encoded entities

    Via email, the title element may use HTML encoded entities and need to be decoded by the API consumer (&lt;, &gt;, etc.)

    opened by troyengel 1
  • Update README.md - fix URL's

    Update README.md - fix URL's

    Certain URL's are missing the .json which is required to make a successful API call.

    opened by BDiehr 1
  • gw36402

    gw36402

    Another repository of mine

    opened by gw36402 1
  • Create saikishore

    Create saikishore

    { margin: 0; padding: 0; }

    header { background-image:url( pic1.jpg); height: 100vh; background-size: cover; background-position:center; }

    .main-nav { float: right; list-style: none; margin-top: 30px; }

    .main-nav li { display: inline-block; }

    .main-nav li a { color: black; text-decoration: none; padding: 5px 20px; font-family: "Roboto", sans-serif; font-size: 15px; }

    .main-nav li.active a { border: 1px solid white; }

    .main-nav li a:hover { border: 1px solid white; }

    .logo img { width: 150px; height: auto; float: left; }

    body { font-family:monospace; }

    .row { max-width:1200px; margin:auto; }

    Loading...
    opened by saikishore9899 1
  •  Is there any way to get contents of the stories?

    Is there any way to get contents of the stories?

    This is a question or Issue
    We only get ids and title and also url. But how to get associated text-contents, is there any option the API provides?

    opened by rohitnitk 1
Owner
Y Combinator Hacker News
Public resources related to Hacker News.
Y Combinator Hacker News
TeslaPy - A Python implementation based on unofficial documentation of the client side interface to the Tesla Motors Owner API

TeslaPy - A Python implementation based on unofficial documentation of the client side interface to the Tesla Motors Owner API, which provides functiona

Tim Dorssers 96 Nov 21, 2021
Discord Bot that leverages the idea of nested containers using podman, runs untrusted user input, executes Quantum Circuits, allows users to refer to the Qiskit Documentation, and provides the ability to search questions on the Quantum Computing StackExchange.

Discord Bot that leverages the idea of nested containers using podman, runs untrusted user input, executes Quantum Circuits, allows users to refer to the Qiskit Documentation, and provides the ability to search questions on the Quantum Computing StackExchange.

Mehul 21 Nov 23, 2021
Official python API for Phish.AI public and private API to detect zero-day phishing websites

phish-ai-api Summary Official python API for Phish.AI public and private API to detect zero-day phishing websites How it Works (TLDR) Essentially we h

Phish.AI 165 Sep 28, 2021
Beyonic API Python official client library simplified examples using Flask, Django and Fast API.

Beyonic API Python official client library simplified examples using Flask, Django and Fast API.

Harun Mbaabu Mwenda 45 Nov 18, 2021
Telegram PHub Bot using ARQ Api and Pyrogram. This Bot can Download and Send PHub HQ videos in Telegram using ARQ API.

Tg_PHub_Bot Telegram PHub Bot using ARQ Api and Pyrogram. This Bot can Download and Send PHub HQ videos in Telegram using ARQ API. OS Support All linu

TheProgrammerCat 9 Sep 20, 2021
🚧 finCLI's own News API. No more limited API calls. Unlimited credible and latest information on BTC, Ethereum, Indian and Global Finance.

?? finCLI's own News API. No more limited API calls. Unlimited credible and latest information on BTC, Ethereum, Indian and Global Finance.

finCLI 4 Nov 6, 2021
Official Python client for the MonkeyLearn API. Build and consume machine learning models for language processing from your Python apps.

MonkeyLearn API for Python Official Python client for the MonkeyLearn API. Build and run machine learning models for language processing from your Pyt

MonkeyLearn 147 Nov 27, 2021
A python to scratch API connector. Can fetch data from the API and send it back in cloud variables.

Scratch2py Scratch2py or S2py is a easy to use, versatile tool to communicate with the Scratch API Based of scratchclient by Raihan142857 Installation

null 14 Nov 15, 2021
The Bot provide Hadith API and fetch content via api.hadith.sutanlab.id

Bot Hadith-API on Telegram The Bot provide Hadith API and fetch content via api.hadith.sutanlab.id Built With Python Asynchronous HTTP protocol client

xMan 8 Aug 13, 2021
Deploy a STAC API and a dynamic mosaic tiler API using AWS CDK.

Earth Observation API Deploy a STAC API and a dynamic mosaic tiler API using AWS CDK.

Development Seed 20 Nov 3, 2021
A new coin listing alert bot using Python, Flask, MongoDB, Telegram API and Binance API

Bzzmans New Coin Listing Detection Bot Architecture About Project Work in progress. This bot basically gets new coin listings from Binance using Binan

Eyüp Barlas 12 Nov 28, 2021
API which uses discord+mojang api to scrape NameMC searches/droptime/dropping status of minecraft names, and texture links

API which uses discord+mojang api to scrape NameMC searches/droptime/dropping status of minecraft names, and texture links

null 2 Nov 23, 2021
DEPRECATED - Official Python Client for the Discogs API

⚠️ DEPRECATED This repository is no longer maintained. You can still use a REST client like Requests or other third-party Python library to access the

Discogs 486 Nov 17, 2021
The Official Dropbox API V2 SDK for Python

The offical Dropbox SDK for Python. Documentation can be found on Read The Docs. Installation Create an app via the Developer Console. Install via pip

Dropbox 752 Nov 24, 2021
Unofficial Python wrapper for official Hacker News API

haxor Unofficial Python wrapper for official Hacker News API. Installation pip install haxor Usage Import and initialization: from hackernews import H

null 139 Nov 16, 2021
The Official Twilio SendGrid Led, Community Driven Python API Library

The default branch name for this repository has been changed to main as of 07/27/2020. This library allows you to quickly and easily use the SendGrid

Twilio SendGrid 1.2k Nov 25, 2021
A Pythonic client for the official https://data.gov.gr API.

pydatagovgr An unofficial Pythonic client for the official data.gov.gr API. Aims to be an easy, intuitive and out-of-the-box way to: find data publish

Ilias Antonopoulos 34 Nov 11, 2021
The official wrapper for spyse.com API, written in Python, aimed to help developers build their integrations with Spyse.

Python wrapper for Spyse API The official wrapper for spyse.com API, written in Python, aimed to help developers build their integrations with Spyse.

Spyse 6 Nov 14, 2021
Official Python wrapper for the Quantel Finance API

Quantel is a powerful financial data and insights API. It provides easy access to world-class financial information. Quantel goes beyond just financial statements, giving users valuable information like insider transactions, major shareholder transactions, share ownership, peers, and so much more.

Guy 44 Nov 23, 2021