Contents

Introduction

This document is intended for developers who want to write applications that interact with YouTube. It explains basic concepts of YouTube and of the API itself. It also provides an overview of the different functions that the API supports.

Before you start

1. You need a Google Account to access the Google APIs Console, request an API key, and register your application.

2. Register your application with Google so that it can submit API requests.

3. After registering your application, select the YouTube Data API as one of the services that your application uses:

   1. Go to the APIs Console and select the project that you just registered.
   2. Click on the Services pane.
   3. In the list of APIs, find the YouTube Data API and change its status to ON.

4. Familiarize yourself with the core concepts of the JSON (JavaScript Object Notation) data format. JSON is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.

Resources and resource types

A resource is an individual data entity with a unique identifier. The table below describes the different types of resources that you can interact with using the API.

Note that, in many cases, a resource contains references to other resources. For example, a playlistItem resource's snippet.resourceId.videoId property identifies a video resource that contains complete information about the video. As another example, a search result contains either a videoId, playlistId, or channelId property that identifies a particular video, playlist, or channel resource.

Supported operations

The following table shows the different methods that the API supports:

The API currently supports methods to list each of the supported resource types, and it supports write operations for many resources as well.

The table below identifies the operations that are supported for different types of resources. Operations that insert, update, or delete resources always require user authorization. In some cases, list methods support both authorized and unauthorized requests, where unauthorized requests only retrieve public data while authorized requests can also retrieve information about or private to the currently authenticated user.

Quota usage

The YouTube Data API uses a quota to ensure that developers use the service as intended and do not create applications that unfairly reduce service quality or limit access for others. You can find the quota available to your application in the API console's Quotas pane.

Google calculates your quota usage by assigning a cost to each request, but the cost is not the same for each request. Two primary factors influence a request's quota cost:

1. Different types of operations have different quota costs.

   • A simple read operation that only retrieves the ID of each returned resource has a cost of approximately 1 unit.
   • A write operation has a cost of approximately 50 units.
   • A video upload has a cost of approximately 16000 units.

2. Read and write operations use different amounts of quota depending on the number of resource parts that each request retrieves. Note that insert and update operations write data and also return a resource. So, for example, inserting a playlist has a quota cost of 50 units for the write operation plus the cost of the returned playlist resource.

   As discussed in the following section, each API resource is divided into parts. For example, a playlist resource has two parts, snippet and status, while a channel resource has four parts and a video resource has five. Each part contains a group of related properties, and the groups are designed so that your application only needs to retrieve the types of data that it actually uses.

   An API request that returns resource data must specify the resource parts that the request retrieves. Each part then adds approximately 2 units to the request's quota cost. As such, a video.list request that only retrieves the snippet part for each video might have a cost of 3 units. However, a video.list request that retrieves all of the parts for each resource might have a cost of around 11 quota units.

With these rules in mind, you can estimate the number of read, write, or upload requests that your application could send per day without exceeding your quota. For example, if you have a daily quota of 5,000,000 units, your application could have any of the following approximate limits:

• 1,000,000 read operations that each retrieve two resource parts.
• 50,000 write operations and 450,000 additional read operations that each retrieve two resource parts.
• 200 video uploads, 7000 write operations, and 200,000 read operations that each retrieve three resource parts.

Important Only retrieving the resource parts that your application needs conserves your daily quota and make the entire system more efficient.

Partial resources

The API allows, and actually requires, the retrieval of partial resources so that applications avoid transferring, parsing, and storing unneeded data. This approach also ensures that the API uses network, CPU, and memory resources more efficiently.

YouTube Data API requests support two parameters, which are explained in the following sections, that enable you to identify the resource properties that should be included in API responses.

• The part parameter identifies groups of properties that should be returned for a resource.
• The fields parameter filters the API response to only return specific properties within the requested resource parts.

Understanding the part parameter

The part parameter is a required parameter for any API request that retrieves or returns a resource. The parameter identifies one or more top-level (non-nested) resource properties that should be included in an API response. For example, a video resource has the following parts:

• snippet
• contentDetails
• player
• statistics
• status

All of these parts are objects that contain nested properties, and you can think of these objects as groups of metadata fields that the API server might (or might not) retrieve. As such, the part parameter requires you to select the resource components that your application actually uses. This requirement serves several purposes:

• It lets you manage your API quota usage. If you increase the number of parts you retrieve in API responses, your API usage increases accordingly, and your available quota decreases.
• It reduces latency by preventing the API server from spending time retrieving metadata fields that your application doesn't use.
• It reduces bandwidth usage by reducing (or eliminating) the amount of unnecessary data that your application might retrieve.

Over time, as resources add more parts, these benefits will only increase since your application will not be requesting newly introduced properties that it doesn't support.

Understanding the fields parameter

The fields parameter filters the API response, which only contains the resource parts identified in the part parameter value, so that the response only includes a specific set of fields. The fields parameter lets you remove nested properties from an API response and thereby further reduce your bandwidth usage. (The part parameter cannot be used to filter nested properties from a response.)

The following rules explain the supported syntax for the fields parameter value, which is loosely based on XPath syntax:

• Use a comma-separated list (fields=a,b) to select multiple fields.
• Use an asterisk (fields=*) as a wildcard to identify all fields.
• Use parentheses (fields=a(b,c)) to specify a group of nested properties that will be included in the API response.
• Use a forward slash (fields=a/b) to identify a nested property.

In practice, these rules often allow several different fields parameter values to retrieve the same API response. For example, if you want to retrieve the playlist item ID, title, and position for every item in a playlist, you could use any of the following values:

• fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
• fields=items(id,snippet/title,snippet/position)
• fields=items(id,snippet(title,position))

Note: As with all query parameter values, the fields parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.

Sample partial requests

The examples below demonstrate how you can use the part and field parameters to ensure that API responses only include the data that your application uses:

1. Example 1 returns a video resource that includes four parts as well as kind and etag properties.
2. Example 2 returns a video resource that includes two parts as well as kind and etag properties.
3. Example 3 returns a video resource that includes two parts but excludes kind and etag properties.
4. Example 4 returns a video resource that includes two parts but excludes kind and etag as well as some nested properties in the resource's snippet object.

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies
several resource parts that should be included in the API response.

API response:

{
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": {
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
contentDetails and status properties are not included in the response.

API response:

{
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": {
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
kind and etag properties from the API response.

API response:

{
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": {
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3 so that
in the API response, each video resource's snippet object only includes the
channelId, title, and categoryId properties.

API response:

{
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": {
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

Optimizing performance

Accept-Encoding: gzip
User-Agent: my program (gzip)