API Reference

L'API di dati di YouTube ti consente di incorporare le funzioni normalmente eseguite sul sito web di YouTube nel tuo sito web o nella tua applicazione. Gli elenchi riportati di seguito identificano i diversi tipi di risorse che puoi recuperare utilizzando l'API. L'API supporta anche i metodi per inserire, aggiornare o eliminare molte di queste risorse.

Questa guida di riferimento spiega come utilizzare l'API per eseguire tutte queste operazioni. La guida è organizzata per tipo di risorsa. Una risorsa rappresenta un tipo di elemento che fa parte dell'esperienza di YouTube, come un video, una playlist o un'iscrizione. Per ogni tipo di risorsa, la guida elenca una o più rappresentazioni dei dati e le risorse sono rappresentate come oggetti JSON. La guida elenca anche uno o più metodi supportati (LIST, POST, DELETE e così via) per ogni tipo di risorsa e spiega come utilizzarli nella tua applicazione.

Chiamata all'API

I requisiti seguenti sono applicabili alle richieste dell'API YouTube Data:

  1. Ogni richiesta deve specificare una chiave API (con il parametro key) o fornire un token OAuth 2.0. La tua chiave API è disponibile nel riquadro Accesso API della Console per gli sviluppatori per il tuo progetto.

  2. Devi inviare un token di autorizzazione per ogni richiesta di inserimento, aggiornamento ed eliminazione. Devi inoltre inviare un token di autorizzazione per qualsiasi richiesta che recuperi i dati privati dell'utente autenticato.

    Inoltre, alcuni metodi API per il recupero delle risorse potrebbero supportare parametri che richiedono autorizzazione o contenere metadati aggiuntivi quando le richieste vengono autorizzate. Ad esempio, una richiesta per recuperare i video caricati da un utente può contenere anche video privati se la richiesta è autorizzata dall'utente in questione.

  3. L'API supporta il protocollo di autenticazione OAuth 2.0. Puoi fornire un token OAuth 2.0 in uno dei seguenti modi:

    • Utilizza il parametro di ricerca access_token in questo modo: ?access_token=oauth2-token
    • Utilizza l'intestazione HTTP Authorization in questo modo: Authorization: Bearer oauth2-token

    Le istruzioni complete per implementare l'autenticazione OAuth 2.0 nelle tue applicazioni sono disponibili nella guida all'autenticazione.

Tipi di risorse

Attività

Una risorsa activity contiene informazioni su un'azione intrapresa da un determinato canale o utente su YouTube. Le azioni riportate nei feed delle attività includono la valutazione di un video, la condivisione di un video, il contrassegno di un video come preferito, il caricamento di un video e così via. Ogni risorsa activity identifica il tipo di azione, il canale associato all'azione e le risorse associate all'azione, ad esempio il video che è stato valutato o caricato.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /activities Restituisce un elenco di eventi di attività del canale che corrispondono ai criteri della richiesta. Ad esempio, puoi recuperare gli eventi associati a un determinato canale o al canale dell'utente.
insert POST /activities Nota: questo metodo è deprecato e non è più supportato.

Sottotitoli codificati

Una risorsa caption rappresenta una traccia di sottotitoli di YouTube. Una traccia di sottotitoli viene associata esattamente a un video di YouTube.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /captions Elimina la traccia di sottotitoli specificata.
download GET /captions/id Scarica una traccia di sottotitoli. La traccia dei sottotitoli viene restituita nel formato originale, a meno che la richiesta non specifichi un valore per il parametro tfmt e nella lingua originale, a meno che la richiesta non specifichi un valore per il parametro tlang.
insert POST /captions Carica una traccia di sottotitoli.
list GET /captions Restituisce un elenco di tracce di sottotitoli associate a un video specificato. Tieni presente che la risposta dell'API non contiene i sottotitoli effettivi e che il metodo captions.download offre la possibilità di recuperare una traccia di sottotitoli.
update PUT /captions Aggiorna una traccia di sottotitoli. Quando aggiorni una traccia di sottotitoli, puoi modificarne lo stato della bozza, caricare un nuovo file di sottotitoli per la traccia o entrambi.

Banner del canale

Una risorsa channelBanner contiene l'URL che useresti per impostare un'immagine appena caricata come immagine banner di un canale.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Carica un'immagine del banner del canale su YouTube. Questo metodo rappresenta i primi due passaggi di un processo in tre passaggi per aggiornare l'immagine del banner di un canale:

  1. Chiama il metodo channelBanners.insert per caricare i dati dell'immagine binaria su YouTube. L'immagine deve avere proporzioni 16:9 ed essere almeno 2048 x 1152 pixel. Ti consigliamo di caricare un'immagine di 2560 x 1440 pixel.
  2. Estrai il valore della proprietà url dalla risposta restituita dall'API per il passaggio 1.
  3. Chiama il metodo channels.update per aggiornare le impostazioni di branding del canale. Imposta il valore della proprietà brandingSettings.image.bannerExternalUrl con l'URL ottenuto nel passaggio 2.

