API Reference

L'API YouTube Data ti consente di incorporare le funzioni normalmente eseguite sul sito web di YouTube nel tuo sito web o nella tua applicazione. Le seguenti sezioni identificano i diversi tipi di risorse che puoi recuperare utilizzando l'API. L'API supporta anche 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, ad esempio un video, una playlist o un abbonamento. 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 nell'applicazione.

Chiama l'API

Alle richieste API YouTube Data si applicano i seguenti requisiti:

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

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

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

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 query access_token nel seguente modo: ?access_token=oauth2-token
   • Utilizza l'intestazione HTTP Authorization nel seguente modo: Authorization: Bearer oauth2-token

   Le istruzioni complete per implementare l'autenticazione OAuth 2.0 nella tua applicazione sono disponibili nella guida all'autenticazione.

Tipi di risorse

Attività

Una risorsa activity contiene informazioni su un'azione eseguita su YouTube da un determinato canale o utente. Le azioni segnalate nei feed attività includono la valutazione di un video, la condivisione di un video, l'aggiunta di un video ai preferiti, 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 valutato o caricato.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 canale specifico o al canale dell'utente.

Sottotitoli

Una risorsa caption rappresenta una traccia di sottotitoli codificati di YouTube. Una traccia dei sottotitoli codificati è associata a un solo video di YouTube.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

Metodo	Richiesta HTTP	Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete	DELETE /captions	Elimina la traccia dei sottotitoli codificati specificata.
download	GET /captions/id	Scarica una traccia dei sottotitoli codificati. La traccia dei sottotitoli codificati 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 codificati.
list	GET /captions	Restituisce un elenco di tracce di sottotitoli codificati associate a un video specificato. La risposta dell'API non contiene i sottotitoli codificati effettivi e il metodo captions.download consente di recuperare una traccia dei sottotitoli codificati.
update	PUT /captions	Aggiorna una traccia di sottotitoli codificati. Quando aggiorni una traccia dei sottotitoli codificati, puoi modificare lo stato di bozza della traccia, caricare un nuovo file di sottotitoli codificati per la traccia o entrambi.

ChannelBanners

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

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 una procedura in tre fasi per aggiornare l'immagine del banner di un canale: Chiama il metodo channelBanners.insert per caricare i dati dell'immagine binaria su YouTube. L'immagine deve avere proporzioni 16:9 e dimensioni di almeno 2048 x 1152 pixel. Consigliamo di caricare un'immagine di 2560 x 1440 px. Estrai il valore della proprietà url dalla risposta restituita dall'API per il passaggio 1. Chiama il metodo channels.update per aggiornare le impostazioni di branding del canale. Imposta il valore della proprietà brandingSettings.image.bannerExternalUrl sull'URL ottenuto nel passaggio 2.

ChannelSections

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

Le sezioni di un canale sono visibili solo se il canale mostra i contenuti in una visualizzazione Sfoglia (anziché in una visualizzazione Feed). Per consentire a un canale di visualizzare i contenuti in una visualizzazione di navigazione, imposta la proprietà brandingSettings.channel.showBrowseView su true per il canale specificato.

Un canale può creare un massimo di 10 sezioni.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 un massimo di 10 sezioni.
list	GET /channelSections	Restituisce un elenco di risorse channelSection 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 saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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. Questo metodo supporta solo gli aggiornamenti degli oggetti brandingSettings e invideoPromotion della risorsa channel e delle relative proprietà secondarie.

CommentThreads

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

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

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 può essere un commento di primo livello o una risposta a un commento di primo livello.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 di 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.
delete	DELETE /comments	Elimina un commento.
update	PUT /comments	Modifica un commento.

I18nLanguages

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

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

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

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

I18nRegions

Una risorsa i18nRegion identifica un'area geografica che un utente di YouTube può selezionare come regione di contenuti preferita. La regione dei contenuti può essere definita anche locale dei contenuti. Per il sito web di YouTube, una regione di contenuti potrebbe essere selezionata automaticamente in base a euristiche come il dominio YouTube o la posizione IP dell'utente. Un utente può anche selezionare manualmente la regione dei contenuti dal piè di pagina del sito YouTube.

Ogni risorsa i18nRegion identifica un codice e un nome della regione. 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 saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

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

Membri

