Video Search Results via Custom Search API Reference

The Custom Search JSON API does not have a dedicated video search mode, but you can reliably surface video results by combining the standard web search endpoint with site operators or the siteSearch parameter. The most effective approach targets YouTube directly — either by adding site:youtube.com to the query or by setting siteSearch=youtube.com. When Google indexes a video page, it embeds schema.org VideoObject structured data in the result’s pagemap, giving you rich metadata like duration, thumbnail, upload date, and description without any additional API calls.

Endpoint

GET https://www.googleapis.com/customsearch/v1

How Video Search Works

Scope your engine or query to video sources

Point your search at YouTube or other video platforms using the siteSearch parameter or a site: query operator. You can also configure your Programmable Search Engine to include only video-hosting domains.

Send the standard web search request

Use the same endpoint and required parameters (key, cx, q) as a normal web search. No special searchType value is needed.

Extract video metadata from pagemap

Each result item includes a pagemap object. Look for pagemap.videoobject to find schema.org VideoObject fields such as name, description, duration, uploaddate, and thumbnailurl.

Request Parameters

Required Parameters

string

required

Your Google API key.

string

required

Your Programmable Search Engine ID.

string

required

The video search query. You can embed site:youtube.com directly in this string as an alternative to using siteSearch. Example: "machine learning tutorial site:youtube.com".

Site Scoping Parameters

string

Restricts results to a specific domain. Set to youtube.com to target YouTube, or use another video platform’s domain such as vimeo.com or dailymotion.com.

string

Controls whether siteSearch includes or excludes the domain.

i — include only results from the specified site.
e — exclude results from the specified site.

Omit this parameter or set it to i when targeting a video platform.

Filtering and Sorting Parameters

integer

default:"10"

Number of results to return per page. Accepted values are 1 through 10.

integer

default:"1"

Index of the first result. Use with num to paginate through up to 100 results.

string

Sort order of results. Pass date to sort by upload/index date and retrieve the most recently published videos first.

string

Limits results to videos indexed within a time window. Format: [d|w|m|y][number]. For example, d7 returns videos indexed in the last 7 days.

string

Restricts results to pages written in a specific language. Example: lang_en.

string

Biases results toward a specific country. Accepts a two-letter ISO 3166-1 alpha-2 country code.

string

default:"off"

SafeSearch setting. Pass active to filter explicit content.

string

Requires every result to contain this exact phrase.

string

Adds alternative terms — results must match at least one term from q or one term from orTerms.

Example Requests

YouTube via siteSearch
YouTube via site: operator
Multiple video platforms

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=kubernetes+tutorial\
&siteSearch=youtube.com\
&siteSearchFilter=i\
&sort=date\
&num=5"

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=kubernetes+tutorial+site%3Ayoutube.com\
&sort=date\
&num=5"

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=documentary+ocean\
&orTerms=site%3Avimeo.com+site%3Ayoutube.com\
&num=10"

import requests

params = {
    "key": "YOUR_API_KEY",
    "cx": "YOUR_SEARCH_ENGINE_ID",
    "q": "kubernetes tutorial",
    "siteSearch": "youtube.com",
    "siteSearchFilter": "i",
    "sort": "date",
    "num": 5,
}

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    params=params
)
data = response.json()

for item in data.get("items", []):
    pagemap = item.get("pagemap", {})
    videoobject = pagemap.get("videoobject", [{}])[0]

    print(item["title"])
    print(f"  URL:       {item['link']}")
    print(f"  Duration:  {videoobject.get('duration', 'N/A')}")
    print(f"  Uploaded:  {videoobject.get('uploaddate', 'N/A')}")
    print(f"  Thumbnail: {videoobject.get('thumbnailurl', 'N/A')}")

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  cx: "YOUR_SEARCH_ENGINE_ID",
  q: "kubernetes tutorial",
  siteSearch: "youtube.com",
  siteSearchFilter: "i",
  sort: "date",
  num: "5",
});

const response = await fetch(
  `https://www.googleapis.com/customsearch/v1?${params}`
);
const data = await response.json();

for (const item of data.items ?? []) {
  const videoobject = item.pagemap?.videoobject?.[0] ?? {};
  console.log(item.title);
  console.log(`  URL:       ${item.link}`);
  console.log(`  Duration:  ${videoobject.duration ?? "N/A"}`);
  console.log(`  Uploaded:  ${videoobject.uploaddate ?? "N/A"}`);
  console.log(`  Thumbnail: ${videoobject.thumbnailurl ?? "N/A"}`);
}

