> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/google-search.md).

# Google Search

Google Search: web search results. A single read-only `GET` endpoint that returns organic Google search results for a query.

**Base URL:** `https://api.pullbay.com/`

## Endpoints

| Endpoint                    | Description               | Pagination      |
| --------------------------- | ------------------------- | --------------- |
| `GET /google-search/search` | Search the web via Google | Page / maxItems |

***

### Search

Returns Google search results for `query`.

**Request**

```bash
GET /google-search/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                       |
| ---------- | ------- | -------- | ----------------------------------------------------------------- |
| `query`    | string  | Yes      | Search query, 1–1000 characters                                   |
| `safe`     | string  | No       | SafeSearch filter level                                           |
| `hl`       | string  | No       | Interface/results language code (e.g. `en`)                       |
| `country`  | string  | No       | 2-letter ISO country code for the search region                   |
| `count`    | string  | No       | Results per page; only `10` is supported                          |
| `noEncode` | string  | No       | Skip URL-encoding the query before sending it upstream            |
| `page`     | integer | No       | Page number, 1+. Mutually exclusive with `maxItems`               |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `page` |

**Example**

```bash
curl -G "https://api.pullbay.com/google-search/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d query="openai" \
  -d country=us \
  -d hl=en \
  -d page=1
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "searchResult",
      "title": "OpenAI | OpenAI",
      "link": "https://openai.com/",
      "snippet": "We believe our research will eventually lead to artificial general intelligence, a system that can solve human-level problems."
    }
  ],
  "pagination": { "page": 1, "hasNextPage": true, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

## Object schemas

### GoogleSearchResult object

| Field     | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `type`    | string | Result type, always `searchResult`             |
| `title`   | string | Page title as shown in search results          |
| `link`    | string | URL of the result                              |
| `snippet` | string | Descriptive text excerpt shown under the title |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Bad request — missing/invalid parameters |
| `402`  | Insufficient credits                     |
| `404`  | App, developer, or review set not found  |

## Pagination and Bulk Pulls

* Use `page` to walk through results one page at a time (`count=10` results per page); `pagination.hasNextPage` in the response tells you whether to keep going.
* Use `maxItems` instead of `page` to pull a larger result set in a single call (up to 200 results). Don't pass both — they're mutually exclusive.
* `count` currently only accepts the value `10` and can typically be omitted.

## Language and Region Codes

* `hl` accepts a 2–3 letter ISO 639 language code (`en`, `es`, `ja`, ...) to control the language of result snippets and UI strings.
* `country` accepts a 2-letter ISO 3166-1 alpha-2 code (`us`, `gb`, `jp`, ...) to bias results to a search region.
* If omitted, both default to a US/English search context.