Google SERP

`POST https://api.keirolabs.cloud/api/v2/search/google`

Cost: 2 credits · Latency: ~0.2–0.4 s

Raw Google SERP results. Fast, clean web search powered by Google — returns title, URL, and snippet for each result, with optional country (bias), cr (restrict), and language filters. Results come back normalized, so the shape is always the same.

**When to use it.** Use Google when you need Google-ranking SERP results with clean, predictable shape. Great for rank tracking, SERP analysis, and region/language-targeted queries via country/cr/lang.

**When not to.** Don't use Google if you need the actual page content (use Search+Content) or the lowest-cost raw SERP (Search is cheaper at 0.5 credits).

## Request

**cURL**

```bash
curl -X POST https://api.keirolabs.cloud/api/v2/search/google \
  -H "Authorization: Bearer $KEIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "best vector databases 2026", "maxResults": 10, "country": "us"}'
```

**Python**

```python
import os, requests

res = requests.post(
    "https://api.keirolabs.cloud/api/v2/search/google",
    headers={"Authorization": f"Bearer {os.environ['KEIRO_API_KEY']}"},
    json={
        "query": "best vector databases 2026",
        "maxResults": 10,
        "country": "us"
    },
)
print(res.json())
```

**Node.js**

```js
const res = await fetch("https://api.keirolabs.cloud/api/v2/search/google", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEIRO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "best vector databases 2026",
    "maxResults": 10,
    "country": "us"
  }),
});
console.log(await res.json());
```

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | The search query (1-500 chars). |
| `maxResults` | integer | no | Number of results to return. Default: 10. Max: 20 (server-clamped). |
| `country` | string | no | ISO 3166-1 alpha-2 code (e.g. "us", "gb"). Geolocation bias — prefers results from that country. |
| `cr` | string | no | ISO 3166-1 alpha-2 code. Hard-restricts results to sites from that country. |
| `lang` | string | no | Language code (e.g. "en", "de", "fr"). Interface/host language. Defaults to "en". |

## Response

```json title="200 OK"
{
  "query": "best js frameworks 2025",
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "snippet": "..."
    }
  ],
  "count": 10,
  "latencyMs": 240,
  "creditsCharged": 2,
  "creditsRemaining": 1136
}
```

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `results` | array | no | List of search results, in Google SERP rank order. |
| `results[].title` | string | no | Page title from the search result. |
| `results[].url` | string | no | Full URL of the result. |
| `results[].snippet` | string | no | Short text excerpt from the page (Google snippet). |
| `count` | integer | no | Number of results returned. |
| `latencyMs` | integer | no | Server processing time in milliseconds. |
| `query` | string | no | The sanitized query the results answer. |
| `creditsCharged` | number | no | Credits deducted for this request (2 on every tier). |
| `creditsRemaining` | number | no | Your remaining credit balance after this request. |

## Errors

| Status | Code | Cause | Fix |
| --- | --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Missing or invalid query parameter | Ensure query is a non-empty string (1-500 chars). |
| `401` | `UNAUTHORIZED` | Missing or invalid API key | Check your Authorization: Bearer header. |
| `402` | `INSUFFICIENT_CREDITS` | Not enough credits | Buy more credits or upgrade your plan at /dashboard/billing. |
| `429` | `RATE_LIMIT_EXCEEDED` | Too many requests | Check X-RateLimit-Remaining header. Wait for Retry-After seconds. |
| `502` | `SEARCH_UNAVAILABLE` | Google SERP backend failure | Credits auto-refunded. Retry with exponential backoff. |

## Rate limits

| Tier | Limit |
| --- | --- |
| Free | 3/min |
| Starter | 20/min |
| Pro | 30/min |
| Startup | 40/min |
| Enterprise | 60/min |

Over the limit you get a `429`. See [Rate limits](/rate-limits) for headers and backoff.