Example Response

{
  "kind": "customsearch#search",
  "searchInformation": {
    "searchTime": 0.287441,
    "totalResults": "8920000"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Kubernetes Tutorial for Beginners [Full Course] — TechWorld",
      "htmlTitle": "<b>Kubernetes Tutorial</b> for Beginners [Full Course] — TechWorld",
      "link": "https://www.youtube.com/watch?v=X48VuDVv0do",
      "displayLink": "www.youtube.com",
      "snippet": "Complete Kubernetes course covering pods, deployments, services, and ingress. Great for DevOps beginners.",
      "htmlSnippet": "Complete <b>Kubernetes</b> course covering pods, deployments, services...",
      "pagemap": {
        "videoobject": [
          {
            "name": "Kubernetes Tutorial for Beginners [Full Course]",
            "description": "Complete Kubernetes course covering pods, deployments, services, and ingress.",
            "thumbnailurl": "https://i.ytimg.com/vi/X48VuDVv0do/hqdefault.jpg",
            "uploaddate": "2020-11-18",
            "duration": "PT3H12M48S",
            "embedurl": "https://www.youtube.com/embed/X48VuDVv0do",
            "playertype": "HTML5 Flash",
            "isfamilyfriendly": "true",
            "genre": "Technology"
          }
        ],
        "metatags": [
          {
            "og:title": "Kubernetes Tutorial for Beginners [Full Course]",
            "og:type": "video.other",
            "og:url": "https://www.youtube.com/watch?v=X48VuDVv0do"
          }
        ]
      }
    }
  ]
}

Response Fields

Video results use the standard web result structure. The video-specific information lives inside items[].pagemap.videoobject[].

string

The title of the video page as indexed by Google.

string

The URL of the video watch page, e.g. https://www.youtube.com/watch?v=....

string

Human-readable hostname, e.g. "www.youtube.com".

string

A text excerpt from the video page — often the video description.

array

An array of schema.org VideoObject entries extracted from the page’s structured data. Usually contains a single entry. May be absent if the page does not include VideoObject markup.

Show videoobject[] fields

string

The title of the video as specified in structured data.

string

The video description from structured data.

string

URL of the video thumbnail image.

string

ISO 8601 date string representing when the video was published, e.g. "2020-11-18".

string

ISO 8601 duration string, e.g. "PT3H12M48S" for 3 hours, 12 minutes, and 48 seconds.

string

The embeddable URL for the video, suitable for use in an <iframe> src attribute.

string

"true" or "false" — whether the video is suitable for all audiences.

string

The category or genre of the video as declared in its structured data.

string

The player technology used, e.g. "HTML5 Flash".

array

Open Graph and other meta tags from the video page. The og:type value "video.other" indicates a video result.

Show metatags[] fields

string

Open Graph title of the video page.

string

Open Graph type. Common values for videos: "video.other", "video.movie", "video.episode".

string

Canonical URL of the video as declared in Open Graph metadata.

Tips and Patterns

Building a video search UI

Use pagemap.videoobject[0].thumbnailurl for the result card image and pagemap.videoobject[0].duration for the runtime badge. Parse the ISO 8601 duration string with a library such as iso8601-duration (JavaScript) or isodate (Python) to display a human-readable format like "3h 12m".

Filtering by upload recency

Combine sort=date with dateRestrict=w1 to return only videos uploaded or indexed in the last week. This is useful for news-style video feeds where freshness matters.

Handling missing pagemap.videoobject

Not every video page includes schema.org VideoObject markup. Always guard against a missing pagemap.videoobject field in your code and fall back to items[].snippet for the description and items[].link for the URL.

The duration field follows ISO 8601 duration format: PT[H]H[M]M[S]S. For example, PT1H30M means 1 hour and 30 minutes.

Results from siteSearch=youtube.com may include channel pages, playlist pages, and community posts in addition to individual watch pages. Filter results in your code by checking that items[].link contains /watch?v= if you only want individual videos.

​Endpoint

​How Video Search Works

​Request Parameters

​Required Parameters

​Site Scoping Parameters

​Filtering and Sorting Parameters

​Example Requests

​Example Response

​Response Fields

​Tips and Patterns

Endpoint

How Video Search Works

Request Parameters

Required Parameters

Site Scoping Parameters

Filtering and Sorting Parameters

Example Requests

Example Response

Response Fields

Tips and Patterns