# gsearch.dev Google Search API documentation

> Authenticate once, send a JSON search request, and receive ordered organic Google results in a stable JSON response.

gsearch.dev is an independent service and is not affiliated with or endorsed by Google.

## Endpoint

`POST https://gsearch.dev/api/v1/search`

Send requests from a trusted server environment with `Content-Type: application/json`.

## Authentication

Use either of these methods:

- `X-API-Key: YOUR_API_KEY`
- `Authorization: Bearer YOUR_API_KEY`

Create an API key in the account area. Store it in a server-side secret manager and never expose it in browser code or a public repository.

## Request body

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `q` | string | Yes | None | The text to search for. Use 1 to 300 characters. |
| `gl` | country code | No | us | The country used to localize the search results. |
| `hl` | language code | No | en | The language used for the search interface and results. |
| `page` | integer | No | 1 | The first result page to request. Accepted values are 1 through 100. |
| `pages` | integer | No | 1 | The number of consecutive pages to return. Each page uses 1 credit. The range from page through the final page must stay within 100. |

Supported language codes: `en`, `bg`, `de`, `fr`, `es`.

Supported country codes (239): `af`, `al`, `dz`, `as`, `ad`, `ao`, `ai`, `aq`, `ag`, `ar`, `am`, `aw`, `au`, `at`, `az`, `bs`, `bh`, `bd`, `bb`, `by`, `be`, `bz`, `bj`, `bm`, `bt`, `bo`, `ba`, `bw`, `bv`, `br`, `io`, `bn`, `bg`, `bf`, `bi`, `kh`, `cm`, `ca`, `cv`, `ky`, `cf`, `td`, `cl`, `cn`, `cx`, `cc`, `co`, `km`, `cg`, `cd`, `ck`, `cr`, `ci`, `hr`, `cu`, `cy`, `cz`, `dk`, `dj`, `dm`, `do`, `ec`, `eg`, `sv`, `gq`, `er`, `ee`, `et`, `fk`, `fo`, `fj`, `fi`, `fr`, `gf`, `pf`, `tf`, `ga`, `gm`, `ge`, `de`, `gh`, `gi`, `gr`, `gl`, `gd`, `gp`, `gu`, `gt`, `gn`, `gw`, `gy`, `ht`, `hm`, `va`, `hn`, `hk`, `hu`, `is`, `in`, `id`, `ir`, `iq`, `ie`, `il`, `it`, `jm`, `jp`, `jo`, `kz`, `ke`, `ki`, `kp`, `kr`, `kw`, `kg`, `la`, `lv`, `lb`, `ls`, `lr`, `ly`, `li`, `lt`, `lu`, `mo`, `mk`, `mg`, `mw`, `my`, `mv`, `ml`, `mt`, `mh`, `mq`, `mr`, `mu`, `yt`, `mx`, `fm`, `md`, `mc`, `mn`, `ms`, `ma`, `mz`, `mm`, `na`, `nr`, `np`, `nl`, `an`, `nc`, `nz`, `ni`, `ne`, `ng`, `nu`, `nf`, `mp`, `no`, `om`, `pk`, `pw`, `ps`, `pa`, `pg`, `py`, `pe`, `ph`, `pn`, `pl`, `pt`, `pr`, `qa`, `re`, `ro`, `ru`, `rw`, `sh`, `kn`, `lc`, `pm`, `vc`, `ws`, `sm`, `st`, `sa`, `sn`, `rs`, `sc`, `sl`, `sg`, `sk`, `si`, `sb`, `so`, `za`, `gs`, `es`, `lk`, `sd`, `sr`, `sj`, `sz`, `se`, `ch`, `sy`, `tw`, `tj`, `tz`, `th`, `tl`, `tg`, `tk`, `to`, `tt`, `tn`, `tr`, `tm`, `tc`, `tv`, `ug`, `ua`, `ae`, `gb`, `us`, `um`, `uy`, `uz`, `vu`, `ve`, `vn`, `vg`, `vi`, `wf`, `eh`, `ye`, `zm`, `zw`.

Unknown request fields are rejected. Query text is trimmed and can contain up to 300 Unicode characters. The starting page and page count can each be 1 through 100, and the final requested page cannot exceed 100.

## Example request

```bash
curl -X POST https://gsearch.dev/api/v1/search -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"q":"Ada Lovelace","gl":"us","hl":"en","page":1,"pages":3}'
```

