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 с лимитом результатов, отслеживайте асинхронную задачу и читайте нормализованные пины с курсорной пагинацией.
- Подготовьте непустой текстовый запрос и выберите results_limit от 1 до 2 000.
- Отправьте query и results_limit методом POST на /v1/pinterest/search и сохраните возвращенный task_id.
- Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой.
- Читайте 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, категории, хештеги, источник и отдельные метрики как необязательные поля, а не считайте отсутствующие значения ошибками запроса.
Связанные API
Помимо 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: месячное число поисков темы, время его обновления и предложенные более узкие темы.