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
Отправьте ключевое слово и географический центр с необязательными фильтрами объявлений, отслеживайте асинхронную задачу и читайте нормализованные объявления с курсорной пагинацией.
- Подготовьте непустой query, latitude от -90 до 90, longitude от -180 до 180 и нужные необязательные фильтры.
- Отправьте запрос методом POST на /v1/facebook-marketplace/search и сохраните возвращенный task_id.
- Опрашивайте /v1/tasks/{task_id}, пока задача не завершится успешно или с ошибкой.
- Читайте 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.
Связанные API
Помимо Facebook Marketplace Search API, используйте эти API, когда нужен другой тип публичных данных Facebook Marketplace.
- Facebook Marketplace Location Search API — Преобразуйте запросы с названием города, региона, района или места в варианты локаций Marketplace с координатами.
- Facebook Marketplace Item API — Собирайте подробные публичные объявления Marketplace по известным URL: продавец, цена, местоположение, медиа, характеристики, доставка и наличие.