A Practical Guide to the Hacker News API for Developers

Choosing The Right Hacker News API For Your Project

Hacker News API Versions Compared

Accessing Real-Time Data with Firebase API Endpoints

Fetching Story IDs

• /v0/topstories.json: The current top stories on the front page.

• /v0/newstories.json: The firehose of the most recently submitted stories.

• /v0/beststories.json: A curated list of stories algorithmically deemed "best."

curl 'https://hacker-news.firebaseio.com/v0/topstories.json'

fetch('https://hacker-news.firebaseio.com/v0/topstories.json')
  .then(response => response.json())
  .then(data => console.log(data.slice(0, 10))); // Logs the first 10 top story IDs

Retrieving Item Details

Mastering Search and Filter Parameters

• query: The keyword or phrase to search for (e.g., query=AI).

• tags: Filter by item type, such as story, comment, or ask_hn.

• numericFilters: Apply filters based on numerical values like score or creation date (e.g., points>100 or created_at_i > [timestamp]).

Advanced Query Examples in Python

import requests
import time

# Calculate the timestamp for 30 days ago
thirty_days_ago = int(time.time()) - (30 * 24 * 60 * 60)

# Define the API endpoint and parameters
url = "http://hn.algolia.com/api/v1/search"
params = {
    "query": "AI",
    "tags": "story",
    "numericFilters": f"created_at_i>{thirty_days_ago},points>50"
}

# Make the request
response = requests.get(url, params=params)
data = response.json()

# Print the titles of the top hits
for hit in data.get("hits", []):
    print(f"- {hit.get('title')}")

Practical Code for Common Use Cases

Fetching and Displaying the Top 10 Stories

// Function to fetch details for a single item
async function getItemDetails(id) {
  const response = await fetch(`https://hacker-news.firebaseio.com/v0/item/${id}.json`);
  return response.json();
}

// Main function to get the top 10 stories
async function getTopTenStories() {
  try {
    // 1. Fetch the list of top story IDs
    const response = await fetch('https://hacker-news.firebaseio.com/v0/topstories.json');
    const topStoryIds = await response.json();

    // 2. Get the first 10 IDs and fetch their details concurrently
    const topTenIds = topStoryIds.slice(0, 10);
    const storyPromises = topTenIds.map(id => getItemDetails(id));
    const stories = await Promise.all(storyPromises);

    // 3. Display the titles and scores
    console.log("Hacker News Top 10 Stories:");
    stories.forEach(story => {
      if (story) {
        console.log(`- ${story.title} (Score: ${story.score})`);
      }
    });
  } catch (error) {
    console.error("Failed to fetch stories:", error);
  }
}

getTopTenStories();

Creating a Keyword-Based Daily Digest

import requests
import time

# Calculate the timestamp for 24 hours ago
one_day_ago = int(time.time()) - (24 * 60 * 60)

# Define Algolia API endpoint and parameters
URL = "http://hn.algolia.com/api/v1/search"
PARAMS = {
    "query": "Python",
    "tags": "story",
    "numericFilters": f"created_at_i>{one_day_ago},points>5"
}

# Make the API request
try:
    response = requests.get(URL, params=PARAMS)
    response.raise_for_status()  # Raise an exception for bad status codes
    data = response.json()

    print("New stories about 'Python' in the last 24 hours:")
    for hit in data.get("hits", []):
        print(f"- {hit.get('title')} (URL: {hit.get('url')})")

except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Managing Rate Limits and Pagination

Navigating Firebase API Limitations

• Batch Your Requests: Fetch the full list of IDs, then loop through it, fetching details for 10-20 items at a time.

• Introduce Delays: Implement a small delay between batches to avoid overwhelming the server.

• Prioritize Necessary Data: For features like an infinite scroll feed, fetch the next batch only when the user approaches the end of the current content.

Paginating Results with Algolia

• page: Specifies the desired page of results (e.g., page=0 for the first page).

• hitsPerPage: Defines the number of results per page, up to a maximum of 1,000.

Optimizing Performance with Caching and Error Handling

Implementing Caching Strategies

Graceful Error Handling

# Python example for handling null responses
import requests

def get_item(item_id):
    url = f"https://hacker-news.firebaseio.com/v0/item/{item_id}.json"
    response = requests.get(url)

    if response.status_code == 200:
        data = response.json()
        if data is None:
            print(f"Warning: Item {item_id} not found or has been deleted.")
            return None
        return data
    else:
        print(f"Error: API returned status {response.status_code}")
        return None

# Test with a potentially invalid ID
item = get_item(999999999)
if item:
    print(item['title'])

A Few Common Questions (The Hacker News API FAQ)

Are There Any Rate Limits?

Can I Post Stories or Comments with the API?

Which API Should I Use? Real-Time vs. Historical

• For real-time data, such as current top stories or new comments, use the official Firebase API. It is designed for live updates.

• For historical data, use the Algolia API. It is built for searching, filtering by date, and analyzing trends over time.