Sezioni del canale

Una risorsa channelSection contiene informazioni su un insieme di video che un canale ha scelto di mostrare. Ad esempio, una sezione potrebbe includere gli ultimi caricamenti, i caricamenti più popolari o i video di una o più playlist.

Tieni presente che le sezioni di un canale sono visibili solo se il canale mostra contenuti in una visualizzazione sfoglia (anziché in una visualizzazione feed). Per consentire a un canale di mostrare i contenuti in una visualizzazione Sfoglia, imposta la proprietà brandingSettings.channel.showBrowseView su true per il canale specificato.

Un canale può creare al massimo 10 scaffali.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Elimina una sezione del canale.
insert POST /channelSections Aggiunge una sezione del canale al canale dell'utente autenticato. Un canale può creare al massimo 10 scaffali.
list GET /channelSections Restituisce un elenco di channelSection risorse che corrispondono ai criteri della richiesta API.
update PUT /channelSections Aggiorna una sezione del canale.

Canali

Una risorsa channel contiene informazioni su un canale YouTube.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /channels Restituisce una raccolta di zero o più risorse channel che corrispondono ai criteri della richiesta.
update PUT /channels Aggiorna i metadati di un canale. Tieni presente che al momento questo metodo supporta solo gli aggiornamenti agli oggetti brandingSettings e invideoPromotion della risorsa channel e alle relative proprietà secondarie.

Thread di commenti

Una risorsa commentThread contiene informazioni su un thread di commenti di YouTube, che comprende un commento di primo livello e le eventuali risposte a quel commento. Una risorsa commentThread può rappresentare i commenti su un video o su un canale.

Sia il commento di primo livello che le risposte sono in realtà comment risorse nidificate all'interno della risorsa commentThread. La risorsa commentThread non contiene necessariamente tutte le risposte a un commento. Se vuoi recuperare tutte le risposte a un determinato commento, devi utilizzare il metodo comments.list. Inoltre, tieni presente che alcuni commenti non hanno risposte.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /commentThreads Restituisce un elenco di thread di commenti che corrispondono ai parametri della richiesta API.
insert POST /commentThreads Crea un nuovo commento di primo livello. Per aggiungere una risposta a un commento esistente, utilizza il metodo comments.insert.

Commenti

Una risorsa comment contiene informazioni su un singolo commento di YouTube. Una risorsa comment può rappresentare un commento su un video o un canale. Inoltre, il commento potrebbe essere un commento di primo livello o una risposta a un commento di primo livello.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /comments Restituisce un elenco di commenti che corrispondono ai parametri della richiesta API.
setModerationStatus POST /comments/setModerationStatus Imposta lo stato della moderazione di uno o più commenti. La richiesta API deve essere autorizzata dal proprietario del canale o del video associato ai commenti.
insert POST /comments Crea una risposta a un commento esistente. Nota: per creare un commento di primo livello, utilizza il metodo commentThreads.insert.
markAsSpam POST /comments/markAsSpam Esprime l'opinione del chiamante sul fatto che uno o più commenti debbano essere contrassegnati come spam.
delete DELETE /comments Elimina un commento.
update PUT /comments Modifica un commento.

Categorie guida

Una risorsa guideCategory identifica una categoria che YouTube applica in modo algoritmico in base ai contenuti di un canale o ad altri indicatori, come la popolarità del canale. L'elenco è simile a quello delle categorie di video, con la differenza che l'utente che ha caricato il video può assegnare una categoria ma solo YouTube può assegnare una categoria.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /guideCategories Restituisce un elenco di categorie che possono essere associate ai canali YouTube.

I18nLingua

Una risorsa i18nLanguage identifica una lingua dell'applicazione supportata dal sito web di YouTube. La lingua dell'applicazione può anche essere definita lingua dell'interfaccia utente. Per il sito web di YouTube, è possibile selezionare automaticamente una lingua dell'applicazione in base alle impostazioni dell'Account Google, alla lingua del browser o alla posizione IP. Un utente può anche selezionare manualmente la lingua della UI che preferisci dal piè di pagina del sito YouTube.

