# Google Search

Search Google and retrieve web search results in JSON format.

## Endpoint

```
GET /v1/search/{query}
```

## Description

The Google Search endpoint allows you to perform web searches and retrieve results from Google. 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=search+api`
- `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/search/q=search+api' \
  --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/search/q=search+api', {
  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/search/q=search+api',
    headers=headers
)
data = response.json()
print(data)
```

## Response

The API returns a JSON object containing an array of search results, plus several other Google SERP feature arrays (ads, images, shopping, local places, etc.) that are populated only when Google's results page includes them.

### Response Structure

```json
{
  "results": [
    {
      "title": "Result Title",
      "description": "Result description text...",
      "position": 1,
      "realPosition": 1,
      "result_type": "organic",
      "metadata": {
        "display_url": "example.com"
      },
      "link": "https://example.com"
    }
  ],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "image_results": [],
  "shopping_ads": [],
  "places": [],
  "local_businesses": [],
  "related_searches": [],
  "carousel": [],
  "company": {},
  "total": null,
  "knowledge_graph": "",
  "related_questions": [],
  "carousel_count": 0,
  "ts": 0.9,
  "device_region": "",
  "device_type": null,
  "query": "search api"
}
```

### Response Fields

- **`results`** (array): An array of organic search result objects
  - **`title`** (string): The title of the search result
  - **`description`** (string): The description/snippet of the search result
  - **`position`** (number): Rank within the result set, starting at 1
  - **`realPosition`** (number): Same as `position` for organic results; differs when other SERP features are interleaved
  - **`result_type`** (string): Result classification, e.g. `organic`
  - **`metadata`** (object): Additional details — usually `display_url`; can include `attributes` (array of strings, e.g. a publish date) and, for local-business-style results, `rating`/`reviews`
  - **`link`** (string): The URL of the search result. Results served from certain buckets carry Google's own tracking params (`client=`, `ved=`, `usg=`, etc.) rather than a bare URL
- **`total`** (number | null): Google's estimated result count. Usually `null` — Google only surfaces this on some result pages, so do not rely on it being populated
- **`answers`** (array): Answer box content, if Google shows one for the query. Empty array when absent
- **`ads`**, **`image_results`**, **`shopping_ads`**, **`places`**, **`local_businesses`**, **`related_searches`**, **`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": "The tutorial — Python 3.14.7 documentation",
      "description": "Python is an easy to learn, powerful programming language...",
      "position": 1,
      "realPosition": 1,
      "result_type": "organic",
      "metadata": {
        "display_url": "docs.python.org"
      },
      "link": "https://docs.python.org/3/tutorial/"
    },
    {
      "title": "Python Tutorial - W3Schools",
      "description": "Python is a popular programming language. Python can be used on a server to create web applications...",
      "position": 2,
      "realPosition": 2,
      "result_type": "organic",
      "metadata": {
        "display_url": "www.w3schools.com"
      },
      "link": "https://www.w3schools.com/python/"
    }
  ],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "image_results": [],
  "shopping_ads": [],
  "places": [],
  "local_businesses": [],
  "related_searches": [],
  "carousel": [],
  "company": {},
  "total": null,
  "knowledge_graph": "",
  "related_questions": [],
  "carousel_count": 0,
  "ts": 1.02,
  "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.