Implementation and Migration: Search requests

The following examples explain how to map search query parameters from the v2 API to their closest equivalents in the v3 API. They also demonstrate how to complete several different types of search requests in the v3 API.

Map of v2 search parameters to the v3 API

The tables below list the search parameters used in the v2 API and their closest equivalents in the v3 API:

v2 API parameter v3 API parameter
3d videoDimension
caption videoCaption
category videoCategoryId
duration videoDuration
ends-after not supported
ends-before not supported
format not supported
hd videoDefinition
license videoLicense
location location
location-radius locationRadius
lr not supported
orderby order
q q
restriction regionCode
safeSearch safeSearch
starts-after not supported
starts-before not supported
status eventType
time publishedBefore
publishedAfter
uploader channelId

New in v3: The v3 API supports the topicId parameter, which indicates that the API response should only contain resources associated with the specified topic. The Searching with Freebase topics guide explains this functionality in detail.

Video search

YouTube Data API (v2) functionality: Searching for videos

This example calls the search.list method to find the most viewed, high-definition (HD) videos associated with the query "skateboarding dog." The query sets the order, part, q, type, and videoDefinition parameters.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &order=viewCount
        &q=skateboarding+dog
        &type=video
        &videoDefinition=high

Related code samples: Java, JavaScript, .NET, PHP, Python, Ruby

Geolocation search

YouTube Data API (v2) functionality: location and location-radius search parameters

This example calls the search.list method to find videos associated with a particular location. It sets the location and locationRadius parameters to retrieve videos taken near Stanford University that are associated with the keyword "Stanford." The query also sets the order parameter to viewCount so that the query retrieves the most viewed videos matching the other search parameters. Note that to use the geolocation search feature, a request must set the type parameter's value to video.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &location=37.43,-122.17
        &locationRadius=5mi
        &order=viewCount
        &q=stanford
        &type=video

Related code samples: Java, PHP, Python

Search for results relevant to a specific language

YouTube Data API (v2) functionality: using the orderby search parameter to find content relevant to a particular language

This example calls the search.list method to find search results that are most relevant to a specific language. The example shows that the query term is marine (q=marine) and that the API response should contain results most relevant to the French language (relevanceLanguage=fr).

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &q=marine
        &relevanceLanguage=fr

Note that the request does not set a value for the type parameter, which means each search result could reference a video, playlist, or channel.

Playlist search

YouTube Data API (v2) functionality: searching for playlists

This example shows how to find playlists matching the query term "GoogleDevelopers." It calls the search.list method and sets the type parameter's value to playlist so that the result set only includes playlists.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &q=GoogleDevelopers
        &type=playlist

Channel search

YouTube Data API (v2) functionality: searching for channels

This example shows how to find channels matching the query term "travel." It calls the search.list method and sets the type parameter's value to channel so that the result set only includes channels.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &q=travel
        &type=channel

Send feedback about...

YouTube Data API
YouTube Data API