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_hnauthor_USERNAME — posts by userstory_ID — comments on story
Numeric filters:
created_at_i>TIMESTAMP — after datepoints>N — minimum pointsnum_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 insteaddeleted and dead items exist — check before displaying- Timestamps are Unix seconds, not milliseconds
- Algolia
objectID = HN item id (as string)