> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapengine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Search

> Execute a Google search and retrieve parsed results with organic listings, ads, and more

## Overview

The `/google/search` endpoint executes a Google search query and returns parsed, structured results. This API handles anti-bot measures and provides clean data extraction from Google's search results.

## Parameters

### Query Parameters

<ParamField query="q" type="string" required>
  The search query
</ParamField>

<ParamField query="hl" type="string" default="en">
  Language code for the interface (e.g., `en`, `es`, `fr`, `de`)
</ParamField>

<ParamField query="gl" type="string" default="us">
  Country code for geo-targeted results (e.g., `us`, `uk`, `de`, `jp`)
</ParamField>

<ParamField query="num" type="number" default="10">
  Number of results to return (1-100)
</ParamField>

<ParamField query="start" type="number" default="0">
  Start offset for pagination (e.g., `0` for first page, `10` for second)
</ParamField>

<ParamField query="device" type="string" default="desktop">
  Device type to emulate. Options: `desktop`, `mobile`, `tablet`
</ParamField>

<ParamField query="location" type="string">
  Location for geo-targeted results (e.g., `New York, USA`, `London, UK`)
</ParamField>

<ParamField query="safe" type="string">
  Safe search mode. Options: `off`, `medium`, `high`
</ParamField>

<ParamField query="tbs" type="string">
  Time-based filter for results:

  * `qdr:d` - Past 24 hours
  * `qdr:w` - Past week
  * `qdr:m` - Past month
  * `qdr:y` - Past year
</ParamField>

<ParamField query="tbm" type="string" default="search">
  Search type. Options: `search`, `images`, `news`, `videos`
</ParamField>

<ParamField query="filter" type="number">
  Duplicate content filter. `0` = show all, `1` = filter duplicates
</ParamField>

<ParamField query="nfpr" type="number">
  Auto-correct toggle. `0` = allow corrections, `1` = disable auto-correct
</ParamField>

<ParamField query="uule" type="string">
  Encoded location in UULE format for precise geo-targeting
</ParamField>

<ParamField query="googleDomain" type="string" default="www.google.com">
  Google domain to use (e.g., `www.google.co.uk`, `www.google.de`)
</ParamField>

<ParamField query="rawHtml" type="boolean" default="false">
  Return raw HTML instead of parsed results
</ParamField>

<ParamField query="async" type="boolean" default="false">
  Async mode - returns job ID immediately for later retrieval
</ParamField>

## Example Requests

### Basic Search

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.scrapengine.io/api/v1/google/search?q=best%20coffee%20shops&gl=us&num=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    q: "best coffee shops",
    gl: "us",
    num: "10",
  });

  const response = await fetch(
    `https://api.scrapengine.io/api/v1/google/search?${params}`,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.scrapengine.io/api/v1/google/search"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  params = {
      "q": "best coffee shops",
      "gl": "us",
      "num": 10
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```
</CodeGroup>

### Location-Targeted Search

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.scrapengine.io/api/v1/google/search?q=restaurants&location=New%20York%2C%20USA&device=mobile" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    q: "restaurants",
    location: "New York, USA",
    device: "mobile",
  });

  const response = await fetch(
    `https://api.scrapengine.io/api/v1/google/search?${params}`,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.scrapengine.io/api/v1/google/search"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  params = {
      "q": "restaurants",
      "location": "New York, USA",
      "device": "mobile"
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```
</CodeGroup>

### News Search with Time Filter

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.scrapengine.io/api/v1/google/search?q=technology&tbm=news&tbs=qdr:d" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    q: "technology",
    tbm: "news",
    tbs: "qdr:d",
  });

  const response = await fetch(
    `https://api.scrapengine.io/api/v1/google/search?${params}`,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.scrapengine.io/api/v1/google/search"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  params = {
      "q": "technology",
      "tbm": "news",
      "tbs": "qdr:d"
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```
</CodeGroup>

## Response

### Success Response (200)

Returns parsed search results with organic listings, ads, and other components:

```json theme={null}
{
  "searchInformation": {
    "totalResults": "1250000000",
    "searchTime": 0.45
  },
  "organicResults": [
    {
      "position": 1,
      "title": "Best Coffee Shops in NYC - Top 10 List",
      "link": "https://example.com/best-coffee-nyc",
      "displayLink": "example.com",
      "snippet": "Discover the best coffee shops in New York City with our curated list of local favorites and hidden gems...",
      "date": "2024-01-10"
    },
    {
      "position": 2,
      "title": "Coffee Shop Guide 2024",
      "link": "https://coffeeguide.com/nyc",
      "displayLink": "coffeeguide.com",
      "snippet": "Your complete guide to finding the perfect coffee shop..."
    }
  ],
  "ads": [
    {
      "position": 1,
      "title": "Premium Coffee Shop Equipment",
      "link": "https://ads.example.com/coffee-equipment",
      "displayLink": "ads.example.com",
      "description": "Shop professional coffee equipment at competitive prices"
    }
  ],
  "relatedSearches": [
    "best coffee shops near me",
    "coffee shops with wifi",
    "specialty coffee shops"
  ],
  "pagination": {
    "current": 1,
    "next": "https://api.scrapengine.io/api/v1/google/search?q=best+coffee+shops&start=10"
  }
}
```

### Response Headers

| Header                | Description                       |
| --------------------- | --------------------------------- |
| `x-remaining-credits` | Number of API credits remaining   |
| `x-trace-id`          | Unique identifier for the request |

### Error Responses

| Status | Description                               |
| ------ | ----------------------------------------- |
| `400`  | Bad Request - Invalid query parameters    |
| `401`  | Unauthorized - Invalid or missing API key |
| `500`  | Internal Server Error                     |

## Use Cases

* **SEO monitoring**: Track keyword rankings and SERP positions
* **Competitor analysis**: Monitor competitor visibility in search results
* **Market research**: Analyze search trends and popular content
* **Lead generation**: Find businesses and contact information
* **Content research**: Discover trending topics and content gaps
* **Ad monitoring**: Track competitor advertising strategies