# 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](/docs/guides/search-operators).

## Authentication

All requests require authentication using the `X-Api-Key` header. See the [Authentication guide](/docs/guides/authentication) 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

```bash
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

```javascript
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

```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](/docs/resources/google-search) (ads, images, shopping, etc.), populated only when Google's results page includes them.

### Response Structure

```json
{
  "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

```json
{
  "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](/docs/guides/errors) for information on error response formats.