API Reddit pushshift.io был разработан и создан командой модификаторов /r/datasets, чтобы обеспечить расширенную функциональность и возможности поиска для поиска комментариев и материалов Reddit. Руководитель проекта, /u/stuck_in_the_matrix, занимается сопровождением архивов комментариев и материалов Reddit, расположенных по адресу https://files.pushshift.io.
Этот RESTful API предоставляет полную функциональность для поиска данных Reddit, а также включает возможность создания мощных агрегатов данных. С помощью этого API вы сможете быстро найти интересующие вас данные и найти интересные корреляции.
Существует два основных способа доступа к базе данных комментариев и материалов Reddit. Один из них — использование API напрямую через https://api.pushshift.io/, а другой — доступ к внутренней поисковой системе Elasticsearch через https://elastic.pushshift.io/. В этом документе будут объяснены оба подхода и даны примеры эффективного использования API. В этом документе также будет рассмотрено использование параметров API для более целенаправленного поиска.
Для поиска всех общедоступных комментариев и материалов на Reddit используются две основные конечные точки:
В следующем разделе мы рассмотрим, как выполнять более эффективный поиск с помощью конечной точки поиска комментариев.
Для поиска комментариев используйте конечную точку https://api.pushshift.io/reddit/search/comment/. Давайте начнем с нескольких примеров, а затем рассмотрим различные параметры, доступные при использовании этой конечной точки. Один из самых простых поисков — использовать только параметр q. Параметр q используется для поиска определенного слова или фразы. Вот пример:
Найдите самые последние комментарии, в которых упоминается слово «наука».
https://api.pushshift.io/reddit/search/comment/?q=science
Будет выполнен поиск самых последних комментариев с термином «наука» в теле комментария. Этот поиск не чувствителен к регистру, поэтому он найдет любое вхождение термина «наука» независимо от регистра. По умолчанию API сортирует в первую очередь по недавно оставленным комментариям. После выполнения этого поиска возвращается 25 результатов. Это размер по умолчанию для поиска, и его можно настроить с помощью параметра размера. Более подробно это будет обсуждаться в разделе параметров. Данные возвращаются в формате JSON, а фактические результаты поиска включаются в ключ «данные». Существует также ключ «метаданных», который предоставляет дополнительную информацию о поиске, включая общее количество найденных результатов, время, необходимое для обработки поиска и т. д. Если запрашиваются агрегации, все агрегированные данные возвращаются под ключом aggs.
Существует множество дополнительных параметров, которые можно использовать при поиске комментариев. Давайте рассмотрим их и приведем примеры для каждого.
| Параметр | Описание | По умолчанию | Принятые значения |
|---|---|---|---|
| д | Поисковый термин. | Н/Д | Строка/строка в кавычках для фраз |
| идентификаторы | Получайте конкретные комментарии через их идентификаторы | Н/Д | Идентификаторы base36, разделенные запятыми |
| размер | Количество результатов для возврата | 25 | Целое число <= 500 |
| поля | Определенные поля с одним возвратом (разделенные запятыми) | Все поля возвращены | строка или строка, разделенная запятыми |
| сортировать | Сортировка результатов в определенном порядке | "деска" | «по возрастанию», «по убыванию» |
| сорт_тип | Сортировка по определенному атрибуту | "созданный_utc" | "оценка", "num_comments", "create_utc" |
| аггс | Сводная информация по возврату агрегации | Н/Д | ["автор", "link_id", "create_utc", "субреддит"] |
| автор | Ограничить конкретным автором | Н/Д | Нить |
| субреддит | Ограничить определенный субреддит | Н/Д | Нить |
| после | Вернуть результаты после этой даты | Н/Д | Значение эпохи или целое число + «s,m,h,d» (т. е. 30d в течение 30 дней). |
| до | Вернуть результаты до этой даты | Н/Д | Значение эпохи или целое число + «s,m,h,d» (т. е. 30d в течение 30 дней) |
| частота | Используется с параметром aggs, если установлено значение Create_utc. | Н/Д | «секунда», «минута», «час», «день» |
| метаданные | отображать метаданные о запросе | ЛОЖЬ | «правда», «ложь» |
Вы можете получить комментарии напрямую, используя параметр ids. Чтобы получить пакет комментариев по их идентификатору, используйте следующий пример:
Получить три комментария, используя их значения идентификаторов по основанию 36.
https://api.pushshift.io/reddit/comment/search?ids=dlrezc8,dlrawgw,dlrhbkq
Необходимо рассмотреть довольно много параметров, поэтому давайте начнем с более сложных примеров и того, как использовать приведенные выше параметры. Давайте продолжим предыдущий пример и расширим наш поиск по ключевым словам «наука». Что, если мы захотим найти термин «наука», но ограничим его конкретным субреддитом? Используя параметр subreddit, мы можем сделать это:
Найдите самые последние комментарии, в которых упоминается слово «наука», в субреддите /r/askscience.
https://api.pushshift.io/reddit/search/comment/?q=science&subreddit=askscience
Это вернет 25 комментариев, содержащих термин «наука», но только из субреддита /r/askscience. Поскольку мы не запрашивали конкретный метод сортировки, возвращаются самые последние комментарии (параметр сортировки по умолчанию имеет значение «desc»). Что, если бы мы хотели, чтобы в /r/askscience был первый комментарий, в котором упоминалось бы слово «наука»? Чтобы справиться с этим, мы могли бы использовать параметры сортировки и размера.
Найдите самые последние комментарии, в которых упоминается слово «наука», в субреддите /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, что соответствует среде, 7 апреля 2010 г., 10:54:21 (GMT). Давайте быстро пробежимся по частям метаданных. Мы видим, что время выполнения этого поиска составило около 30 миллисекунд. Всего было исследовано 36 осколков, и все они увенчались успехом. Тайм-аут поиска не истек (параметр timed_out), и это хорошо. Это атрибут, который вы, возможно, захотите проверить, если вы используете API программно, поскольку некоторые более сложные поисковые запросы иногда могут истечь. Значение total_results — 134 785. Это говорит нам об общем количестве комментариев в /r/askscience, в которых упоминается слово наука. Поскольку мы не использовали параметры «до» и «после», это число представляет собой все комментарии, сделанные в /r/askscience.
Давайте продолжим использовать дополнительные параметры, чтобы подчеркнуть возможности API поиска. Параметры «до» и «после» позволяют ограничить временные рамки поиска, задав для обоих временную метку эпохи. Однако API также понимает более человеческие значения для параметров «до» и «после». Вы также можете использовать число, за которым следуют символы s,m,h,d (которые обозначают секунду, минуту, час и день), чтобы также ограничить временной интервал. Давайте рассмотрим несколько примеров.
Если вы хотите выполнить поиск по запросу «Рим» в субреддите /r/askhistorians, но ограничите его только последними 30 днями, вы можете использовать параметр after со значением 30d (30 дней).
Найдите в субреддите /r/askhistorians комментарии с упоминанием Рима за последние 30 дней.
https://api.pushshift.io/reddit/search/comment/?q=rome&subreddit=askhistorians&after=30d
Что, если недавно появилась новость три дня назад, но мы хотим ограничить окно поиска периодом от 4 до 2 дней назад? Для этого мы могли бы использовать оба параметра: before и after. В следующем примере мы будем искать комментарии с упоминанием Трампа, сделанные 4–2 дня назад, и сортировать их по возрастанию.
Выполните поиск во всех субреддитах по слову «Трамп» и верните комментарии, сделанные 2–4 дня назад.
https://api.pushshift.io/reddit/search/comment/?q=trump&after=4d&before=2d&sort=asc
Допустим, вы хотите выполнить поиск по последним 150 комментариям, но вам нужно, чтобы для каждого комментария возвращались только поля автора и тела. Используя параметр полей, вы можете указать API, какие фрагменты информации вы хотите фильтровать. Это в первую очередь помогает уменьшить пропускную способность, если вы делаете много запросов и вам нужны только определенные поля.
Вот пример использования параметра полей для поиска последних 150 комментариев, в которых упоминается слово «правительство», и возврата только полей автора и тела:
Выполняйте поиск во всех субреддитах по слову «правительство» и возвращайте комментарии только с текстом и ключами автора.
https://api.pushshift.io/reddit/search/comment/?q=government&size=150&fields=body,автор
Используя один из приведенных выше примеров поиска первого появления слова «наука» в субреддите /r/askscience, мы увидели, что автором комментария был «MockDeath». Что, если мы хотим получить первые 100 комментариев, которые «MockDeath» оставил на Reddit? Мы можем использовать параметр автора вместе с параметрами сортировки и размера.
Выполните поиск по всем субреддитам и получите первые 100 комментариев, когда-либо оставленных пользователем /u/MockDeath.
https://api.pushshift.io/reddit/search/comment/?author=MockDeath&sort=asc&size=100
Агрегации — это мощный метод предоставления сводных данных для поиска. Используя параметр aggs, мы можем быстро создавать фасеты вокруг определенных параметров и видеть, как данные изменяются с течением времени. Параметр aggs для поиска комментариев принимает следующие значения: автор, субреддит, reated_utc и link_id. Используя этот параметр, мы можем сделать много интересных вещей, поэтому давайте углубимся в несколько примеров.
Допустим, мы хотели увидеть частоту использования термина «Трамп» с течением времени. Мы хотели бы видеть, сколько комментариев было оставлено в час за последние 7 дней для этого термина. Используя агрегаты и параметр aggs, мы можем быстро получить эти данные. Вот пример использования этого критерия:
Создайте агрегацию времени, используя термин «Трамп», чтобы показать количество комментариев, упоминающих Трампа, каждый час за последние 7 дней.
https://api.pushshift.io/reddit/search/comment/?q=trump&after=7d&aggs=created_utc& Frequency=hour&size=0
Мы использовали параметр частоты вместе с параметром aggs для создания почасовых сегментов, чтобы показать общее количество комментариев с упоминанием Трампа за последние 7 дней. Параметр size был установлен на 0, поскольку нас интересуют только данные агрегирования, а не данные комментариев. Данные агрегирования возвращаются в ответе по ключу aggs -> созданный_utc. Вот фрагмент первой части возврата:
{
"aggs": {
"created_utc": [
{
"doc_count": 685,
"key": 1502406000
},
{
"doc_count": 1238,
"key": 1502409600
},
{
"doc_count": 1100,
"key": 1502413200
},
Значение doc_count — это общее количество комментариев, содержащих термин «козырь». Ключевое значение — это время эпохи для этого конкретного сегмента. В этом примере первый сегмент имеет время эпохи 1502406000, что соответствует четвергу, 10 августа 2017 г., 23:00:00. Это ключевое значение является временем начала сегмента, поэтому в этом примере 685 комментариев содержат термин «козырь» между временем четверга, 10 августа 2017 г., 23:00:00, и четвергом, 10 августа 2017 г., 12:00: 00 вечера. Параметр частоты позволяет создавать сегменты в секунду, минуту, час, день, неделю, месяц, год. Используя это агрегирование, вы можете использовать данные для создания диаграммы (например, Highcharts) и графиков активности комментариев для определенных терминов, авторов, субреддитов и т. д. Это чрезвычайно мощный инструмент анализа данных.
Что, если вы хотите не только узнать частоту появления определенных терминов в комментариях с течением времени, но и посмотреть, какие субреддиты были наиболее популярны для данного термина за этот период времени? Вот пример использования параметров aggs, чтобы показать, какие субреддиты имели наибольшую активность для определенного термина.
Создайте агрегацию субреддитов, используя термин «Трамп», чтобы отобразить самые популярные субреддиты, упоминающие Трампа, за последние 7 дней.
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
},
Агрегация субреддита вернет общее количество комментариев в этом субреддите, в которых упоминается термин запроса (doc_count), а также общее количество комментариев, сделанных в этом субреддите за этот период времени (bg_count). Это не только покажет вам, какие субреддиты упоминают Трампа чаще всего, но также даст вам нормализованные результаты, так что вы также сможете увидеть, какой процент комментариев этого субреддита содержал поисковый запрос. Если бы вы просто ранжировали субреддиты, по которым чаще всего упоминался поисковый запрос «трамп», результаты были бы смещены в сторону субреддитов, которые также содержат наибольшую активность в целом. Используя этот подход, вы можете видеть как необработанные данные, так и нормализованные данные.
API также позволяет выполнять агрегацию по link_id, что является еще одним очень мощным методом определения того, какие материалы являются наиболее популярными на основе определенного поискового запроса. Продолжая приведенные выше примеры, давайте приведем сценарий, в котором это будет чрезвычайно полезно. За последние 24 часа появилось множество громких историй, касающихся Дональда Трампа. Вы хотели бы использовать 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 показывает общее количество комментариев для каждой публикации, в которых упоминается поисковый запрос («козырь»), а 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 часа, частоту комментариев в час с упоминанием Трампа, самых популярных авторов, публикующих сообщения о Трампе, и самые популярные субреддиты, на которых были оставлены комментарии. упоминание Трампа.
Показать совокупные данные по авторам, материалам, субреддитам и частоте использования термина «Трамп» за последние 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/endpoint. Давайте начнем с нескольких примеров, а затем рассмотрим различные параметры, доступные при использовании этой конечной точки. При простом поиске параметр q используется для поиска определенного слова или фразы. Вот пример:
Найдите последние материалы, в которых упоминается слово «наука».
https://api.pushshift.io/reddit/search/submission/?q=science
При этом будут найдены самые последние материалы, содержащие слово наука в заголовке или внутреннем тексте. Поиск не чувствителен к регистру, поэтому он найдет любое научное явление независимо от капитализации. По умолчанию API сначала сортирует самые последние отправленные материалы. После запуска этого поиска возвращается 25 результатов. Это размер по умолчанию для поиска, и его можно изменить с помощью параметра размера. Более подробно это будет обсуждаться в разделе параметров. Данные возвращаются в формате JSON, а результаты включаются в ключ «данные».
Существует множество дополнительных параметров, которые можно использовать при выполнении поиска материалов. Давайте теперь рассмотрим каждый из них и приведем примеры для каждого.
| Параметр | Описание | По умолчанию | Принятые значения |
|---|---|---|---|
| идентификаторы | Получайте конкретные материалы по их идентификаторам | Н/Д | Идентификаторы base36, разделенные запятыми |
| д | Поисковый термин. Будет искать ВСЕ возможные поля | Н/Д | Строка/строка в кавычках для фраз |
| вопрос: нет | Исключить поисковый запрос. Исключим эти условия | Н/Д | Строка/строка в кавычках для фраз |
| заголовок | Поиск только в поле заголовка | Н/Д | Строка/строка в кавычках для фраз |
| Название: нет | Исключить поисковый запрос из заголовка. Исключим эти условия | Н/Д | Строка/строка в кавычках для фраз |
| автотекст | Поиск только в поле автотекста | Н/Д | Строка/строка в кавычках для фраз |
| автотекст: нет | Исключить поисковый запрос из внутреннего текста. Исключим эти условия | Н/Д | Строка/строка в кавычках для фраз |
| размер | Количество результатов для возврата | 25 | Целое число <= 500 |
| поля | Определенные поля с одним возвратом (разделенные запятыми) | Все поля | Строка или строка, разделенная запятыми (допускается несколько значений). |
| сортировать | Сортировка результатов в определенном порядке | "деска" | «по возрастанию», «по убыванию» |
| сорт_тип | Сортировка по определенному атрибуту | "созданный_utc" | "оценка", "num_comments", "create_utc" |
| аггс | Сводная информация по возврату агрегации | Н/Д | ["автор", "link_id", "create_utc", "субреддит"] |
| автор | Ограничить конкретным автором | Н/Д | Строка или строка, разделенная запятыми (допускается несколько значений). |
| субреддит | Ограничить определенный субреддит | Н/Д | Строка или строка, разделенная запятыми (допускается несколько значений). |
| после | Вернуть результаты после этой даты | Н/Д | Значение эпохи или целое число + «s,m,h,d» (т. е. 30d в течение 30 дней) |
| до | Вернуть результаты до этой даты | Н/Д | Значение эпохи или целое число + «s,m,h,d» (т. е. 30d в течение 30 дней). |
| счет | Ограничить результаты на основе оценки | Н/Д | Целое число или > x или < x (т. е. оценка=>100 или оценка=<25) |
| num_comments | Ограничить результаты по количеству комментариев | Н/Д | Целое число или > x или < x (т. е. num_comments=>100) |
| старше_18 | Ограничить содержимым nsfw или sfw | оба разрешены | «правда» или «ложь» |
| is_video | Ограничить видеоконтентом | оба разрешены | «правда» или «ложь» |
| заперто | Возвращать только заблокированные или разблокированные темы | оба разрешены | «правда» или «ложь» |
| липкий | Возвращать только прикрепленный или неприкрепленный контент | оба разрешены | «правда» или «ложь» |
| спойлер | Исключить или включить только спойлеры | оба разрешены | «правда» или «ложь» |
| конкурсный_режим | Исключение или включение отправки в режиме контента | оба разрешены | «правда» или «ложь» |
| частота | Используется с параметром aggs, если установлено значение Create_utc. | Н/Д | «секунда», «минута», «час», «день» |
| метаданные | отображать метаданные о запросе | ЛОЖЬ | ["правда", "ложь"] |
Этот вызов очень полезен при использовании вместе с API Reddit. Когда есть большие материалы с тысячами комментариев, часто бывает сложно получить все идентификаторы комментариев для отправки. Этот вызов вернет массив идентификаторов комментариев, когда ему будет передан идентификатор отправки. Конечная точка: https://api.pushshift.io/reddit/submission/comment_ids/{идентификатор отправки base36}.
Этот вызов вернет ключ данных с массивом идентификаторов комментариев. Затем вы можете получить фактическую информацию о комментариях из этого API или API Reddit. Если публикация довольно новая, лучше использовать API Reddit, чтобы получить самую актуальную оценку комментариев.
Получить все идентификаторы комментариев для объекта отправки
https://api.pushshift.io/reddit/submission/comment_ids/6uey5x
| Конечная точка | Описание | Статус |
|---|---|---|
| /reddit/поиск/комментарий/ | Поиск комментариев Reddit | Активный |
| /reddit/поиск/отправка/ | Поиск материалов Reddit | Активный |
| /reddit/submission/comment_ids/{base36-submission-id} | Получить идентификаторы комментариев для объекта отправки | Активный |
| /reddit/analyze/user/{имя автора} | Анализируйте активность пользователя Reddit | В разработке |
| /reddit/term/частота/{термин} | Анализ термина по активности | В разработке |
| /reddit/поиск/все/ | Поиск как по комментариям, так и по материалам | В разработке |
| /reddit/тренды/люди | Узнайте, кто в тренде на Reddit | В разработке |
| /reddit/поиск/ссылки | Найдите соответствующие ссылки, которыми делятся на Reddit | В разработке |
