API Reference

L'API YouTube Data ti consente di incorporare nel tuo sito web o nella tua applicazione le funzioni normalmente eseguite sul sito web di YouTube. Gli elenchi riportati di seguito 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 nella tua applicazione.

Chiamata all'API

Ai seguenti requisiti si applicano le 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 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 sono autorizzate. Ad esempio, una richiesta di recupero dei video caricati da un utente può includere 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 come segue: ?access_token=oauth2-token
    • Utilizza l'intestazione HTTP Authorization come segue: 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 intrapresa da un determinato canale o utente su YouTube. Le azioni registrate nei feed Attività includono la classificazione di un video, la sua condivisione, l'aggiunta ai preferiti, il caricamento 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 ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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 relativi all'attività del canale che corrispondono ai criteri di richiesta. Ad esempio, puoi recuperare gli eventi associati a un determinato canale o al canale dell'utente.
insert POST /activities Nota: questo metodo è stato ritirato e non è più supportato.

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

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /captions Consente di eliminare la traccia di 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 sottotitoli codificati associate a un video specificato. Tieni presente che la risposta dell'API non contiene i sottotitoli effettivi e che il metodo captions.download consente di recuperare una traccia di sottotitoli codificati.
update PUT /captions Aggiorna una traccia di sottotitoli codificati. Quando aggiorni una traccia dei sottotitoli codificati, puoi modificare lo stato della bozza della traccia, caricare un nuovo file dei sottotitoli codificati per la traccia o entrambe le cose.

ChannelBanners

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

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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:

  1. Chiama il metodo channelBanners.insert per caricare i dati delle immagini binarie su YouTube. L'immagine deve avere proporzioni 16:9 e essere di almeno 2048 x 1152 pixel. Consigliamo di caricare un'immagine da 2560 x 1440 px.
  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 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 o più popolari di un canale oppure i video di una o più playlist.

Tieni presente che 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 mostrare 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 ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione e l'elenco delle proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /channelSections Consente di eliminare una sezione del canale.
insert POST /channelSections Aggiunge una sezione 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 di richiesta dell'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 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 di 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.

CommentThreads

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

Sia il commento di primo livello sia 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 per un determinato commento. Tieni inoltre presente che alcuni commenti non hanno risposte.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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 corrispondenti ai parametri della richiesta API.
insert POST /commentThreads Crea un nuovo commento di primo livello. Per aggiungere una risposta a un commento esistente, utilizza invece 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 delle proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /comments Restituisce un elenco di commenti corrispondenti 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.
markAsSpam POST /comments/markAsSpam Nota: questo metodo è stato ritirato e non è più supportato.
delete DELETE /comments Consente di eliminare un commento.
update PUT /comments Modifica un commento.

GuideCategories

Una risorsa guideCategory identifica una categoria assegnata in modo algoritmico da YouTube in base ai contenuti di un canale o ad altri indicatori, come la popolarità del canale. L'elenco è simile alle categorie di video, con la differenza che l'utente che ha caricato un video può assegnargli una categoria, mentre solo YouTube può assegnare una categoria al canale.

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

I18nLanguages

Una risorsa i18nLanguage identifica una lingua di applicazione supportata dal sito web di YouTube. La lingua dell'applicazione può essere indicata anche come 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 dell'IP. Un utente può anche selezionare manualmente la lingua dell'interfaccia utente desiderata dal piè di pagina del sito di YouTube.

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

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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 di applicazione supportate dal sito web di 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 indicata anche come locale dei contenuti. Per il sito web di YouTube, una regione di contenuti potrebbe essere selezionata automaticamente in base a criteri di euristica come il dominio di YouTube o la posizione dell'indirizzo IP dell'utente. Un utente può anche selezionare manualmente la regione 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 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 finanziario ricorrente a un creator e riceve vantaggi speciali. Ad esempio, gli abbonati possono chattare quando il creator attiva la modalità chat riservata agli abbonati per una chat.

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

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /members Elenca gli abbonati (in precedenza noti come "sponsor") di un canale. La richiesta all'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 sua rappresentazione 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, inclusa 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 una playlist anche 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 quell'elenco dalla scheda 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 delle proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Consente di eliminare un elemento di una playlist.
insert POST /playlistItems Aggiunge una risorsa a una playlist.
list GET /playlistItems Restituisce una raccolta di elementi della playlist che corrispondono ai parametri di richiesta dell'API. Puoi recuperare tutti gli elementi di una playlist specifica o uno o più elementi di una playlist in base ai relativi 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ù specifici, 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 di ciascuna di queste playlist dal 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 delle proprietà.

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /playlists Consente di eliminare una playlist.
list GET /playlists Restituisce una raccolta di playlist che corrispondono ai parametri di richiesta dell'API. Ad esempio, puoi recuperare tutte le playlist di proprietà dell'utente autenticato o una o più playlist tramite i relativi 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.

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

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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 di 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.

Abbonamenti

Una risorsa subscription contiene informazioni sull'abbonamento di un utente di YouTube. Un'iscrizione consente a un utente di ricevere una notifica quando vengono aggiunti nuovi video a un canale o quando un altro utente esegue una delle diverse azioni disponibili su YouTube, ad esempio carica un video, lo valuta o lo commenta.

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

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Consente di eliminare 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 di richiesta dell'API.

Miniature

Una risorsa thumbnail identifica diverse dimensioni delle immagini 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 immagini in miniatura 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.
  • I diversi tipi di risorse possono supportare dimensioni diverse delle miniature.
  • Tipi diversi 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 di 120 x 90 px, mentre l'immagine in miniatura default per una risorsa channel è in genere di 88 x 88 px.
  • Le risorse dello stesso tipo possono avere dimensioni diverse per le miniature di determinate immagini, a seconda della risoluzione dell'immagine originale o dei contenuti 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à 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 modificare le proporzioni. L'immagine non è ritagliata, ma potrebbe includere barre nere per avere le dimensioni corrette.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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 video personalizzata su YouTube e la imposta per un video.

VideoAbuseReportReasons

Una risorsa videoAbuseReportReason contiene informazioni sul motivo per cui un video è stato segnalato per contenuti offensivi. Quando la tua applicazione chiama il metodo videos.reportAbuse per segnalare un video illecito, la richiesta utilizza le informazioni di una risorsa videoAbuseReportReason per identificare il motivo della segnalazione.

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

Metodo Richiesta HTTP Descrizione
URI relativi a https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons Visualizza 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 ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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 ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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, ne imposta i metadati.
list GET /videos Restituisce un elenco di video corrispondenti ai parametri della richiesta API.
delete DELETE /videos Consente di eliminare un video di YouTube.
update PUT /videos Aggiorna i metadati di un video.
rate POST /videos/rate Aggiungere una valutazione di Mi piace o Non mi piace a un video o rimuoverla.
getRating GET /videos/getRating Recupera le valutazioni assegnate dall'utente autorizzato a un elenco di video specificati.
reportAbuse POST /videos/reportAbuse Segnalare un video per contenuti illeciti.

Filigrane

Una risorsa watermark identifica un'immagine visualizzata durante la riproduzione dei video di un canale specifico. Puoi anche specificare un canale di destinazione a cui verrà collegato l'immagine, nonché i dettagli relativi alla temporizzazione che determinano quando viene visualizzata la filigrana durante la riproduzione dei video e la durata della sua visibilità.

Per ulteriori informazioni su questa risorsa, consulta la relativa rappresentazione 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 della filigrana su YouTube e la imposta per un canale.
unset POST /watermarks/unset Consente di eliminare l'immagine del watermark di un canale.