Search

The YouTube Data API (v3) is an experimental API version, which means it is still in development. We'll be adding many more features to the API while it is still an experimental version. Until the experimental label is removed, however, the Deprecation Policy for YouTube APIs won't apply to this version as discussed in the API Terms of Service.

A search result contains information about a YouTube video, channel, or playlist that matches the search parameters specified in an API request. While a search result points to a uniquely identifiable resource, like a video, it does not have its own persistent data.

Methods

The API supports the following methods for search:

list: Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching video, channel, and playlist resources, but you can also configure queries to only retrieve a specific type of resource. Try it now.

Resource representation

The JSON structure below shows the format of a search result:

{
  "id": {
    "kind": string,
    "videoId": string,
    "channelId": string,
    "playlistId": string
  },
  "kind": "youtube#searchResult",
  "etag": etag,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string
      }
    }
  }
}

Properties

The following table defines the properties that appear in a search result:

Property name	Value	Description
`id`	`nested object`	The `id` object contains information that can be used to uniquely identify the resource that matches the search request.
`id.kind`	`string`	The kind, or type, of the referred resource.
`id.videoId`	`string`	If the `id.type` property's value is `youtube#video`, then this property will be present and its value will contain the ID that YouTube uses to uniquely identify a video that matches the search query.
`id.channelId`	`string`	If the `id.type` property's value is `youtube#channel`, then this property will be present and its value will contain the ID that YouTube uses to uniquely identify a channel that matches the search query.
`id.playlistId`	`string`	If the `id.type` property's value is `youtube#playlist`, then this property will be present and its value will contain the ID that YouTube uses to uniquely identify a playlist that matches the search query.
`kind`	`string`	The type of the API response. For this resource, the value will be `youtube#searchResult`.
`etag`	`etag`	The ETag of the search result.
`snippet`	`nested object`	The `snippet` object contains basic details about a search result, such as its title or description. For example, if the search result is a video, then the title will be the video's title and the description will be the video's description.
`snippet.publishedAt`	`datetime`	The creation date and time of the resource that the search result identifies. The value is specified in ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) format.
`snippet.channelId`	`string`	The value that YouTube uses to uniquely identify the channel that published the resource that the search result identifies.
`snippet.title`	`string`	The title to display for the search result.
`snippet.description`	`string`	A description of the search result.
`snippet.thumbnails`	`object`	A map of thumbnail images associated with the search result. For each object in the map, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail.
`snippet.thumbnails.(key)`	`nested object`	The thumbnail image's name. This value is used as the key in the `snippet.thumbnails` map.
`snippet.thumbnails.(key).url`	`string`	The thumbnail image's URL.

YouTube

Methods

Resource representation

Properties

Authentication required

Signing you in...