facebook-marketplace/
search

Cerca gli annunci pubblici di Facebook Marketplace per parola chiave e coordinate, con titoli, prezzi, posizioni, immagini, campi di stato e URL di origine come record normalizzati.

Facebook Marketplace Search API

Input con parola chiave e coordinate
Filtri geografici e degli annunci
1–2.000 risultati richiesti
Annunci pubblici normalizzati
0,7 crediti per risultato
Pronto
Pronto

Inserisci i parametri e invia una richiesta. Qui compariranno lo stato dell’attività e i risultati normalizzati.

README

A cura di SocQ · Aggiornato il

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

ParametriObbligatorioDescrizione
queryObbligatorioParola chiave obbligatoria e non vuota dell’annuncio; gli spazi iniziali e finali vengono rimossi prima dell’invio.
latitudeObbligatorioLatitudine obbligatoria del centro di ricerca, espressa come numero da -90 a 90.
longitudeObbligatorioLongitudine obbligatoria del centro di ricerca, espressa come numero da -180 a 180.
results_limitFacoltativoNumero massimo di annunci da salvare tra le pagine di ricerca; il valore predefinito è 100 e accetta numeri interi da 1 a 2.000.
radius_kmFacoltativoRaggio di ricerca facoltativo in chilometri; se indicato, deve essere un numero maggiore di 0.
min_priceFacoltativoPrezzo minimo facoltativo dell’annuncio; non può essere negativo né superare max_price.
max_priceFacoltativoPrezzo massimo facoltativo dell’annuncio; non può essere negativo né inferiore a min_price.
sort_byFacoltativoOrdinamento facoltativo: suggested, distance_ascend, creation_time_descend, price_ascend o price_descend.
delivery_methodFacoltativoFiltro facoltativo di consegna: all, local_pickup o shipping.
conditionFacoltativoFiltro facoltativo di condizione: new, used_like_new, used_good o used_fair.
date_listedFacoltativoFiltro facoltativo di età dell’annuncio: all, 1, 7, 30, last_24_hours, last_7_days o last_30_days.
availabilityFacoltativoFiltro 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.

  1. Prepara una query non vuota, una latitudine da -90 a 90, una longitudine da -180 a 180 e gli eventuali filtri facoltativi.
  2. Invia con POST la richiesta a /v1/facebook-marketplace/search, poi salva il task_id restituito.
  3. Interroga /v1/tasks/{task_id} finché l’attività ha successo o restituisce un errore.
  4. 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 true

Casi 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.

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à.

Esplora altre piattaforme

Combina i dati di Facebook Marketplace con i dati pubblici delle altre piattaforme social supportate.

Facebook Marketplace Search API — FAQ

Facebook Marketplace Search API recupera gli annunci pubblici di Marketplace per una parola chiave non vuota intorno a coordinate di latitudine e longitudine obbligatorie. Restituisce identità dell’annuncio, titoli, prezzi, posizioni, immagini, contesto pubblico del venditore, campi di stato, URL di origine e momento della raccolta, tutto normalizzato.

La richiesta richiede query, latitude e longitude. I controlli facoltativi comprendono results_limit, radius_km, prezzi minimo e massimo, ordinamento, metodo di consegna, condizione, età dell’annuncio e disponibilità, con i valori enum documentati.

results_limit è un massimo richiesto, non un conteggio garantito. La raccolta si ferma quando non ci sono altre pagine della fonte e i record con lo stesso ID di annuncio esposto vengono salvati una sola volta.

Le schede di ricerca possono omettere descrizioni, identità del venditore, coordinate precise, attributi e orari di creazione. I client dovrebbero omettere o gestire in modo sicuro i campi facoltativi assenti, senza considerarli errori della richiesta.

Un risultato vuoto può significare che non è stata restituita alcuna corrispondenza pubblica per la parola chiave e le coordinate, che i filtri erano troppo restrittivi, che la disponibilità regionale era diversa o che la fonte pubblica si è fermata a un limite di risposta. Controlla la posizione e allarga i filtri facoltativi prima di riprovare.

Usa Location Search quando hai il nome di una città, regione, quartiere o luogo ma non coordinate verificate. Usa Marketplace Item con l’URL di un annuncio noto quando ti serve un dettaglio pubblico più approfondito di quello di una scheda di ricerca.

Ogni record di annuncio restituito costa 0,7 crediti SocQ. La stima della richiesta usa results_limit, o 100 se omesso, e un insieme di risultati vuoto non ha alcun addebito.