Una risorsa member rappresenta un abbonato a un canale YouTube. Un abbonato fornisce un sostegno 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 della risorsa e l'elenco delle proprietà.

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

MembershipsLevels

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

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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.

PlaylistItems

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

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

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

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

Playlist

Una risorsa playlist rappresenta una playlist di YouTube. Una playlist è una raccolta di video che possono essere visualizzati in sequenza e condivisi con altri utenti. Per impostazione predefinita, le playlist sono visibili pubblicamente agli altri utenti, ma possono essere pubbliche o private.

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

• video caricati
• video con valutazioni positive (Mi piace)
• cronologia visualizzazioni
• guarda più tardi

Per essere più precisi, questi elenchi sono associati a un canale, ovvero una raccolta di video, playlist e altre informazioni di YouTube di una persona, un gruppo o un'azienda. Puoi recuperare gli ID playlist per ciascuno di questi elenchi da channel resource per un determinato canale.

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

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 ai loro 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 della privacy di una playlist.

Cerca

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. Sebbene un risultato di ricerca rimandi a una risorsa identificabile in modo univoco, come un video, non dispone di dati persistenti propri.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 della query specificati nella richiesta API. Per impostazione predefinita, un insieme di risultati di ricerca identifica le risorse video, channel e playlist corrispondenti, ma puoi anche configurare le query in modo da recuperare solo un tipo specifico di risorsa.

Iscrizioni

Una risorsa subscription contiene informazioni sull'abbonamento di un utente di YouTube. Un'iscrizione avvisa un utente quando vengono aggiunti nuovi video a un canale o quando un altro utente esegue una delle diverse azioni su YouTube, ad esempio caricare un video, valutarlo o commentarlo.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

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

Miniature

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

• La proprietà snippet.thumbnails di una risorsa è un oggetto che identifica le immagini in miniatura disponibili per quella 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.
• Diversi tipi di risorse possono supportare dimensioni diverse delle immagini delle miniature.
• Diversi tipi di risorse possono definire dimensioni diverse per le immagini in miniatura con lo stesso nome. Ad esempio, l'immagine in miniatura default per una risorsa video è in genere 120 x 90 px, mentre l'immagine in miniatura default per una risorsa channel è in genere 88 x 88 px.
• Le risorse dello stesso tipo potrebbero comunque avere dimensioni diverse delle immagini in miniatura per determinate immagini, a seconda della risoluzione dell'immagine o dei contenuti originali caricati su YouTube. Ad esempio, un video HD potrebbe supportare miniature con una risoluzione più elevata rispetto ai video non HD.
• Ogni oggetto che contiene informazioni sulle dimensioni di un'immagine in miniatura ha una proprietà width e una proprietà height. Tuttavia, le proprietà di larghezza e altezza potrebbero non essere restituite per l'immagine.
• Se un'immagine in miniatura caricata non corrisponde alle dimensioni richieste, viene ridimensionata in modo da corrispondere alle dimensioni corrette senza modificarne le proporzioni. L'immagine non è ritagliata, ma potrebbe includere barre nere per garantire le dimensioni corrette.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

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

VideoAbuseReportReasons

Una risorsa videoAbuseReportReason contiene informazioni su un motivo per cui un video potrebbe essere segnalato per contenuti offensivi. Quando la tua applicazione chiama il metodo videos.reportAbuse per segnalare un video che viola le norme, la richiesta utilizza le informazioni di una risorsa videoAbuseReportReason per identificare il motivo della segnalazione del video.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

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

VideoCategories

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

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle proprietà.

Metodo	Richiesta HTTP	Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
insert	POST /videos	Carica un video su YouTube e, facoltativamente, imposta i metadati del video.
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	Aggiungere un Mi piace o un Non mi piace a un video o rimuovere una valutazione 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 perché contiene contenuti offensivi.

Filigrane

Una risorsa watermark identifica un'immagine che viene visualizzata durante la riproduzione dei video di un canale specifico. Puoi anche specificare un canale di destinazione a cui l'immagine verrà collegata, nonché i dettagli di temporizzazione che determinano quando viene visualizzata la filigrana durante la riproduzione dei video e per quanto tempo è visibile.

Per saperne di più su questa risorsa, consulta la relativa rappresentazione della risorsa e l'elenco delle 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 del watermark di un canale.