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)