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」鍵中。還有一個「元資料」鍵，它提供有關搜尋的附加信息，包括找到的結果總數、搜尋處理所需的時間等。
執行評論搜尋時可以使用許多附加參數。讓我們回顧一下它們並為每個例子提供範例。
| 範圍 | 描述 | 預設 | 可接受的值 |
|---|---|---|---|
| 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 條評論怎麼辦？我們可以使用作者參數以及排序和大小參數。
搜尋所有 subreddit 並獲取用戶 /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 上共享的相關鏈接 | 開發中 |
