Video Search: Surface Video Results via Google API

The Custom Search JSON API does not have a dedicated searchType=video parameter, but you can reliably surface video results by targeting video platforms directly with siteSearch and by using query operators that match video-hosting page patterns. The most effective approach is to restrict your search to youtube.com — the world’s largest public video index — and combine that with descriptive query terms. You can also target other platforms such as vimeo.com or dailymotion.com using the same technique.

How video search works

Google indexes the metadata and transcripts of publicly available videos. When you restrict your search to a video platform domain using siteSearch, the results returned are video watch pages. Each result’s link is a direct URL to the video player; snippet typically contains the video description; and pagemap often contains structured data including duration, view count, upload date, and thumbnail URLs extracted from the page’s Open Graph and Schema.org markup.

To search across multiple video platforms simultaneously, configure your Programmable Search Engine in the Control Panel to include youtube.com, vimeo.com, and any other platforms as Included sites. You can then omit the per-request siteSearch parameter.

Key parameters for video search

string

required

Your video search query. You can use standard Google operators to sharpen results. For example:

q=python+tutorial+intitle:beginner — matches “beginner” in the page title
q=jazz+guitar+lesson — broad keyword match across title and description

string

The domain to restrict results to. Set to youtube.com for YouTube-only results, vimeo.com for Vimeo, or any other video platform.

string

Set to i (include) to restrict results exclusively to siteSearch. Set to e (exclude) to strip results from that platform.

string

Although most video watch pages are HTML documents, you can use fileType to find directly linked video files (e.g., mp4, webm) when they are indexed. This is uncommon for major platforms but useful for open-media repositories.

string

Limit results to videos indexed within a time window. Format: d[N], w[N], m[N], y[N]. Use d7 for the last week of uploads, which surfaces trending or recently published content.

string

Set to date to return the most recently indexed videos first rather than sorting by relevance.

integer

Number of results per page. Accepts 1–10. Defaults to 10.

integer

Pagination offset (1-based, max 91). Combine with num to page through up to 100 video results.

Make your first video search request

Choose your target platform

Decide whether you want YouTube-only results, multi-platform results, or results from a specific video host. For most use cases, siteSearch=youtube.com with siteSearchFilter=i is the right starting point.

Build the request

Combine siteSearch, siteSearchFilter, and a descriptive q value:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=machine+learning+for+beginners\
&siteSearch=youtube.com\
&siteSearchFilter=i"

Add recency and sorting filters

Surface the newest content by combining dateRestrict and sort=date:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=machine+learning+for+beginners\
&siteSearch=youtube.com\
&siteSearchFilter=i\
&dateRestrict=m3\
&sort=date"

Full curl examples

YouTube search
Vimeo search
Multi-platform (engine config)
Direct video file search

Fetch the ten most recent YouTube tutorials on Rust programming published in the last 30 days:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=rust+programming+tutorial\
&siteSearch=youtube.com\
&siteSearchFilter=i\
&dateRestrict=m1\
&sort=date\
&num=10"

Search for short documentary films on Vimeo:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=short+documentary+film\
&siteSearch=vimeo.com\
&siteSearchFilter=i\
&num=10"

If your Programmable Search Engine is configured to include multiple video sites, omit siteSearch and query broadly:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=acoustic+guitar+fingerpicking+lesson\
&dateRestrict=y1\
&sort=date"

Find publicly accessible MP4 video files using fileType:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=open+source+conference+talk\
&fileType=mp4"

Sample video result item

A YouTube result’s pagemap typically contains rich structured data. The videoobject key (when present) carries duration, upload date, view count, and a thumbnail URL extracted from the page’s Schema.org markup:

