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
, andplaylist
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:
|
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. |