Search

  • Search results from the API provide information about YouTube videos, channels, or playlists that match specific search criteria, without containing persistent data themselves.

  • The search/list method returns a collection of search results and can be configured to retrieve specific resource types like videos, channels, or playlists.

  • Each search result contains an id object that uniquely identifies the matched resource, and the kind property within this object specifies whether it is a video, channel, or playlist.

  • The snippet object in a search result includes basic details like the title, description, channel information, publishing date, and thumbnail images related to the search result.

  • Thumbnail images in a search result are provided in various resolutions (default, medium, high, standard, maxres), with each having its own URL, width, and height.

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 following JSON structure shows the format of a search result:

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

Properties

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

Properties
kind string
Identifies the API resource's type. The value will be youtube#searchResult.
etag etag
The Etag of this resource.
id object
The id object contains information that can be used to uniquely identify the resource that matches the search request.
id.kind string
The type of the API 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.
snippet 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 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 of 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) object
Valid key values are:
  • default – The default thumbnail image. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
  • medium – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
  • high – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall.
  • standard – An even higher resolution version of the thumbnail image than the high resolution image. This image is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 640px wide and 480px tall.
  • maxres – The highest resolution version of the thumbnail image. This image size is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 1280px wide and 720px tall.
snippet.thumbnails.(key).url string
The image's URL.
snippet.thumbnails.(key).width unsigned integer
The image's width.
snippet.thumbnails.(key).height unsigned integer
The image's height.
snippet.channelTitle string
The title of the channel that published the resource that the search result identifies.
snippet.liveBroadcastContent string
An indication of whether a video or channel resource has live broadcast content. Valid property values are upcoming, live, and none.

For a video resource, a value of upcoming indicates that the video is a live broadcast that has not yet started, while a value of live indicates that the video is an active live broadcast. For a channel resource, a value of upcoming indicates that the channel has a scheduled broadcast that has not yet started, while a value of live indicates that the channel has an active live broadcast.