Ogni risorsa i18nLanguage identifica un codice lingua e un nome. Il codice della lingua può essere utilizzato come valore del parametro hl quando si chiamano i metodi API come videoCategories.list e guideCategories.list.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /i18nLanguages Restituisce un elenco di lingue delle applicazioni supportate dal sito web di YouTube.

Regioni i18n

Una risorsa i18nRegion identifica un'area geografica che un utente di YouTube può selezionare come regione di contenuti preferita. L'area geografica dei contenuti può anche essere definita come lingua dei contenuti. Per il sito web di YouTube, un'area geografica dei contenuti potrebbe essere selezionata automaticamente in base a un'euristica come il dominio di YouTube o la località IP dell'utente. Un utente può anche selezionare manualmente l'area geografica dei contenuti desiderata dal piè di pagina del sito di YouTube.

Ogni risorsa i18nRegion identifica un codice regione e un nome. Il codice regione può essere utilizzato come valore del parametro regionCode quando si chiamano metodi API come search.list, videos.list, activities.list e videoCategories.list.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /i18nRegions Restituisce un elenco di aree geografiche di contenuti supportate dal sito web di YouTube.

Gli abbonati

Una risorsa member rappresenta un membro del canale per un canale YouTube. Un abbonato fornisce un supporto monetario ricorrente a un creator e riceve vantaggi speciali. Ad esempio, gli abbonati possono chattare quando il creator attiva la modalità riservata agli abbonati per una chat.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /members Elenca i membri (precedentemente noti come "sponsor") per un canale. La richiesta API deve essere autorizzata dal proprietario del canale.

Abbonamenti

Una risorsa membershipsLevel identifica un livello di prezzo per il creatore che ha autorizzato la richiesta API.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /membershipsLevels Restituisce una raccolta di zero o più risorse membershipsLevel di proprietà del canale che ha autorizzato la richiesta API. I livelli vengono restituiti in ordine di visualizzazione implicito.

PlaylistElementi

Una risorsa playlistItem identifica un'altra risorsa, ad esempio un video, che è inclusa in una playlist. Inoltre, la risorsa playlistItem contiene dettagli sulla risorsa inclusa che riguardano specificamente il modo in cui la risorsa viene utilizzata in quella playlist.

YouTube utilizza inoltre una playlist per identificare l'elenco dei video caricati da un canale, con ogni playlistItem che rappresenta un video caricato. Puoi recuperare l'ID playlist dell'elenco dalla channel resource per un determinato canale. Puoi quindi utilizzare il metodo playlistItems.list per l'elenco.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Elimina una playlist.
insert POST /playlistItems Aggiunge una risorsa a una playlist.
list GET /playlistItems Restituisce una raccolta di elementi di playlist che corrispondono ai parametri della richiesta API. Puoi recuperare tutti gli elementi della playlist di una playlist specificata o una o più playlist in base all'ID univoco.
update PUT /playlistItems Modifica una voce della playlist. Ad esempio, potresti aggiornare la posizione dell'elemento nella playlist.

Playlist

Una risorsa playlist rappresenta una playlist di YouTube. Una playlist è una raccolta di video che può essere visualizzata in sequenza e condivisa con altri utenti. Una playlist può contenere fino a 200 video e YouTube non limita il numero di playlist create da ciascun utente. Per impostazione predefinita, le playlist sono visibili pubblicamente agli altri utenti, ma possono essere pubbliche o private.

YouTube usa le playlist anche per identificare le raccolte speciali di video per un canale, ad esempio:

  • video caricati
  • video con Mi piace (incluso)
  • Cronologia visualizzazioni
  • guarda più tardi
Per essere più precisi, questi elenchi sono associati a un canale, ovvero una raccolta di video di una persona, un gruppo o una società, playlist e altre informazioni di YouTube. Puoi recuperare gli ID playlist di ciascuno di questi elenchi dalla sezione channel resource di un determinato canale.

Puoi quindi utilizzare il metodo playlistItems.list per recuperare uno di questi elenchi. Puoi anche aggiungere o rimuovere elementi da questi elenchi chiamando i metodi playlistItems.insert e playlistItems.delete.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /playlists Elimina una playlist.
list GET /playlists Restituisce una raccolta di playlist che corrispondono ai parametri della richiesta API. Ad esempio, puoi recuperare tutte le playlist di proprietà dell'utente autenticato oppure una o più playlist in base agli ID univoci.
insert POST /playlists Crea una playlist.
update PUT /playlists Modifica una playlist. Ad esempio, puoi modificare il titolo, la descrizione o lo stato di privacy di una playlist.

