Master the IHacker News Search API: A Complete Guide

If you’ve ever wanted to tap into the real‑time pulse of tech headlines, the IHacker News Search API is the shortcut you’ve been waiting for. It lets developers query the same stories that populate the popular IHacker News aggregator, all without scraping HTML or fighting rate‑limits. In this guide we’ll walk through everything from authentication to crafting efficient queries, so you can start building data‑driven tools today.

What Is the IHacker News Search API?

The IHacker News Search API is a RESTful interface that mirrors the public search functionality of the IHacker News website. It returns JSON‑encoded results for stories, comments, and users, complete with timestamps, scores, and URLs. Because the service is built on top of Algolia’s search engine, you get fast, typo‑tolerant matching and facet filtering out of the box.

Getting Started: Access and Authentication

Unlike many commercial APIs, the IHacker News Search API does not require an API key for basic usage. You can start sending GET requests immediately, which makes experimentation painless. However, for higher throughput or commercial projects you may want to register for a free Algolia account and obtain an application ID and API key; this lifts the default rate limit from 1,000 requests per day to 10,000.

To register, head to algolia.com/dashboard, create a new application, and copy the credentials. Then add two HTTP headers to every request:

• X-Algolia-Application-Id: YOUR_APP_ID
• X-Algolia-API-Key: YOUR_SEARCH_ONLY_KEY

These headers are safe to expose in client‑side code because the search‑only key only permits read operations.

Core Endpoints and Their Parameters

The API revolves around a single search endpoint:

• https://hn.algolia.com/api/v1/search

Optional query parameters let you narrow results:

• query – the text you’re looking for (e.g., query=react).
• tags – filter by item type: story, comment, author_<username>.
• numericFilters – apply numeric constraints such as points>100 or created_at_i>1622505600.
• hitsPerPage – number of results per page (max 1000).
• page – pagination offset, starting at 0.

All parameters are URL‑encoded and can be combined arbitrarily. For example, a request for high‑scoring stories about “AI” posted in the last month might look like:

https://hn.algolia.com/api/v1/search?query=AI&tags=story&numericFilters=points%3E200,created_at_i%3E1661990400

Practical Example: Building a “Top Stories” Widget

Suppose you want to display the ten most popular stories from the past week. You could fetch them with a single call:

https://hn.algolia.com/api/v1/search_by_date?tags=story&numericFilters=created_at_i%3E{one_week_ago}&hitsPerPage=10&orderBy=points

Replace {one_week_ago} with a Unix timestamp for seven days ago. The response includes an array of hits, each containing title, url, points, and author. Loop through the array in your front‑end code and render a list of linked titles.

Rate Limits, Caching, and Best Practices

Even with an Algolia key, the service caps you at 10 requests per second. Exceeding that limit returns a 429 Too Many Requests response. To stay within limits, consider the following tactics:

• Cache frequent queries. Store results for at least five minutes; many popular terms change slowly.
• Batch pagination. Instead of requesting one page at a time in a loop, request larger hitsPerPage values when possible.
• Debounce user input. If you’re building a live search box, wait 300‑500 ms after the last keystroke before issuing the request.

These habits not only protect you from throttling but also improve perceived performance for end users.

Common Pitfalls and How to Avoid Them

While the API is straightforward, developers often stumble on a few quirks:

• Timestamp confusion. The created_at_i field uses Unix seconds, not milliseconds. Forgetting this leads to off‑by‑factor‑1000 errors.
• Case‑sensitive tags. Tags must be lowercase; Story will be ignored.
• Missing fields. Not every story has a url (Ask HN posts, for instance). Always guard against null values before rendering links.

By handling these edge cases early, you’ll save debugging time later.

FAQ

Can I use the API for commercial projects?

Yes. The search‑only Algolia key is intended for public, read‑only access, even in commercial applications. Just respect the rate limits and attribute the source if you display large amounts of data.

What’s the difference between /search and /search_by_date?

/search ranks results by relevance, while /search_by_date orders them chronologically. Choose the endpoint that matches your UI—relevance for keyword‑driven queries, date for “latest stories” feeds.

Is there a way to retrieve comments for a specific story?

Yes. First fetch the story’s objectID, then query https://hn.algolia.com/api/v1/search?tags=comment,story_{objectID}. This returns all comments attached to that story.

Do I need to worry about CORS?

The API includes the proper Access-Control-Allow-Origin: * header, so browsers can call it directly from client‑side JavaScript without a proxy.