Quick Reference
| Topic | File |
|---|
| API endpoints | INLINECODE0 |
| Search patterns |
search.md |
Core Rules
1. Two APIs Available
| API | Use Case | Base URL |
|---|
| Official HN API | Single items, real-time | INLINECODE2 |
| Algolia Search |
Full-text search, filters |
https://hn.algolia.com/api/v1 |
2. Official API Endpoints
- -
/topstories.json — top 500 story IDs - INLINECODE5 — newest 500 story IDs
- INLINECODE6 — best stories
- INLINECODE7 — Ask HN
- INLINECODE8 — Show HN
- INLINECODE9 — job postings
- INLINECODE10 — story/comment details
- INLINECODE11 — user profile
3. Algolia Search Syntax
CODEBLOCK0
Tags (combinable with AND):
- -
story, comment, poll, job, ask_hn, INLINECODE17 - INLINECODE18 — posts by user
- INLINECODE19 — comments on story
Numeric filters:
- -
created_at_i>TIMESTAMP — after date - INLINECODE21 — minimum points
- INLINECODE22 — 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, INLINECODE41
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 - INLINECODE46 and
dead items exist — check before displaying - Timestamps are Unix seconds, not milliseconds
- Algolia
objectID = HN item id (as string)
快速参考
search.md |
核心规则
1. 两个可用的 API
| API | 使用场景 | 基础 URL |
|---|
| 官方 HN API | 单个项目、实时数据 | https://hacker-news.firebaseio.com/v0 |
| Algolia 搜索 |
全文搜索、筛选 | https://hn.algolia.com/api/v1 |
2. 官方 API 端点
- - /topstories.json — 前 500 个故事 ID
- /newstories.json — 最新 500 个故事 ID
- /beststories.json — 最佳故事
- /askstories.json — Ask HN
- /showstories.json — Show HN
- /jobstories.json — 招聘信息
- /item/{id}.json — 故事/评论详情
- /user/{username}.json — 用户资料
3. Algolia 搜索语法
/search?query=关键词&tags=标签&numericFilters=筛选条件
标签（可用 AND 组合）：
- - story、comment、poll、job、askhn、showhn
- author用户名 — 该用户的帖子
- storyID — 该故事下的评论
数值筛选：
- - createdati>时间戳 — 指定日期之后
- points>N — 最低分数
- num_comments>N — 最低评论数
4. 常见模式
| 请求 | 端点 |
|---|
| 首页 | 官方 /topstories.json → 获取前 30 个项目 |
| 搜索帖子 |
Algolia /search?query=X&tags=story |
| 用户的帖子 | Algolia /search?tags=author_用户名 |
| 谁在招聘？ | Algolia /search?query=who is hiring&tags=story,author_whoishiring |
| 故事下的评论 | Algolia /search?tags=comment,story_ID |
| 本周热门 | Algolia /search?tags=story&numericFilters=created
ati>本周时间戳 |
5. 响应处理
- - 官方 API 返回 ID → 批量获取项目（并行处理）
- Algolia 返回包含 hits[] 数组的完整对象
- 故事对象：id、title、url、score、by、time、descendants（评论数）
- 评论对象：id、text、by、parent、time
6. 速率限制
- - 官方 API：无需认证，限制宽松
- Algolia：每小时 10,000 次请求（无需密钥）
- 大量结果请始终分页（page=N、hitsPerPage=N）
7. 注意事项
- - Ask HN/Show HN 文本帖子的 url 为 null — 请改用 text 字段
- 存在 deleted 和 dead 项目 — 显示前需检查
- 时间戳为 Unix 秒数，而非毫秒
- Algolia 的 objectID = HN 项目的 id（字符串格式）