Un risultato di ricerca contiene informazioni su un video, un canale o una playlist di YouTube che corrispondono ai parametri di ricerca specificati in una richiesta API. Anche se un risultato di ricerca rimanda a una risorsa identificabile in modo univoco, ad esempio un video, non dispone di dati permanenti.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /search Restituisce una raccolta di risultati di ricerca che corrispondono ai parametri di ricerca specificati nella richiesta API. Per impostazione predefinita, un set di risultati di ricerca identifica le risorse video, channel e playlist corrispondenti, ma puoi anche configurare le query in modo che recuperino solo un tipo specifico di risorsa.

Iscrizioni

Una risorsa subscription contiene informazioni su un'iscrizione degli utenti di YouTube. Le iscrizioni vengono avvisate quando un nuovo utente viene aggiunto a un canale o quando un altro utente intraprende una delle varie azioni su YouTube, ad esempio carica un video, valuta un video o commenta un video.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Elimina una sottoscrizione.
insert POST /subscriptions Aggiunge un'iscrizione al canale dell'utente autenticato.
list GET /subscriptions Restituisce le risorse di sottoscrizione che soddisfano i criteri della richiesta API.

Miniature

Una risorsa thumbnail identifica le diverse dimensioni delle miniature associate a una risorsa. Tieni presente le seguenti caratteristiche delle immagini in miniatura:

  • La proprietà snippet.thumbnails di una risorsa è un oggetto che identifica le miniature disponibili per la risorsa.
  • Una risorsa thumbnail contiene una serie di oggetti. Il nome di ogni oggetto (default, medium, high e così via) si riferisce alle dimensioni dell'immagine in miniatura.
  • Tipi di risorse diversi possono supportare dimensioni dell'immagine in miniatura diverse.
  • Tipi diversi di risorse possono definire dimensioni diverse per le miniature con lo stesso nome. Ad esempio, le dimensioni delle miniature default per una risorsa video in genere sono 120 x 90 px, mentre le dimensioni delle miniature default per una risorsa channel sono in genere 88 x 88 px.
  • Le risorse dello stesso tipo potrebbero comunque avere dimensioni delle miniature diverse per determinate immagini, a seconda della risoluzione dell'immagine originale o dei contenuti caricati su YouTube. Ad esempio, un video HD potrebbe supportare miniature a risoluzione più elevata rispetto a quelle non in HD.
  • Ogni oggetto contenente informazioni su una dimensione dell'immagine in miniatura ha una proprietà width e una proprietà height. Tuttavia, le proprietà di altezza e larghezza potrebbero non essere restituite.
  • Se l'immagine in miniatura caricata non corrisponde alle dimensioni richieste, viene ridimensionata per adattarsi alle dimensioni corrette senza modificarne le proporzioni. L'immagine non è ritagliata, ma può includere barre nere per rendere le dimensioni corrette.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Carica una miniatura personalizzata per un video su YouTube e la imposta per un video.

Motivi di segnalazione di abuso del video

Una risorsa videoAbuseReportReason contiene informazioni sul motivo per cui un video viene segnalato per contenuti illeciti. Quando l'applicazione chiama il metodo videos.reportAbuse per segnalare un video illecito, la richiesta utilizza le informazioni di una risorsa videoAbuseReportReason per identificare il motivo per cui il video viene segnalato.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Recupera un elenco dei motivi che possono essere utilizzati per segnalare video illeciti.

Categorie video

Una risorsa videoCategory identifica una categoria che è stata o potrebbe essere associata ai video caricati.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /videoCategories Restituisce un elenco di categorie che possono essere associate ai video di YouTube.

Video

Una risorsa video rappresenta un video di YouTube.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
insert POST /videos Carica un video su YouTube e, facoltativamente, ne imposta i metadati.
list GET /videos Restituisce un elenco di video che corrispondono ai parametri della richiesta API.
delete DELETE /videos Elimina un video di YouTube.
update PUT /videos Aggiorna i metadati di un video.
rate POST /videos/rate Aggiungi una valutazione che ti piace o non mi piace a un video o rimuovine una da un video.
getRating GET /videos/getRating Recupera le valutazioni che l'utente autorizzato ha assegnato a un elenco di video specificati.
reportAbuse POST /videos/reportAbuse Segnala un video con contenuti offensivi.

Filigrane

Una risorsa watermark identifica un'immagine visualizzata durante le riproduzioni dei video di un canale specificato. Puoi anche specificare un canale di destinazione a cui collegare l'immagine, nonché i dettagli relativi alla tempistica che stabiliscono quando la filigrana viene visualizzata durante le riproduzioni video e la durata di visibilità.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco di proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
set POST /watermarks/set Carica un'immagine filigrana su YouTube e la imposta per un canale.
unset POST /watermarks/unset Elimina l'immagine della filigrana di un canale.