API documentation
Google Search API documentation
Integrate organic Google search results with one server-side request. Authenticate, target a country and language, and handle structured JSON with the examples below.
One endpoint for text search
Send a JSON body with an HTTP POST request to /api/v1/search. Authenticate with the X-API-Key header or an Authorization Bearer token.
Supported language codes are en, bg, de, fr, es. The OpenAPI 3.1 specification is the machine-readable contract and lists all 239 country codes accepted by gl.
gsearch.dev combines multiple search providers and in-house search scrapers behind one stable API. This sourcing model helps us keep prices low. At its full 300,000-credit monthly allowance, the annual Platform plan works out to $0.58 per 1,000 search credits. One returned page uses one credit.
Authentication
Create a key in your account and send it in the X-API-Key header. You can also use an Authorization Bearer token. Keep API keys in a server-side secret manager and out of browser code and public repositories.
API rate limits by plan
| Plan | Request limit | Requested-page limit |
|---|---|---|
| Free | 60 API requests per minute | 100 requested pages per minute |
| Builder | 600 API requests per minute | 600 requested pages per minute |
| Platform | 3,000 API requests per minute | 3,000 requested pages per minute |
Rate-limited requests return HTTP 429 and do not use a search credit.
Search parameters
| Name | 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. |
JSON request body
{
"q": "Ada Lovelace",
"gl": "us",
"hl": "en",
"page": 1,
"pages": 3
}Make your first API request
Replace the example key, then run this request from a trusted server environment.
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}'Structured JSON response
A successful request returns ordered organic results with a title, link, snippet, and position, plus normalized search parameters and a request ID.
{
"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
Each requested page in a successful API or Playground response uses one credit, including a cached page. Failed requests do not use search credits. The Free plan includes 100 credits each calendar month.
Errors
| 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
Go beyond the field reference with practical guidance for localized targeting, rate limits, retries, and timeouts.