Google Video

Search Google Video to retrieve video results in JSON format.

Endpoint

GET /v1/video/{query}

Description

The Google Video Search endpoint allows you to search for videos on Google and retrieve results. The query parameter should be a URL-encoded query string that follows Google's search parameter format.

For reference on Google search parameters, check out our Google Search Operators guide.

Authentication

All requests require authentication using the X-Api-Key header. See the Authentication guide for more details.

Path Parameters

query (required)

Type: string

A URL-encoded query string. This should follow Google's search parameter format.

Examples:

  • q=iphone+reviews
  • q=search+api&num=100

Request Headers

X-Proxy-Location (optional)

Type: string

Specify the proxy location for the search. This determines the geographic location from which the search is performed.

Allowed values:

  • EU - European Union
  • CA - Canada
  • US - United States
  • IE - Ireland
  • GB - United Kingdom
  • FR - France
  • DE - Germany
  • SE - Sweden
  • IN - India
  • JP - Japan
  • KR - South Korea
  • SG - Singapore
  • AU - Australia
  • BR - Brazil

X-User-Agent (optional)

Type: string

Specify the device type for the search. Defaults to desktop if not provided.

Allowed values:

  • desktop - Desktop browser (default)
  • mobile - Mobile device

Request Example

Using cURL

curl --request GET \
  --url 'https://api.serply.io/v1/video/q=iphone+reviews' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Proxy-Location: US' \
  --header 'X-User-Agent: desktop'

Using JavaScript/Node.js

const response = await fetch('https://api.serply.io/v1/video/q=iphone+reviews', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
  }
});
const data = await response.json();
console.log(data);

Using Python

import requests

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
}

response = requests.get(
    'https://api.serply.io/v1/video/q=iphone+reviews',
    headers=headers
)
data = response.json()
print(data)

Response

The API returns a JSON object containing an array of video search results, plus the same SERP-feature arrays as Google Search (ads, images, shopping, etc.), populated only when Google's results page includes them.

Response Structure

{
  "results": [
    {
      "title": "Video Title",
      "link": "https://example.com/video",
      "description": "",
      "realPosition": 1
    }
  ],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "shopping_ads": [],
  "places": [],
  "related_searches": [],
  "image_results": [],
  "carousel": [],
  "company": {},
  "total": null,
  "knowledge_graph": "",
  "related_questions": [],
  "carousel_count": 0,
  "ts": 0.9,
  "device_region": "",
  "device_type": null,
  "query": "iphone reviews"
}

Response Fields

  • results (array): An array of video result objects
    • title (string): The title of the video result
    • link (string): The URL of the video result. Often carries Google's own tracking params (sa=, ved=, usg=) rather than a bare URL
    • description (string): Usually empty — Google's video results rarely include a snippet
    • realPosition (number): Rank within the result set, starting at 1
  • total (number | null): Google's estimated result count. Usually null
  • answers (array): Answer box content, if present. Empty array when absent
  • ads, shopping_ads, places, related_searches, image_results, carousel, related_questions (arrays): Other SERP feature results, populated only when present on the page
  • ads_count, carousel_count (number): Counts for the corresponding arrays
  • company (object), knowledge_graph (string): Knowledge panel data, when present; otherwise empty
  • ts (number): Time in seconds the request took to complete
  • device_region (string): Proxy region used, if specified via X-Proxy-Location
  • device_type (string | null): Device type used for the search
  • query (string): The search query that was run

Example Response

{
  "results": [
    {
      "title": "Python Full Course for Beginners - YouTube",
      "link": "https://www.youtube.com/watch?v=_uQrJ0TkZlc",
      "description": "",
      "realPosition": 1
    },
    {
      "title": "Python Full Course for free - YouTube",
      "link": "https://www.youtube.com/watch?v=ix9cRaBkVe0",
      "description": "",
      "realPosition": 2
    }
  ],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "shopping_ads": [],
  "places": [],
  "related_searches": [],
  "image_results": [],
  "carousel": [],
  "company": {},
  "total": null,
  "knowledge_graph": "",
  "related_questions": [],
  "carousel_count": 0,
  "ts": 1.1,
  "device_region": "",
  "device_type": null,
  "query": "python tutorial"
}

Status Codes

  • 200 OK - Successful response
  • 404 Not Found - The requested resource was not found
  • 422 Unprocessable Entity - The request was well-formed but contains semantic errors
  • 429 Too Many Requests - Rate limit exceeded

Error Responses

See the Errors guide for information on error response formats.

View as Markdown