facebook-marketplace/
search

Ищите публичные объявления Facebook Marketplace по ключевому слову и координатам: заголовки, цены, местоположения, изображения, поля статуса и исходные URL в виде нормализованных записей.

Facebook Marketplace Search API

Ключевое слово и координаты
Географические фильтры и фильтры объявлений
1–2 000 результатов на запрос
Нормализованные публичные объявления
0,7 кредита за результат
Готово
Готово

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

README

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

Facebook Marketplace Search

Объявления в поиске Facebook Marketplace — это публичные предложения локальной торговли с заголовками, ценами, местоположениями, изображениями, данными продавца, вариантами доставки и признаками доступности. Эти поля помогают исследовать локальный ассортимент, сравнивать запрашиваемые цены, анализировать категории и регулярно снимать срезы рынка.

Возможности Facebook Marketplace Search API

  • Поиск объявлений по ключевому слову и географииОбъединяет один непустой запрос с обязательными координатами широты и долготы, а затем сужает выборку публичных объявлений по радиусу, цене, сортировке, доставке, состоянию, дате и доступности.
  • Структурированные записи объявлений и ценВозвращает ID объявлений, публичные URL, заголовки, доступные описания, суммы цен, валюты, форматированные цены и зачеркнутые цены в единой структуре.
  • Местоположение, медиафайлы и классификацияСохраняет с каждым результатом доступные метки местоположения, город и штат, ссылки на изображения, ID категорий, характеристики, типы доставки и текст с датой публикации.
  • Глубина данных поисковой карточкиСохраняет открытые поля продавца и признаки live, pending, sold, доставки, мгновенной покупки и сообщений, оставляя пустыми детали карточки, которых нет в публичном результате.

Параметры Facebook Marketplace Search API

ПараметрыОбязательныйОписание
queryОбязательныйОбязательное непустое ключевое слово для поиска объявлений; начальные и конечные пробелы удаляются перед отправкой.
latitudeОбязательныйОбязательная широта центра поиска — число от -90 до 90.
longitudeОбязательныйОбязательная долгота центра поиска — число от -180 до 180.
results_limitНеобязательныйМаксимальное число объявлений, сохраняемых по всем страницам поиска; по умолчанию 100, допускаются целые числа от 1 до 2 000.
radius_kmНеобязательныйНеобязательный радиус поиска в километрах; если указан, должен быть числом больше 0.
min_priceНеобязательныйНеобязательная минимальная цена объявления; должна быть неотрицательной и не может превышать max_price.
max_priceНеобязательныйНеобязательная максимальная цена объявления; должна быть неотрицательной и не может быть меньше min_price.
sort_byНеобязательныйНеобязательный порядок сортировки: suggested, distance_ascend, creation_time_descend, price_ascend или price_descend.
delivery_methodНеобязательныйНеобязательный фильтр доставки: all, local_pickup или shipping.
conditionНеобязательныйНеобязательный фильтр состояния: new, used_like_new, used_good или used_fair.
date_listedНеобязательныйНеобязательный фильтр по давности объявления: all, 1, 7, 30, last_24_hours, last_7_days или last_30_days.
availabilityНеобязательныйНеобязательный фильтр доступности: available, sold или all.

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

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

  1. Подготовьте непустой query, latitude от -90 до 90, longitude от -180 до 180 и нужные необязательные фильтры.
  2. Отправьте запрос методом POST на /v1/facebook-marketplace/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/facebook-marketplace/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"bike","latitude":30.2677,"longitude":-97.7475,"results_limit":100}'

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

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

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

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

  • Если поиск начинается с названия места, а не с координат, сначала найдите и проверьте вариант через Location Search, а затем передавайте latitude и longitude.
  • Перед отправкой проверяйте диапазоны координат, держите radius_km больше 0, используйте неотрицательные цены и следите, чтобы min_price не превышал max_price.
  • Переходите по next_cursor, пока has_more не станет false, если сохраненных результатов больше, чем помещается на первой странице ответа; results_limit управляет сбором, а не размером страницы ответа задачи.
  • Связывайте повторные срезы по ID объявления и сохраняйте collected_at: дубли ID сохраняются один раз на задачу, а публичные объявления могут меняться или исчезать.
  • Считайте описания, поля продавца, точные координаты, характеристики и время создания необязательными; если нужны более подробные публичные данные, передайте возвращенный URL объявления в Marketplace Item.

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

  • Facebook Marketplace Location Search API — Преобразуйте запросы с названием города, региона, района или места в варианты локаций Marketplace с координатами.
  • Facebook Marketplace Item API — Собирайте подробные публичные объявления Marketplace по известным URL: продавец, цена, местоположение, медиа, характеристики, доставка и наличие.

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

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

Facebook Marketplace Search API — FAQ

Facebook Marketplace Search API получает публичные объявления Marketplace по непустому ключевому слову вокруг обязательных координат широты и долготы. Он возвращает нормализованные идентификаторы объявлений, заголовки, цены, местоположения, изображения, публичные данные продавца, поля состояния, исходные URL и время сбора.

Обязательные параметры запроса — query, latitude и longitude. Необязательные: results_limit, radius_km, минимальная и максимальная цена, порядок сортировки, способ доставки, состояние, давность объявления и доступность с задокументированными значениями enum.

results_limit — это запрошенный максимум, а не гарантированное количество. Сбор останавливается, когда в источнике больше нет страниц, а записи с одинаковым открытым ID объявления сохраняются один раз.

В поисковых карточках могут отсутствовать описания, данные продавца, точные координаты, характеристики и время создания. Клиенты должны пропускать или корректно обрабатывать отсутствующие необязательные поля, а не считать их ошибками запроса.

Пустой результат может означать, что по ключевому слову и координатам не нашлось публичных совпадений, фильтры оказались слишком строгими, доступность в регионе отличалась или публичный источник остановился на границе ответа. Проверьте местоположение и ослабьте необязательные фильтры перед повторной попыткой.

Используйте Location Search, если у вас есть название города, региона, района или места, но нет проверенных координат. Используйте Marketplace Item с известным URL объявления, если нужны более подробные публичные данные, чем дает поисковая карточка.

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