API guide
Get Google search results as JSON
Use one server-side POST request to turn a Google text search into ordered JSON. This guide covers the complete path from a query to a checked response.
Send a small, explicit request
Post UTF-8 JSON to /api/v1/search. The q field is required. The gl, hl, and page fields are optional, so include them only when the location, language, or result page matters.
Keep the API key on your server. Do not place it in browser code, mobile app bundles, public repositories, or URLs.
cURL 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}'Read the ordered organic results
A successful response includes normalized searchParameters, an organic array, resultCount, cached, and requestId. Each organic item has a title, link, snippet, and position.
Treat the link as the source URL and position as the order returned for that request. Keep requestId in your logs so a specific request can be traced when you need help.
Successful JSON response · json
{
"searchParameters": {
"q": "Ada Lovelace",
"type": "search",
"gl": "us",
"hl": "en",
"page": 1
},
"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,
"requestId": "4a7c43b4-19e5-4ecf-a2f8-7d734f7ac731"
}Control market, language, and page
The API accepts 239 country codes and 5 language codes: en, bg, de, fr, es. Page values run from 1 through 10.
Use the same query and targeting values when comparing results over time. Search results can change, so store the request fields beside any result data that your product keeps.
Request body · json
{
"q": "Ada Lovelace",
"gl": "us",
"hl": "en",
"page": 1
}Handle errors before reading results
Check the HTTP status before reading organic. Error responses include code, message, and requestId. Failed requests do not use a search credit.
Retry temporary 429, 502, 503, and 504 responses with a delay. Do not retry 400, 401, 402, 413, or 415 until the request, credentials, credits, body size, or content type has been corrected.
- Set a request timeout in your application.
- Use a capped retry count with increasing delays.
- Log the HTTP status, error code, and requestId, but never log the API key.