Facebook Marketplace Search
Los artículos de Facebook Marketplace Search son ofertas públicas de comercio local con títulos, precios, ubicaciones, imágenes, contexto del vendedor, opciones de entrega y señales de disponibilidad. Estos campos sirven para investigar inventario local, comparar precios de venta, analizar categorías y tomar instantáneas repetibles del mercado.
Funcionalidades de la Facebook Marketplace Search API
- Búsqueda de artículos por palabra clave y ubicación geográficaCombine una consulta no vacía con las coordenadas obligatorias de latitud y longitud, y acote los artículos públicos con controles de radio, precio, orden, entrega, condición, fecha y disponibilidad.
- Registros estructurados de artículos y preciosDevuelve los ID de los artículos, las URL públicas, los títulos, las descripciones disponibles, los importes de precio, las monedas, los precios con formato y los valores tachados en una estructura uniforme.
- Contexto de ubicación, medios y clasificaciónConserva en cada resultado las etiquetas de ubicación disponibles, los valores de ciudad y estado, las referencias a imágenes, los ID de categoría, los atributos, los tipos de entrega y el texto de la fecha de publicación.
- Profundidad de las tarjetas de búsqueda públicasConserva los campos del vendedor expuestos y los indicadores de activo, pendiente, vendido, envío, compra inmediata y mensajería, y deja vacíos los detalles de la tarjeta de búsqueda cuando el resultado público no los ofrece.
Parámetros de la Facebook Marketplace Search API
| Parámetros | Obligatorio | Descripción |
|---|---|---|
query | Obligatorio | Palabra clave obligatoria y no vacía del artículo; los espacios iniciales y finales se eliminan antes del envío. |
latitude | Obligatorio | Latitud obligatoria del centro de búsqueda, expresada como un número de -90 a 90. |
longitude | Obligatorio | Longitud obligatoria del centro de búsqueda, expresada como un número de -180 a 180. |
results_limit | Opcional | Número máximo de artículos por guardar entre las páginas de búsqueda; el valor predeterminado es 100 y acepta enteros de 1 a 2,000. |
radius_km | Opcional | Radio de búsqueda opcional en kilómetros; si se indica, debe ser un número mayor que 0. |
min_price | Opcional | Precio mínimo opcional del artículo; no puede ser negativo ni superar max_price. |
max_price | Opcional | Precio máximo opcional del artículo; no puede ser negativo ni ser menor que min_price. |
sort_by | Opcional | Orden opcional: suggested, distance_ascend, creation_time_descend, price_ascend o price_descend. |
delivery_method | Opcional | Filtro opcional de entrega: all, local_pickup o shipping. |
condition | Opcional | Filtro opcional de condición: new, used_like_new, used_good o used_fair. |
date_listed | Opcional | Filtro opcional de antigüedad de la publicación: all, 1, 7, 30, last_24_hours, last_7_days o last_30_days. |
availability | Opcional | Filtro opcional de disponibilidad: available, sold o all. |
Cómo usar la Facebook Marketplace Search API
Envíe una palabra clave y un centro geográfico con filtros de artículos opcionales, siga la tarea asíncrona y lea los artículos normalizados con paginación por cursor.
- Prepare una consulta no vacía, una latitud de -90 a 90, una longitud de -180 a 180 y los filtros opcionales que necesite.
- Envíe la solicitud por POST a /v1/facebook-marketplace/search y guarde el task_id devuelto.
- Consulte /v1/tasks/{task_id} hasta que la tarea termine con éxito o devuelva un error.
- Lea data.results.items y solicite el next_cursor devuelto mientras has_more siga en 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 trueCasos de uso de la Facebook Marketplace Search API
- Comparación de precios de venta locales: Compare los importes de precio normalizados, las monedas, los títulos, el contexto de la consulta y las ubicaciones de artículos públicos similares dentro de un área de búsqueda definida.
- Investigación de inventario regional y de categorías: Use los ID de categoría, los atributos, los tipos de entrega, los campos de disponibilidad, las imágenes y el contexto de ubicación para armar un conjunto de datos acotado de artículos locales.
- Instantáneas repetibles del mercado: Conserve los ID de los artículos, los precios, los campos de estado, search_query y collected_at para comparar a lo largo del tiempo resultados recopilados de forma independiente para la misma búsqueda.
- Preparación de una lista corta de artículos: Use las URL públicas de los artículos, los títulos, los precios, las imágenes y el contexto de disponibilidad para elegir los registros que merecen un seguimiento a nivel de artículo.
Consejos de expertos para la Facebook Marketplace Search API
- Cuando una búsqueda parta de un nombre de lugar y no de coordenadas, resuelva y verifique un candidato de Location Search antes de enviar la latitud y la longitud.
- Valide los rangos de las coordenadas, mantenga radius_km por encima de 0, use precios no negativos y asegúrese de que min_price no supere max_price antes del envío.
- Siga next_cursor hasta que has_more sea false cuando los resultados almacenados superen la primera página de respuesta; results_limit controla la recopilación, no el tamaño de página de la respuesta de la tarea.
- Identifique las instantáneas repetidas por el ID del artículo y conserve collected_at, porque los ID duplicados se almacenan una sola vez por tarea y los artículos públicos pueden cambiar o desaparecer.
- Trate las descripciones, los campos del vendedor, las coordenadas precisas, los atributos y las horas de creación como opcionales; use la URL de un artículo devuelto con Marketplace Item cuando necesite más detalle público.
APIs relacionadas
Además de la Facebook Marketplace Search API, use estas APIs cuando necesite otro tipo de datos públicos de Facebook Marketplace.
- Facebook Marketplace Location Search API — Convierte consultas de ciudad, región, barrio o nombre de lugar en candidatos de ubicación de Marketplace con sus coordenadas.
- Facebook Marketplace Item API — Recolecta artículos públicos detallados de Marketplace desde URLs conocidas, con campos de vendedor, precio, ubicación, contenido multimedia, atributos, entrega y disponibilidad.