> 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/documentation/api-and-references/google-search.md).
# Google Search
The Pullbay Google Search API provides programmatic access to Google web search results. Integrate SERP data into your applications, dashboards, and analytics pipelines without scraping or managing your own search infrastructure.
**Base URL:** `https://dashboard.pullbay.com/api`
## Overview
The Google Search service lets you:
* Run a Google web search for any query string
* Page through results with `page`, or pull a larger batch of results in one request with `maxItems`
* Pass through a handful of optional, loosely-specified query modifiers (`safe`, `hl`, `country`, `noEncode`) supported by the underlying search
This is a single-endpoint service: there is one `GET` request that returns Google's organic search results for a query.
## Common Use Cases
**SEO Rank Tracking** — Run the same query on a schedule and track how a domain's position in `data` moves over time.
**SERP Research** — Pull the current result set for a keyword to see which domains, titles, and snippets currently rank.
**Content & Competitor Research** — Search topics relevant to your niche and mine the `title`/`snippet` fields for how competitors position themselves.
**Brand Monitoring** — Search for your brand or product name periodically and check which pages and snippets show up.
**Data Pipelines** — Feed Google search results into a downstream analytics, alerting, or BI pipeline instead of scraping search result pages directly.
## 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 | Default | Description |
| ---------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query` | string | Yes | — | Search query, 1–1000 characters |
| `safe` | string | No | — | Safe-search filter string. The API spec doesn't document a restricted set of accepted values for this parameter. |
| `hl` | string | No | — | Language code string. The API spec doesn't document a restricted set of accepted values for this parameter. |
| `country` | string | No | — | Country/region string. The API spec doesn't document a restricted set of accepted values for this parameter. |
| `count` | string | No | — | Result-count selector. This is a closed enum — the only currently accepted value is `"10"`. The spec does not document any other accepted value. |
| `noEncode` | string | No | — | String parameter. The API spec doesn't document a restricted set of accepted values for this parameter. |
| `maxItems` | integer | No | — | One-shot bulk pull, 1–200 results |
| `page` | integer | No | — | Page number, 1 and up (the documented maximum is effectively unbounded) |
Note: `page` and `maxItems` are both listed as independent optional parameters on this endpoint. The spec does not document a mutual-exclusivity rule between them — use `page` for sequential page-based navigation, or `maxItems` to request a larger batch of results in a single call.
**Example**
```bash
curl -G "https://dashboard.pullbay.com/api/google-search/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d query="openai" \
-d count=10 \
-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": null, "cursor": null, "offset": null },
"pricing": { "creditsCharged": 1 }
}
```
**Response Schema**
| Field | Type | Description |
| ----------------------------------------- | ----------------- | ----------------------------------------------------------------- |
| `data` | array | Array of [GoogleSearchResult objects](#googlesearchresult-object) |
| `pagination.page` | integer, nullable | Current page number (only set when using `page`) |
| `pagination.hasNextPage` | boolean, nullable | Whether another page is available |
| `pagination.cursor` / `pagination.offset` | string, nullable | Not used by this endpoint |
| `pricing.creditsCharged` | number | Credits charged for this request |
**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.
***
## 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 or invalid parameters |
| `402` | Insufficient credits |
| `404` | Not found |
## Object Schema
### GoogleSearchResult object
| Field | Type | Description |
| --------- | ------------ | ------------------------------------------- |
| `type` | string | Result type, e.g. `searchResult` |
| `title` | string | Title of the search result |
| `link` | string (uri) | URL of the search result |
| `snippet` | string | Text snippet shown beneath the result title |
Note: as documented, the GoogleSearchResult object contains only these four fields — there is no position/rank field, no rich-result metadata, and no sitelinks in the schema.
## Python Example: Paginating Through Search Results
This example pages through results using `page`, stopping when a page comes back with no results or `pagination.hasNextPage` is explicitly `false`. The check for an empty page matters here because, as the sample response above shows, `hasNextPage` can come back as `null` rather than a clean boolean:
```python
import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://dashboard.pullbay.com/api"
def get_all_results(query, max_pages=10):
all_results = []
page = 1
while page <= max_pages:
resp = requests.get(
f"{BASE_URL}/google-search/search",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"query": query, "page": page},
)
resp.raise_for_status()
body = resp.json()
results = body.get("data", [])
if not results:
break
all_results.extend(results)
if body.get("pagination", {}).get("hasNextPage") is False:
break
page += 1
return all_results
results = get_all_results("openai")
print(f"Fetched {len(results)} results")
```
Each request is billed independently, with the charged amount reported in that response's `pricing.creditsCharged`. If you'd rather pull a larger batch in one call instead of looping over `page`, pass `maxItems` (1–200) on a single request.
## FAQ
How many results come back per page?
The spec exposes a `count` parameter, but it's a closed enum whose only currently documented value is `"10"`. No other value is documented as accepted.
What do safe, hl, country, and noEncode accept?
The API spec doesn't document a restricted set of accepted values (no enum, no pattern) for any of these four parameters — they're plain optional strings with no further documented constraint. Pullbay's spec does not publish an allow-list for any of them.
Can I use page and maxItems together?
The spec doesn't document a rule against it either way — it lists them as two independent optional parameters. `page` is for stepping through results sequentially; `maxItems` is for pulling a larger batch of results in one shot.
What's the credit cost per request?
It's dynamic — every response includes `pricing.creditsCharged` with the exact amount for that call. There's no fixed published rate.
Does the response tell me the total number of matching results?
No — the response envelope only includes `data`, `pagination`, and `pricing`. There's no total-result-count field documented for this endpoint.
Can I search images, news, or videos with this endpoint?
No — this endpoint returns standard web search results (`GoogleSearchResult` objects only). There's no separate mode or parameter documented for image, news, or video search.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pullbay.com/documentation/api-and-references/google-search.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.