{
  "kind": "customsearch#result",
  "title": "Machine Learning for Beginners – Full Course in 6 Hours",
  "htmlTitle": "<b>Machine Learning</b> for Beginners – Full Course in 6 Hours",
  "link": "https://www.youtube.com/watch?v=example123",
  "displayLink": "www.youtube.com",
  "snippet": "Learn machine learning from scratch in this comprehensive beginner-friendly course. Topics covered: supervised learning, neural networks, model evaluation...",
  "htmlSnippet": "Learn <b>machine learning</b> from scratch in this comprehensive beginner-friendly course...",
  "formattedUrl": "https://www.youtube.com/watch?v=example123",
  "pagemap": {
    "videoobject": [
      {
        "name": "Machine Learning for Beginners – Full Course in 6 Hours",
        "description": "Learn machine learning from scratch in this comprehensive beginner-friendly course.",
        "thumbnailurl": "https://i.ytimg.com/vi/example123/hqdefault.jpg",
        "uploaddate": "2024-09-01",
        "duration": "PT6H12M",
        "interactioncount": "1240000"
      }
    ],
    "metatags": [
      {
        "og:title": "Machine Learning for Beginners – Full Course in 6 Hours",
        "og:url": "https://www.youtube.com/watch?v=example123",
        "og:image": "https://i.ytimg.com/vi/example123/maxresdefault.jpg",
        "og:video:duration": "22320"
      }
    ]
  }
}

Extract video metadata from `pagemap`

Thumbnail URL

Check pagemap.videoobject[0].thumbnailurl first. Fall back to pagemap.metatags[0]["og:image"] for a wider thumbnail.

const thumbnail =
  item.pagemap?.videoobject?.[0]?.thumbnailurl ??
  item.pagemap?.metatags?.[0]?.["og:image"] ??
  null;

Upload date

ISO 8601 date available at pagemap.videoobject[0].uploaddate (format: YYYY-MM-DD):

const uploadDate = item.pagemap?.videoobject?.[0]?.uploaddate;

Video duration

Duration in ISO 8601 format at pagemap.videoobject[0].duration (e.g., PT6H12M means 6 hours 12 minutes):

const duration = item.pagemap?.videoobject?.[0]?.duration;

View count

Available at pagemap.videoobject[0].interactioncount as a string:

const views = parseInt(item.pagemap?.videoobject?.[0]?.interactioncount ?? "0", 10);

pagemap data is extracted from the page’s structured markup at crawl time and is not guaranteed to be present or up to date. Always code defensively with optional chaining and fallbacks. Fields like interactioncount (view count) reflect the value at the time of the last crawl, not real-time platform data.

Targeting specific video content types

Goal	Recommended approach
Latest uploads on a topic	`sort=date` + `dateRestrict=d7` + `siteSearch=youtube.com`
Full-length courses	Add `intitle:full+course` or `intitle:complete+course` to `q`
Short-form clips	Add `intitle:short` or `inurl:shorts` to `q`
Official channel content	Add `inurl:@channelname` or `site:youtube.com/@channelname` to `q`
Playlist pages	Add `inurl:playlist` to `q`
Publicly hosted MP4s	Use `fileType=mp4` without `siteSearch`

Error reference

HTTP status	Meaning	Common cause
`400`	Bad request	Invalid `fileType` value or malformed `dateRestrict`
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Quota exceeded or API not enabled
`429`	Too many requests	Rate limit; apply exponential back-off
`500`	Server error	Transient issue; retry with back-off

Combine siteSearch=youtube.com with language filtering (lr=lang_es for Spanish, lr=lang_fr for French) to surface video content in a target language. See Advanced Filters for the full lr value list.

Get Started

Core Concepts

Search Features

Guides

Help

Video Search: Surface Video Results via Google API

How video search works

Key parameters for video search

Make your first video search request

Full curl examples

Sample video result item

Extract video metadata from `pagemap`

Targeting specific video content types

Error reference

​How video search works

​Key parameters for video search

​Make your first video search request

​Full curl examples

​Sample video result item

​Extract video metadata from pagemap

​Targeting specific video content types

​Error reference

How video search works

Key parameters for video search

Make your first video search request

Full curl examples

Sample video result item

Extract video metadata from `pagemap`

Targeting specific video content types

Error reference