hacker-news

Quick Reference

Topic	File
API endpoints	`api.md`
Search patterns	`search.md`

Core Rules

1. Two APIs Available

API	Use Case	Base URL
Official HN API	Single items, real-time	`https://hacker-news.firebaseio.com/v0`
Algolia Search	Full-text search, filters	`https://hn.algolia.com/api/v1`

2. Official API Endpoints

/topstories.json — top 500 story IDs
/newstories.json — newest 500 story IDs
/beststories.json — best stories
/askstories.json — Ask HN
/showstories.json — Show HN
/jobstories.json — job postings
/item/{id}.json — story/comment details
/user/{username}.json — user profile

3. Algolia Search Syntax

/search?query=TERM&tags=TAG&numericFilters=FILTER

Tags (combinable with AND): - story, comment, poll, job, ask_hn, show_hn - author_USERNAME — posts by user - story_ID — comments on story

Numeric filters: - created_at_i>TIMESTAMP — after date - points>N — minimum points - num_comments>N — minimum comments

4. Common Patterns

Request	Endpoint
Frontpage	Official `/topstories.json` → fetch first 30 items
Search posts	Algolia `/search?query=X&tags=story`
User's posts	Algolia `/search?tags=author_USERNAME`
Who is hiring?	Algolia `/search?query=who is hiring&tags=story,author_whoishiring`
Comments on story	Algolia `/search?tags=comment,story_ID`
This week's top	Algolia `/search?tags=story&numericFilters=created_at_i>WEEK_TS`

5. Response Handling

Official API returns IDs → batch fetch items (parallelize)
Algolia returns full objects with hits[] array
Story object: id, title, url, score, by, time, descendants (comment count)
Comment object: id, text, by, parent, time

6. Rate Limits

Official API: No auth required, generous limits
Algolia: 10,000 requests/hour (no key needed)
Always paginate large results (page=N, hitsPerPage=N)

7. Gotchas

url is null for Ask HN/Show HN text posts — use text field instead
deleted and dead items exist — check before displaying
Timestamps are Unix seconds, not milliseconds
Algolia objectID = HN item id (as string)