pinterest/
search

Ищите публичные пины Pinterest по текстовому запросу с лимитом результатов и получайте нормализованный контент, данные автора, медиа, таксономию и видимую вовлеченность.

Pinterest Search API

Текстовый запрос на входе
1–2 000 запрошенных результатов
Нормализованные публичные пины
0,6 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

Pinterest Search

Результаты Pinterest Search — это публичные пины, соответствующие текстовому запросу, с заголовками, описаниями, данными автора, ссылками на медиа, категориями, хештегами, метками времени и видимой вовлеченностью. Эти записи помогают находить темы, исследовать визуальные тренды, анализировать контекст авторов и сравнивать контент по запросам.

Возможности Pinterest Search API

  • Поиск пинов по запросуПринимает один непустой текстовый запрос и results_limit от 1 до 2 000, чтобы запросить ограниченную выборку публичных записей пинов.
  • Нормализованные записи пинов, авторов и медиаВозвращает ID пинов, URL, заголовки, текст, публичные поля автора и ссылки на изображения или видео в единой структуре результата.
  • Таксономия и видимые сигналыСохраняет доступные категории, хештеги, тип пина, метаданные источника, видимое число лайков, комментариев и подписчиков автора, время публикации, время сбора и переданный запрос.

Параметры Pinterest Search API

ПараметрыОбязательныйОписание
queryОбязательныйОбязательный непустой текстовый запрос для поиска публичных пинов Pinterest; начальные и конечные пробелы удаляются перед отправкой.
results_limitНеобязательныйМаксимальное число пинов, запрашиваемых по запросу; по умолчанию 100, допускаются целые числа от 1 до 2 000.

Как использовать Pinterest Search API

Отправьте текстовый запрос Pinterest с лимитом результатов, отслеживайте асинхронную задачу и читайте нормализованные пины с курсорной пагинацией.

  1. Подготовьте непустой текстовый запрос и выберите results_limit от 1 до 2 000.
  2. Отправьте query и results_limit методом POST на /v1/pinterest/search и сохраните возвращенный task_id.
  3. Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой.
  4. Читайте data.results.items и запрашивайте возвращенный next_cursor, пока has_more равно true.
curl -X POST "https://api.socq.ai/v1/pinterest/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"home office ideas","results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Сценарии использования Pinterest Search API

  • Тематические датасеты пинов: Используйте заданный запрос вместе с ID пинов, исходными URL, заголовками, текстом, ссылками на медиа и discovery_input, чтобы собрать отслеживаемую тематическую коллекцию.
  • Исследование визуала и таксономии: Сравнивайте изображения или видео, post_type, категории, хештеги, заголовки и описания, чтобы изучить форматы и темы в результатах запроса.
  • Сравнение авторов и видимых сигналов: Объединяйте публичные поля автора с числом лайков, комментариев и подписчиков, а также collected_at, чтобы сравнивать наблюдаемый контекст результатов между сборами по запросам.

Практические советы по Pinterest Search API

  • Отправляйте непустой query без случайных пробелов по краям и держите results_limit в диапазоне от 1 до 2 000, чтобы пройти проверку входных данных.
  • Переходите по next_cursor, пока has_more не станет false, если сохраненных результатов больше, чем помещается на первой странице ответа из 50 элементов.
  • Сохраняйте extra.discovery_input и collected_at, чтобы каждый пин оставался привязан к переданному ключевому слову и времени наблюдения.
  • Обрабатывайте заголовок, текст, данные автора, медиа, created_at, категории, хештеги, источник и отдельные метрики как необязательные поля, а не считайте отсутствующие значения ошибками запроса.

Помимо Pinterest Search API, используйте эти API, когда нужен другой тип публичных данных Pinterest.

  • Pinterest Pins API — Преобразуйте URL публичных пинов в нормализованный контент, автора, медиа, таксономию, метки времени и видимые метрики.
  • Pinterest User Pins API — Находите публичные пины по URL профилей с лимитом на профиль: нормализованный контент, автор, медиа, метки времени и видимые метрики.
  • Pinterest Profiles API — Собирайте по URL профилей публичные данные аккаунта, описание, изображение, сайт, видимые счетчики и контекст сбора.
  • Pinterest User Boards API — Получайте доски профилей Pinterest по URL профилей: названия, описания, обложки, даты создания и число пинов, подписчиков, разделов и соавторов.
  • Pinterest Board Pins API — Собирайте пины доски Pinterest по ее URL в порядке доски: текст пина, сохранивший аккаунт, изображения в полном размере и ссылки на пины.
  • Pinterest Topic API — Читайте страницы идей Pinterest по URL: месячное число поисков темы, время его обновления и предложенные более узкие темы.

Другие платформы

Объединяйте данные Pinterest с публичными данными других поддерживаемых соцсетей.

Pinterest Search API — FAQ

Pinterest Search API находит публичные записи пинов по непустому текстовому запросу и необязательному лимиту результатов. Он возвращает нормализованные идентификаторы пинов, контент, авторов, медиа, таксономию, метки времени и видимую вовлеченность.

Эндпоинт принимает только query и results_limit. Параметров фильтрации по сортировке, дате, языку, доске или типу результата нет.

Каждый нормализованный результат — это публичный пин, у которого resource равен search, а type равен pin. Профили, доски, товары и подсказки не выделяются в этом ответе в отдельные типы результатов.

Записи могут содержать ID пина, URL, заголовок, текст, публичные данные автора, ссылки на изображения или видео, видимое число лайков, комментариев и подписчиков, created_at, collected_at, а также поля таксономии, источника и поиска в extra. Необязательные значения источника могут быть null или пустыми.

results_limit по умолчанию равен 100 и принимает целые числа от 1 до 2 000 как запрошенный максимум для запроса. Ответы успешной задачи по умолчанию возвращают сохраненные результаты страницами по 50; переходите по next_cursor, пока has_more равно true, а при прямом обращении к эндпоинту задач задавайте лимит страницы от 1 до 500.

Каждая возвращенная запись пина стоит 0,6 кредита SocQ. Предварительная оценка использует results_limit или 100, если он не указан, а пустой набор результатов не оплачивается.