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
urlis null for Ask HN/Show HN text posts — usetextfield insteaddeletedanddeaditems exist — check before displaying- Timestamps are Unix seconds, not milliseconds
- Algolia
objectID= HN itemid(as string)