Pinterest Search
I risultati di Pinterest Search sono Pin pubblici corrispondenti a una query di testo, con titoli, descrizioni, dettagli del creator, riferimenti ai media, categorie, hashtag, timestamp ed engagement visibile. Questi record supportano la ricerca di argomenti, lo studio dei temi visivi, l’analisi del contesto dei creator e il confronto di contenuti basato sulle query.
Funzionalità della Pinterest Search API
- Ricerca di Pin basata su queryAccetta una query di testo non vuota e un results_limit da 1 a 2.000 per richiedere una raccolta limitata di record di Pin pubblici.
- Record normalizzati di Pin, creator e mediaRestituisce ID dei Pin, URL, titoli, testi, campi pubblici del creator e riferimenti a immagini o video in una struttura di risultato coerente.
- Tassonomia e contesto dei segnali visibiliConserva categorie, hashtag, tipo di Pin, metadati di origine, numero visibile di Mi piace, commenti e follower del creator, data di pubblicazione, orario di raccolta e contesto della query inviata, quando disponibili.
Parametri della Pinterest Search API
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
query | Obbligatorio | Query di testo obbligatoria e non vuota usata per trovare i Pin pubblici di Pinterest; gli spazi iniziali e finali vengono rimossi prima dell’invio. |
results_limit | Facoltativo | Numero massimo di Pin richiesti per la query; il valore predefinito è 100 e accetta interi da 1 a 2.000. |
Come usare la Pinterest Search API
Invia una query di testo di Pinterest con un limite di risultati, segui l’attività asincrona e leggi i Pin normalizzati con la paginazione a cursore.
- Prepara una query di testo non vuota e scegli un results_limit da 1 a 2.000.
- Invia con POST query e results_limit a /v1/pinterest/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/pinterest/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"home office ideas","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 Pinterest Search API
- Dataset di Pin per argomento: Usa una query definita con ID dei Pin, URL di origine, titoli, testi, riferimenti ai media e discovery_input per costruire una raccolta tematica tracciabile.
- Ricerca visiva e sulla tassonomia: Confronta immagini o video, post_type, categorie, hashtag, titoli e descrizioni per esaminare formati e temi nei risultati di una query.
- Confronto di creator e segnali visibili: Combina i campi pubblici del creator con il numero di Mi piace, commenti e follower e con collected_at, per confrontare il contesto osservato tra raccolte di query diverse.
Consigli degli esperti per la Pinterest Search API
- Invia una query non vuota dopo aver rimosso gli spazi accidentali attorno al testo e mantieni results_limit tra 1 e 2.000 per rispettare la validazione dell’input.
- Segui next_cursor finché has_more è false quando i risultati salvati superano la prima pagina di risposta da 50 elementi.
- Conserva extra.discovery_input e collected_at, così ogni Pin resta legato alla parola chiave inviata e al momento dell’osservazione.
- Gestisci title, text, dettagli dell’autore, media, created_at, categorie, hashtag, source e le singole metriche come campi facoltativi, invece di trattare i valori mancanti come errori della richiesta.
API correlate
Oltre alla Pinterest Search API, usa queste API quando ti serve un altro tipo di dati pubblici di Pinterest.
- Pinterest Pins API — Trasforma gli URL dei Pin pubblici in contenuti, creator, media, tassonomia, date e metriche visibili normalizzati.
- Pinterest User Pins API — Individua i Pin pubblici dagli URL dei profili con un limite per profilo e contenuti, creator, media, date e metriche visibili normalizzati.
- Pinterest Profiles API — Raccoglie identità del profilo pubblico, bio, immagine, sito web, conteggi visibili dell’account e contesto della raccolta dagli URL dei profili.
- Pinterest User Boards API — Elenca le bacheche dei profili Pinterest dagli URL dei profili, con nomi, descrizioni, copertine, date di creazione e numero di Pin, follower, sezioni e collaboratori.
- Pinterest Board Pins API — Raccoglie i Pin di una bacheca Pinterest dal suo URL nell’ordine della bacheca, con testo del Pin, account che l’ha salvato, immagini a piena risoluzione e link ai Pin.
- Pinterest Topic API — Legge gli URL delle pagine delle idee di Pinterest per ottenere le ricerche mensili di ogni argomento, la data di aggiornamento e gli argomenti più specifici suggeriti.