Pushshift.io Reddit API 是由 /r/datasets mod 团队设计和创建的，旨在帮助提供用于搜索 Reddit 评论和提交的增强功能和搜索功能。项目负责人 /u/stuck_in_the_matrix 是位于 https://files.pushshift.io 的 Reddit 评论和提交档案的维护者。
这个 RESTful API 提供了搜索 Reddit 数据的完整功能，还包括创建强大的数据聚合的功能。通过这个API，您可以快速找到您感兴趣的数据并发现有趣的相关性。
访问 Reddit 评论和提交数据库的主要方式有两种。一种是通过 https://api.pushshift.io/ 直接使用 API，另一种是通过 https://elastic.pushshift.io/ 访问后端 Elasticsearch 搜索引擎。本文档将解释这两种方法并给出有关如何有效使用 API 的示例。本文档还将探讨如何使用 API 参数来利用更有针对性的搜索。
有两个主要端点用于搜索 Reddit 上所有公开评论和提交的内容：
在下一节中，我们将探讨如何使用评论搜索端点执行更有效的搜索。
要搜索评论，请使用 https://api.pushshift.io/reddit/search/comment/ 端点。让我们从几个示例开始，然后查看使用此端点时可用的各种参数。最简单的搜索之一是仅使用 q 参数。 q 参数用于搜索特定的单词或短语。这是一个例子：
搜索最近提到“科学”一词的评论
https://api.pushshift.io/reddit/search/comment/?q=science
这将搜索评论正文中带有“科学”一词的最新评论。此搜索不区分大小写，因此无论大小写如何，它都会找到任何出现的术语“science”。 API 默认按照最近发表的评论进行排序。执行此搜索后，将返回 25 个结果。这是搜索的默认大小，可以使用 size 参数进行调整。这将在参数部分进一步详细讨论。数据以 JSON 格式返回，实际搜索结果包含在“data”键中。还有一个“元数据”键，它提供有关搜索的附加信息，包括找到的结果总数、搜索处理所需的时间等。如果请求聚合，则所有聚合数据都会在 aggs 键下返回。
执行评论搜索时可以使用许多附加参数。让我们回顾一下它们并为每个例子提供示例。
| 范围 | 描述 | 默认 | 可接受的值 |
|---|---|---|---|
| q | 搜索词。 | 不适用 | 短语的字符串/引用字符串 |
| id | 通过他们的 ID 获取具体评论 | 不适用 | 逗号分隔的 base36 id |
| 尺寸 | 返回的结果数 | 25 | 整数 <= 500 |
| 领域 | 一返回特定字段（逗号分隔） | 返回所有字段 | 字符串或逗号分隔的字符串 |
| 种类 | 按特定顺序对结果进行排序 | “描述” | “升序”、“降序” |
| 排序类型 | 按特定属性排序 | “创建_UTC” | “分数”、“评论数”、“创建时间” |
| 鸡蛋 | 返回聚合摘要 | 不适用 | [“作者”，“link_id”，“created_utc”，“subreddit”] |
| 作者 | 限制为特定作者 | 不适用 | 细绳 |
| 红迪网子版块 | 限制到特定的 Reddit 子版块 | 不适用 | 细绳 |
| 后 | 返回该日期之后的结果 | 不适用 | 纪元值或整数 +“s,m,h,d”（即 30d 表示 30 天） |
| 前 | 返回此日期之前的结果 | 不适用 | 纪元值或整数 +“s,m,h,d”（即 30d 表示 30 天） |
| 频率 | 当设置为created_utc时与aggs参数一起使用 | 不适用 | “秒”、“分钟”、“小时”、“日” |
| 元数据 | 显示有关查询的元数据 | 错误的 | “真”、“假” |
您可以使用 ids 参数直接检索评论。要通过 ID 获取一批评论，请使用以下示例：
使用基于 36 位的 id 值检索三个评论
https://api.pushshift.io/reddit/comment/search?ids=dlrezc8,dlrawgw,dlrhbkq
有相当多的参数需要查看，所以让我们首先提供一些更复杂的示例以及如何使用上面的参数。让我们继续上面的例子，并扩展我们的“科学”关键字搜索。如果我们想要搜索“科学”一词但将其限制在特定的 Reddit 子版块中该怎么办？通过使用 subreddit 参数，我们可以做到这一点：
在 subreddit /r/askscience 中搜索提及“科学”一词的最新评论
https://api.pushshift.io/reddit/search/comment/?q=science&subreddit=askscience
这将返回 25 条包含术语“science”的评论，但仅来自 /r/askscience subreddit。由于我们没有要求特定的排序方法，因此返回最新的评论（排序参数默认为“desc”）。如果我们想要 /r/askscience 的第一个评论提到“科学”这个词怎么办？我们可以使用排序和大小参数来处理这个问题。
在 subreddit /r/askscience 中搜索提及“科学”一词的最新评论
https://api.pushshift.io/reddit/search/comment/?q=science&subreddit=askscience&sort=asc&size=1
这是结果：
{
"data": [
{
"author": "MockDeath",
"author_flair_css_class": null,
"author_flair_text": null,
"body": "Knowing more would definitely help. I guess all you can do is find out if they know the basics like you said then take it from there. That COu00b2 has the carbon turned to the isotope carbon14 in the upper atmosphere by cosmic radiation. This causes a specific percentage of carbon in the atmosphere to be carbon14.nnNow we are carbon based life forms and we have to get the carbon we are built out of from some where. We get it from eating plants, and the plants get it from absorbing COu00b2 from the air. So so long as we are alive, we uptake new carbon14. So this gives you a pretty good base line for dating.nnNow to fight arguments against carbon dating you could use the example of how we can see proton collisions in the LHC for sensitivity of our equipment. Nuclear decay is very accurate in how fast it happens, this is why atomic clocks work to a much higher degree of accuracy than other methods of time keeping. Also, you might want to make a general appeal for science. Science works, that is why we have TV's, robots, particle accelerators, satellites, computers, MRI and CAT scanners, nuclear power, etc etc. Scientists are not just willy nilly making shit up, or these kinds of things wouldn't work.",
"created_utc": 1270637661,
"id": "c0nn9iq",
"link_id": "t3_bne3u",
"parent_id": "t1_c0nn5ux",
"score": 2,
"subreddit": "askscience",
"subreddit_id": "t5_2qm4e"
}
],
"metadata": {
"execution_time_milliseconds": 30.52,
"results_returned": 1,
"shards": {
"failed": 0,
"successful": 36,
"total": 36
},
"size": 1,
"sort": "asc",
"sort_type": "created_utc",
"timed_out": false,
"total_results": 134785,
"version": "v3.0"
}
}
从返回的结果中，我们可以看到，对 /r/askscience 的第一个提及“科学”的评论发生在纪元日期 1270637661，即 2010 年 4 月 7 日星期三上午 10:54:21 (GMT)。让我们快速浏览一下元数据片段。我们可以看到该搜索的执行时间约为 30 毫秒。总共搜索了36个分片，全部成功。搜索没有超时（timed_out 参数），这很好。如果您以编程方式使用 API，您可能需要检查此属性，因为某些更复杂的搜索有时可能会超时。 Total_results 值为 134,785。这告诉我们 /r/askscience 中提到“科学”一词的评论总数。由于我们没有使用 before 或 after 参数，因此这个数字代表对 /r/askscience 所做的全部评论。
让我们继续使用其他参数来突出搜索 API 的强大功能。 before 和 after 参数允许您通过为两者提供纪元时间戳来限制搜索的时间范围。然而，API 还可以理解更类似于人类的前后参数值。您也可以使用数字后跟字符 s、m、h、d（代表秒、分、小时和日）来限制时间范围。让我们来看一些例子。
如果您想在 subreddit /r/askhistorians 中搜索“Rome”，但仅限于过去 30 天，则可以使用值为 30d（30 天）的 after 参数。
在 Reddit /r/askhistorians 子版块中搜索过去 30 天内提及罗马的评论
https://api.pushshift.io/reddit/search/comment/?q=rome&subreddit=askhistorians&after=30d
如果三天前有最近的新闻报道，但我们想将搜索窗口限制在 4 天前和 2 天前之间怎么办？我们可以同时使用 before 和 after 参数来做到这一点。在下一个示例中，我们将搜索 4 到 2 天前发表的提及特朗普的评论，并按升序排序。
在所有 Reddit 子版块中搜索“特朗普”一词，并返回 2 至 4 天前发表的评论
https://api.pushshift.io/reddit/search/comment/?q=trump&after=4d&before=2d&sort=asc
假设您想要搜索最后 150 条评论，但您只需要为每条评论返回作者和正文字段。使用 fields 参数，您可以告诉 API 您想要过滤哪些信息。如果您发出大量请求并且只需要返回特定字段，这主要是为了帮助减少带宽。
以下是使用 fields 参数搜索过去 150 条提及“政府”的评论并仅返回作者和正文字段的示例：
在所有 Reddit 子版块中搜索“政府”一词，并返回仅包含正文和作者键的评论
https://api.pushshift.io/reddit/search/comment/?q=government&size=150&fields=body,author
使用上面的一个示例，在 Reddit /r/askscience 子版块中搜索第一次出现的“science”一词，我们看到该评论的作者是“MockDeath”。如果我们想获取“MockDeath”对 Reddit 的前 100 条评论怎么办？我们可以使用作者参数以及排序和大小参数。
搜索所有 subreddits 并获取用户 /u/MockDeath 发表的前 100 条评论
https://api.pushshift.io/reddit/search/comment/?author=MockDeath&sort=asc&size=100
聚合是一种为搜索提供汇总数据的强大方法。使用 aggs 参数，我们可以围绕特定参数快速创建分面，并查看数据如何随时间变化。评论搜索的 aggs 参数接受以下值：author、subreddit、reated_utc 和 link_id。我们可以使用这个参数做很多很酷的事情，所以让我们深入研究一些例子。
假设我们想了解“特朗普”一词随时间的使用频率。我们希望能够查看该学期过去 7 天内每小时发布的评论数。使用聚合和 aggs 参数，我们可以快速获取该数据。这是使用此标准的示例：
使用术语 trump 创建时间聚合，以显示过去 7 天内每小时提及 trump 的评论数
https://api.pushshift.io/reddit/search/comment/?q=trump&after=7d&aggs=created_utc&Frequency=hour&size=0
我们使用频率参数和 aggs 参数创建每小时的存储桶，以显示过去 7 天内提及特朗普的评论总数。 size 参数设置为 0，因为我们只对获取聚合数据感兴趣，而不是评论数据。聚合数据在键 aggs ->created_utc 下的响应中返回。以下是退货第一部分的片段：
{
"aggs": {
"created_utc": [
{
"doc_count": 685,
"key": 1502406000
},
{
"doc_count": 1238,
"key": 1502409600
},
{
"doc_count": 1100,
"key": 1502413200
},
doc_count 值是包含术语“特朗普”的评论总数。键值是该特定存储桶的纪元时间。在此示例中，第一个存储桶的纪元时间为 1502406000，对应于 2017 年 8 月 10 日星期四晚上 11:00:00。该键值是存储桶的开始时间，因此在本例中，2017年8月10日星期四11:00:00 PM到2017年8月10日星期四12:00之间有685条评论包含术语“特朗普”：下午 00 点。频率参数允许您每秒、每分钟、每小时、每天、每周、每月、每年创建存储桶。使用此聚合，您可以使用数据创建图表（即 Highcharts）并绘制特定术语、作者、subreddits 等评论活动的图表。这是一个极其强大的数据分析工具。
如果您不仅想了解一段时间内特定评论术语的频率，还想了解特定术语在该时间段内哪些 Reddit 子版块最受欢迎，该怎么办？以下是使用 aggs 参数来显示哪些 subreddits 对于特定术语最活跃的示例。
使用术语“特朗普”创建 Reddit 子版块聚合，以显示过去 7 天内提及特朗普的热门 Reddit 子版块
https://api.pushshift.io/reddit/search/comment/?q=trump&after=7d&aggs=subreddit&size=0
这是结果的片段：
{
"aggs": {
"subreddit": [
{
"bg_count": 66,
"doc_count": 44,
"key": "lovetrumpshaters",
"score": 0.6666666666666666
},
{
"bg_count": 20,
"doc_count": 9,
"key": "Denmark_Uncensored",
"score": 0.45
},
{
"bg_count": 51,
"doc_count": 16,
"key": "WhoRedditHatesNow",
"score": 0.3137254901960784
},
subreddit 聚合将返回该 subreddit 中提及查询术语的评论总数 (doc_count) 以及在该时间段内对该 subreddit 发表的评论总数 (bg_count)。这不仅会向您显示哪些子版块最常提到特朗普，而且还会为您提供标准化结果，以便您还可以查看该子版块的评论中包含搜索词的百分比。如果您只是简单地对最常提到搜索词“特朗普”的子版块进行排名，则结果将偏向于通常也包含最多活动的子版块。使用这种方法，您可以看到原始计数和标准化数据。
该 API 还允许对 link_id 进行聚合，这是另一种非常强大的方法，可以根据特定的搜索词查看哪些提交最受欢迎。继续上面的例子，让我们给出一个非常有帮助的场景。过去 24 小时内，有关唐纳德·特朗普 (Donald Trump) 的重大新闻报道层出不穷。您希望使用 API 根据提交内容中提及特朗普的评论数量来查看哪些提交内容与特朗普相关。我们可以再次使用 aggs 参数并将其设置为 link_id 来快速获取此信息。让我们继续看另一个例子：
显示过去 24 小时内评论中经常提及特朗普的提交内容
https://api.pushshift.io/reddit/search/comment/?q=trump&after=24h&aggs=link_id&size=0
这将在 aggs -> link_id 键下返回提交对象的数组。 doc_count 给出了每次提交的提及搜索词（“trump”）的评论总数，bg_count 给出了对该提交的评论总数。这是根据特定搜索词或短语快速查找“热门”提交内容的好方法。
该 API 还允许您创建作者聚合，以便您可以快速查看哪些作者对特定搜索词发表的评论最多。以下是使用作者聚合的示例：
显示过去 24 小时内提及“特朗普”一词的热门作者
https://api.pushshift.io/reddit/search/comment/?q=trump&after=24h&aggs=author&size=0
{
"aggs": {
"author": [
{
"doc_count": 605,
"key": "grrrrreat"
},
{
"doc_count": 329,
"key": "AutoModerator"
},
{
"doc_count": 168,
"key": "autotldr"
},
{
"doc_count": 73,
"key": "SnapshillBot"
},
作者聚合将向您显示哪些作者发表了最多包含特定查询术语的评论。从上面的例子来看，许多提到“特朗普”一词的顶级作者实际上都是机器人。
使用 aggs 参数，您可以组合多个聚合并获取特定术语的大量方面数据。使用上面的示例，我们可以将所有通话合并为一个通话，并显示过去 24 小时内提交最多的内容、每小时提及特朗普的评论频率、发布有关特朗普的热门作者以及发表评论的热门 Reddit 子版块提到特朗普。
显示过去 24 小时内“特朗普”一词的作者、提交内容、子版块和时间频率的聚合
https://api.pushshift.io/reddit/search/comment/?q=trump&after=24h&aggs=author,link_id,subreddit,created_utc&Frequency=hour&size=0
要搜索提交内容，请使用端点 https://api.pushshift.io/reddit/search/submission/ 端点。让我们从几个示例开始，然后查看使用此端点时可用的各种参数。对于简单的搜索，q 参数用于搜索特定的单词或短语。这是一个例子：
搜索提及“科学”一词的最新提交内容
https://api.pushshift.io/reddit/search/submission/?q=science
这将搜索标题或自文本中包含科学一词的最新提交内容。搜索不区分大小写，因此无论大小写如何，它都会找到任何出现的科学内容。 API 默认按照最近提交的内容进行排序。运行此搜索后，将返回 25 个结果。这是搜索的默认大小，可以使用 size 参数进行更改。这将在参数部分进一步详细讨论。数据以 JSON 格式返回，结果包含在“data”键中。
执行提交搜索时可以使用许多附加参数。现在让我们逐一回顾并为每一个提供示例。
| 范围 | 描述 | 默认 | 可接受的值 |
|---|---|---|---|
| id | 通过 ID 获取特定提交内容 | 不适用 | 逗号分隔的 base36 id |
| q | 搜索词。将搜索所有可能的字段 | 不适用 | 短语的字符串/引用字符串 |
| 问：不 | 排除搜索词。将排除这些条款 | 不适用 | 短语的字符串/引用字符串 |
| 标题 | 仅搜索标题字段 | 不适用 | 短语的字符串/引用字符串 |
| 标题：不 | 从标题中排除搜索词。将排除这些条款 | 不适用 | 短语的字符串/引用字符串 |
| 自传 | 仅搜索自文本字段 | 不适用 | 短语的字符串/引用字符串 |
| 自文：不是 | 从自文本中排除搜索词。将排除这些条款 | 不适用 | 短语的字符串/引用字符串 |
| 尺寸 | 返回的结果数 | 25 | 整数 <= 500 |
| 领域 | 一返回特定字段（逗号分隔） | 所有领域 | 字符串或逗号分隔的字符串（允许多个值） |
| 种类 | 按特定顺序对结果进行排序 | “描述” | “升序”、“降序” |
| 排序类型 | 按特定属性排序 | “创建_UTC” | “分数”、“评论数”、“创建时间” |
| 鸡蛋 | 返回聚合摘要 | 不适用 | [“作者”，“link_id”，“created_utc”，“subreddit”] |
| 作者 | 限制为特定作者 | 不适用 | 字符串或逗号分隔的字符串（允许多个值） |
| 红迪网子版块 | 限制到特定的 Reddit 子版块 | 不适用 | 字符串或逗号分隔的字符串（允许多个值） |
| 后 | 返回该日期之后的结果 | 不适用 | 纪元值或整数 +“s,m,h,d”（即 30d 表示 30 天） |
| 前 | 返回该日期之前的结果 | 不适用 | 纪元值或整数 +“s,m,h,d”（即 30d 表示 30 天） |
| 分数 | 根据分数限制结果 | 不适用 | 整数或> x或< x（即分数=>100或分数=<25） |
| 评论数 | 根据评论数量限制结果 | 不适用 | 整数或 > x 或 < x（即 num_comments=>100） |
| 18岁以上 | 限制为 nsfw 或 sfw 内容 | 两者都允许 | “真”或“假” |
| 是_视频 | 限制为视频内容 | 两者都允许 | “真”或“假” |
| 锁定 | 仅返回锁定或解锁的线程 | 两者都允许 | “真”或“假” |
| 粘着的 | 仅返回粘性或非粘性内容 | 两者都允许 | “真”或“假” |
| 剧透 | 仅排除或包含剧透 | 两者都允许 | “真”或“假” |
| 竞赛模式 | 排除或包含内容模式提交 | 两者都允许 | “真”或“假” |
| 频率 | 当设置为created_utc时与aggs参数一起使用 | 不适用 | “秒”、“分钟”、“小时”、“日” |
| 元数据 | 显示有关查询的元数据 | 错误的 | [“真”，“假”] |
当与 Reddit 的 API 一起使用时，此调用非常有用。当有大量提交且有数千条评论时，通常很难获取提交的所有评论 ID。当提交 ID 传递给该调用时，该调用将返回一个评论 ID 数组。端点是：https://api.pushshift.io/reddit/submission/comment_ids/{base36提交id}
此调用将返回一个包含评论 ID 数组的数据键。然后，您可以从此 API 或 Reddit API 检索实际评论信息。如果提交的内容相当新，最好使用 Reddit API 获取评论的最新分数。
检索提交对象的所有评论 ID
https://api.pushshift.io/reddit/submission/comment_ids/6uey5x
| 端点 | 描述 | 地位 |
|---|---|---|
| /reddit/搜索/评论/ | 搜索 Reddit 评论 | 积极的 |
| /reddit/搜索/提交/ | 搜索 Reddit 提交内容 | 积极的 |
| /reddit/submission/comment_ids/{base36-submission-id} | 检索提交对象的评论 ID | 积极的 |
| /reddit/analyze/user/{作者姓名} | 分析 Reddit 用户的活动 | 开发中 |
| /reddit/term/Frequency/{term} | 根据活动分析术语 | 开发中 |
| /reddit/搜索/全部/ | 搜索评论和提交内容 | 开发中 |
| /reddit/趋势/人物 | 了解 Reddit 上的热门人物 | 开发中 |
| /reddit/搜索/链接 | 查找 Reddit 上共享的相关链接 | 开发中 |
