Facebook Marketplace Search
Gli annunci di Facebook Marketplace Search sono offerte pubbliche del commercio locale con titoli, prezzi, posizioni, immagini, contesto del venditore, opzioni di consegna e segnali di disponibilità. Questi campi servono a ricerche sull’inventario locale, al confronto dei prezzi richiesti, all’analisi per categoria e a istantanee di mercato ripetibili.
Funzionalità della Facebook Marketplace Search API
- Ricerca di annunci per parola chiave e area geograficaCombina una query non vuota con latitudine e longitudine obbligatorie, poi restringi gli annunci pubblici con controlli su raggio, prezzo, ordinamento, consegna, condizione, data e disponibilità.
- Record strutturati di annunci e prezziRestituisce ID degli annunci, URL pubblici, titoli, descrizioni disponibili, importi, valute, prezzi formattati e valori barrati in una forma coerente.
- Contesto di posizione, media e classificazioneConserva con ogni risultato le etichette di posizione disponibili, i valori di città e stato, i riferimenti alle immagini, gli ID di categoria, gli attributi, i tipi di consegna e il testo della data di pubblicazione.
- Profondità delle schede di ricerca pubblicheMantiene i campi del venditore esposti e i flag di annuncio attivo, in sospeso, venduto, con spedizione, acquisto immediato e messaggistica, lasciando vuoti i dettagli della scheda quando il risultato pubblico non li fornisce.
Parametri della Facebook Marketplace Search API
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
query | Obbligatorio | Parola chiave obbligatoria e non vuota dell’annuncio; gli spazi iniziali e finali vengono rimossi prima dell’invio. |
latitude | Obbligatorio | Latitudine obbligatoria del centro di ricerca, espressa come numero da -90 a 90. |
longitude | Obbligatorio | Longitudine obbligatoria del centro di ricerca, espressa come numero da -180 a 180. |
results_limit | Facoltativo | Numero massimo di annunci da salvare tra le pagine di ricerca; il valore predefinito è 100 e accetta numeri interi da 1 a 2.000. |
radius_km | Facoltativo | Raggio di ricerca facoltativo in chilometri; se indicato, deve essere un numero maggiore di 0. |
min_price | Facoltativo | Prezzo minimo facoltativo dell’annuncio; non può essere negativo né superare max_price. |
max_price | Facoltativo | Prezzo massimo facoltativo dell’annuncio; non può essere negativo né inferiore a min_price. |
sort_by | Facoltativo | Ordinamento facoltativo: suggested, distance_ascend, creation_time_descend, price_ascend o price_descend. |
delivery_method | Facoltativo | Filtro facoltativo di consegna: all, local_pickup o shipping. |
condition | Facoltativo | Filtro facoltativo di condizione: new, used_like_new, used_good o used_fair. |
date_listed | Facoltativo | Filtro facoltativo di età dell’annuncio: all, 1, 7, 30, last_24_hours, last_7_days o last_30_days. |
availability | Facoltativo | Filtro facoltativo di disponibilità: available, sold o all. |
Come usare la Facebook Marketplace Search API
Invia una parola chiave e un centro geografico con filtri facoltativi, segui l’attività asincrona e leggi gli annunci normalizzati con la paginazione a cursore.
- Prepara una query non vuota, una latitudine da -90 a 90, una longitudine da -180 a 180 e gli eventuali filtri facoltativi.
- Invia con POST la richiesta a /v1/facebook-marketplace/search, poi salva il task_id restituito.
- Interroga /v1/tasks/{task_id} finché l’attività ha successo o restituisce un errore.
- Leggi data.results.items e richiedi il next_cursor restituito finché has_more resta 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 trueCasi d’uso della Facebook Marketplace Search API
- Confronto dei prezzi richiesti a livello locale: Confronta importi normalizzati, valute, titoli, contesto della query e posizioni di annunci pubblici simili all’interno di un’area di ricerca definita.
- Ricerca su inventario regionale e categorie: Usa ID di categoria, attributi, tipi di consegna, campi di disponibilità, immagini e contesto di posizione per costruire un dataset delimitato di annunci locali.
- Istantanee di mercato ripetibili: Conserva ID degli annunci, prezzi, campi di stato, search_query e collected_at per confrontare nel tempo risultati raccolti in modo indipendente per la stessa ricerca.
- Preparazione di una selezione di annunci: Usa URL pubblici degli annunci, titoli, prezzi, immagini e contesto di disponibilità per scegliere i record da approfondire a livello di singolo articolo.
Consigli degli esperti per la Facebook Marketplace Search API
- Quando una ricerca parte da un nome di luogo e non da coordinate, risolvi e verifica un candidato di Location Search prima di inviare latitudine e longitudine.
- Verifica gli intervalli delle coordinate, mantieni radius_km sopra 0, usa prezzi non negativi e assicurati che min_price non superi max_price prima dell’invio.
- Segui next_cursor finché has_more è false quando i risultati salvati superano la prima pagina di risposta; results_limit controlla la raccolta, non la dimensione della pagina di risposta dell’attività.
- Indicizza le istantanee ripetute per ID dell’annuncio e conserva collected_at, perché gli ID duplicati vengono salvati una sola volta per attività e gli annunci pubblici possono cambiare o scomparire.
- Considera facoltativi descrizioni, campi del venditore, coordinate precise, attributi e orari di creazione; usa l’URL di un annuncio restituito con Marketplace Item quando serve un dettaglio pubblico più approfondito.
API correlate
Oltre alla Facebook Marketplace Search API, usa queste API quando ti serve un altro tipo di dati pubblici di Facebook Marketplace.
- Facebook Marketplace Location Search API — Trasforma query con città, regione, quartiere o nome di un luogo in candidati di località di Marketplace e coordinate.
- Facebook Marketplace Item API — Raccoglie annunci pubblici dettagliati di Marketplace dagli URL di articoli noti, con venditore, prezzo, località, media, attributi, consegna e disponibilità.