```json
{
  "q": "Ada Lovelace",
  "gl": "us",
  "hl": "en",
  "page": 1,
  "pages": 3
}
```

## Successful response

A successful request returns HTTP 200. Organic results from all requested pages are combined and ordered by position. When `pages` is sent, the response reports `pagesReturned` and `creditsUsed`. Keep the `requestId` when requesting help with a specific request.

```json
{
  "searchParameters": {
    "q": "Ada Lovelace",
    "type": "search",
    "gl": "us",
    "hl": "en",
    "page": 1,
    "pages": 3
  },
  "organic": [
    {
      "title": "Ada Lovelace | Biography, Computer, and Facts",
      "link": "https://example.com/ada-lovelace",
      "snippet": "A concise result snippet returned as structured text.",
      "position": 1
    }
  ],
  "engine": "google",
  "cached": false,
  "resultCount": 1,
  "pagesReturned": 3,
  "creditsUsed": 3,
  "requestId": "4a7c43b4-19e5-4ecf-a2f8-7d734f7ac731"
}
```

## Credits and rate limits

Each requested page in a successful API or Playground response uses one credit, including a cached page. If any page fails, the request returns no partial response and uses no search credits.

| Plan | API requests per minute | Requested pages per minute |
| --- | ---: | ---: |
| Free | 60 | 100 |
| Builder | 600 | 600 |
| Platform | 3,000 | 3,000 |

A rate-limited request returns HTTP 429. Use the response rate-limit headers to decide when to retry.

## Errors

Every error response uses a JSON object with `code`, `message`, and `requestId` fields.

| HTTP | Code | Meaning |
| ---: | --- | --- |
| 400 | `INVALID_SEARCH_REQUEST or INVALID_JSON` | The request body is missing, malformed, or contains an invalid value. |
| 401 | `AUTH_REQUIRED or INVALID_CREDENTIALS` | The request does not include a valid API key or account session. |
| 402 | `CREDITS_EXHAUSTED` | The account does not have enough credits for every requested page. |
| 413 | `REQUEST_BODY_TOO_LARGE` | The JSON request body is larger than the accepted limit. |
| 415 | `UNSUPPORTED_MEDIA_TYPE` | The request does not use supported UTF-8 JSON content. |
| 429 | `API_PLAN_RATE_LIMITED, API_PLAN_PAGE_RATE_LIMITED, API_SEARCH_IP_RATE_LIMITED, or RATE_LIMITED` | The account request limit, requested-page limit, search IP safety limit, or global API limit was reached. |
| 500 | `INTERNAL_ERROR` | The request failed because of an unexpected service error. |
| 502 | `PROVIDER_UNAVAILABLE or PROVIDER_INVALID_RESPONSE` | The search could not return a valid response. |
| 503 | `SERVICE_UNAVAILABLE` | The search service is temporarily unavailable. |
| 504 | `PROVIDER_TIMEOUT` | The search did not finish before the request deadline. |

## Implementation guides

- [Google Search API country and language targeting](https://gsearch.dev/guides/google-search-api-country-language-targeting/index.md): Use Google Search API country and language parameters correctly, compare markets, validate supported codes, and keep localized requests repeatable.
- [Google Search API retries and rate limits](https://gsearch.dev/guides/google-search-api-retries-rate-limits/index.md): Handle Google Search API rate limits, timeouts, and temporary errors with capped retries, response checks, safe delays, and useful request logs.

## Current contract

- [OpenAPI 3.1 specification](https://gsearch.dev/openapi.json): Complete machine-readable request and response contract.
- [Human-readable API documentation](https://gsearch.dev/docs): Interactive documentation and examples.
- [Pricing and plans in Markdown](https://gsearch.dev/pricing/index.md): Monthly and annual prices, plan limits, and billing rules.
- [Human-readable pricing and plans](https://gsearch.dev/pricing): Current plan comparison and volume options.
- [Developer guides and examples](https://gsearch.dev/guides): Practical Google search JSON, agent, RAG, Python, and Node.js guides.
- [About gsearch.dev](https://gsearch.dev/about): Product scope, operator, service boundaries, and support.
- [Product and pricing in Markdown](https://gsearch.dev/index.md): Plans, prices, product capabilities, and usage rules.