YouTube Search
I risultati di YouTube Search sono video pubblici regolari corrispondenti a una parola chiave o a una frase, con titoli, canali, miniature, durata, dettagli di pubblicazione ed engagement visibile. Questi record supportano la scoperta di argomenti, la ricerca sui contenuti, il monitoraggio dei concorrenti e l’analisi delle opportunità.
Funzionalità della YouTube Search API
- Scoperta di video senza URLScopri i video pubblici regolari senza conoscerne in anticipo gli URL.
- Ordinamento dei risultatiOrdina i risultati per rilevanza, data di pubblicazione, valutazione o numero pubblico di visualizzazioni.
- Finestre di pubblicazioneFiltra i risultati per finestre di pubblicazione di un’ora, un giorno, una settimana, un mese o un anno.
- Filtri per durata e sottotitoliFiltra per durata breve, media o lunga e richiedi la disponibilità dei sottotitoli quando serve.
- Risultati video normalizzatiRestituisce metadati normalizzati dei video, informazioni sul canale, miniature, durata, dati di pubblicazione e metriche pubbliche.
Parametri della YouTube Search API
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
query | Obbligatorio | Parola chiave o frase usata per scoprire video pubblici. |
results_limit | Facoltativo | Numero massimo di risultati di video pubblici da richiedere. Deve essere un intero positivo e ha 100 come valore predefinito. |
sort_by | Facoltativo | Ordinamento dei risultati. Il valore predefinito è relevance. |
published_within | Facoltativo | Finestra di pubblicazione facoltativa, misurata dal momento della richiesta. |
duration | Facoltativo | Categoria di durata di YouTube facoltativa. |
has_captions | Facoltativo | Filtro facoltativo sulla disponibilità dei sottotitoli. Lascialo intatto per omettere questo filtro. |
Come usare la YouTube Search API
Scrivi la query come una strategia di recupero, non come una semplice parola chiave. Parti abbastanza in largo da esaminare il panorama, poi aggiungi un filtro alla volta per capire quale scelta ha eliminato i candidati.
- Definisci l’argomento e la domanda: migliori corrispondenze tematiche, copertura più recente, contenuti molto visti o candidati pronti per la trascrizione.
- Invia con POST query e results_limit, più solo l’ordinamento e i filtri necessari per quella domanda, a /v1/youtube/search.
- Salva la richiesta completa insieme al task_id, poi interroga /v1/tasks/{task_id} finché la scoperta ha successo o fallisce.
- Deduplica i risultati per ID del video, conserva il contesto della posizione e collected_at, e scorri le pagine finché has_more è true.
curl -X POST "https://api.socq.ai/v1/youtube/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"NASA Artemis","results_limit":10,"sort_by":"date","published_within":"month","duration":"medium","has_captions":true}'
# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50Casi d’uso della YouTube Search API
- Ricerca su argomenti e mercati: Scopri video pubblici su prodotti, settori, organizzazioni, eventi o argomenti emergenti.
- Scoperta di creator e concorrenti: Usa i risultati di ricerca e le informazioni sul canale che pubblica per individuare creator, brand o concorrenti rilevanti.
- Monitoraggio dei video recenti: Combina l’ordinamento per data e le finestre di pubblicazione per raccogliere i video recenti da rivedere o analizzare.
- Dataset pronti per la trascrizione: Richiedi la disponibilità dei sottotitoli per trovare video da usare nella raccolta di trascrizioni, nel riassunto, nella classificazione o nella ricerca.
Consigli degli esperti per la YouTube Search API
- Prova due o tre varianti precise della query invece di nascondere ogni concetto in un’unica frase lunga. La sovrapposizione è spesso istruttiva quanto le differenze.
- Aggiungi i filtri in modo progressivo. Se specifichi finestra di pubblicazione, durata e sottotitoli tutti insieme, un risultato vuoto dà pochi indizi su quale vincolo fosse troppo stretto.
- Usa date con published_within per il monitoraggio; relevance senza finestra risponde a una domanda di ricerca diversa e più ampia.
- La classifica non è stabile. Salva la richiesta, l’ID attività, l’ID del video e collected_at ogni volta che contano la posizione o la composizione del campione.
- results_limit è un tetto, non una garanzia di completezza. L’idoneità pubblica e i filtri scelti possono produrre meno record.
- Deduplica tra le varianti della query per ID del video, ma conserva quale query ha prodotto ogni corrispondenza per l’analisi successiva della rilevanza.
- Quando l’URL è già noto, usa Videos per i dettagli aggiornati e Transcripts per il testo dei sottotitoli disponibili, invece di cercarlo ripetutamente.
API correlate
Oltre alla YouTube Search API, usa queste API quando ti serve un altro tipo di dati pubblici di YouTube.
- YouTube Comments API — Raccoglie commenti pubblici, autori, engagement, video di origine e contesto della conversazione.
- YouTube Transcripts API — Recupera le trascrizioni disponibili in testo semplice con scelta facoltativa della lingua.
- YouTube Channels API — Recupera identità del canale pubblico, immagini, verifica e statistiche visibili del pubblico.
- YouTube Videos API — Recupera metadati, miniature, durata ed engagement a partire dagli URL di video o Short noti.
- YouTube Hashtag Search API — Trova video pubblici dai feed degli hashtag, raccogliendo tutti i contenuti oppure solo gli Shorts.
- YouTube Channel Search API — Trova canali per parola chiave, con nomi, numero di iscritti, avatar ed estratti della descrizione.
- YouTube Channel Videos API
- YouTube Shorts API
- YouTube Channel Live Videos API
- YouTube Comment Replies API
- YouTube Community Posts API
- YouTube Playlist Videos API
- YouTube Trending Shorts API
- YouTube Community Post API
- YouTube Community Post Comments API
- YouTube Related Videos API
- YouTube Shorts Search API
- YouTube Search Suggestions API
- YouTube Email Finder API
- YouTube Trending Videos API