SERP API · Google Search
Google Search API for structured, contextual SERP data.
Send a Google query with the locale, device, search surface, and result window that define the observation. Receive the documented request context and parsed JSON result collections your server-side application can evaluate.
GET /v2 · engine=google · Server-side use · Discuss your search-data workflow
- Query-specific Every response starts with
q - Contextual Country, language, location, device
- Surface-aware Web, images, videos, news, shopping, jobs
- Parsed output JSON result collections and metadata
Web data workflow · google searchReady
How to choose a trail shoe
best trail shoes
G ⌕
domain google
.com gl / hl us / en device mobile start / num 0 / 10
cardorganic
cardorganic
cardsample
asideoptional modules
stackimages
From query to usable objects
Keep Google search context attached to the results it produced.
A useful SERP observation is more than a list of links. Define the search conditions up front and retain them with the parsed response so downstream comparisons remain interpretable.
01 · define
Build a precise request fingerprint
Describe the query, Google domain, encoded location, interface language, country, device, surface, and result window required by the workflow.
02 · consume
Work with parsed collections
Read documented metadata and result arrays instead of coupling your application to the presentation markup of a search page.
03 · interpret
Model optionality honestly
Treat search modules as conditional. Their presence varies with the request context and the Google surface returned for that observation.
04 · compare
Keep like-for-like analysis possible
Store the request context beside results before calculating positions, changes, publisher coverage, or product-specific signals.
- 01
Query best trail shoes
- 02
Domain google.com
- 03
Location US · encoded place
- 04
Language en
- 05
Presentation mobile · web
- 06
Window start 0 · num 10
- 07
Output metadata + collections
Documented Google surfaces
Choose the search surface before designing the consumer.
Regular web results use the Google engine without a vertical selector. Documented controls extend the same request model to media, commerce, and jobs surfaces.
Default surface
Web search
Send engine=google and the required q. Leave tbm unset for regular Google Search results.
organic[] + returned modules
Visual discovery
Images
Set the documented vertical selector to tbm=isch.
Watch intent
Videos
Set the documented vertical selector to tbm=vid.
Current coverage
News
Set the documented vertical selector to tbm=nws.
Product discovery
Shopping
Set the documented vertical selector to tbm=shop.
Role discovery
Jobs
Use the documented jobs value ibp=htl;jobs.
Implementation source of truth
Validate inputs and returned modules against the Google Search API documentation with representative queries from your intended workflow.
Request controls
Make each Google observation explicit and reproducible.
Start with the required query parameter. Add documented optional controls only where the workflow needs a particular surface, presentation, locale, or result window.
Required query
q
The keywords to search for on Google.
string · required
Search surface
tbm ibp
tbm selects documented image, video, news, or shopping verticals. ibp supports the documented jobs search value.
string · optional
Presentation
device
Select a supported desktop, mobile, or tablet search presentation.
string · optional
Google host
domain
Choose the Google domain used for the search.
string · optional
Encoded location
uule
Pass a Google encoded location for the search context.
string · optional
Language and country
hl gl
hl sets the interface language; gl supplies the country code used to localize the search.
string · optional
Result window
start num
start is the result offset to skip; num requests the number of results on each page.
integer · optional
Illustrative request GET /v2?engine=google&api_key=…&q=best%20trail%20shoes&domain=google.com&gl=us&hl=en&device=mobile&start=0&num=10
Parsed Google response
Design around stable meanings and conditional modules.
The documented response carries search metadata and parsed JSON result collections. The blocks present in a specific response depend on the query, locale, device, and search vertical.
01 · context
general
Search engine, result count, language, location, presentation, search type, page title, and timestamp fields shown by the documented response example.
02 · request trace
input
Request information such as the original URL and user-agent fields shown by the documented response example.
03 · discovery paths
navigation
Returned navigation entries can identify other Google search surfaces for the query.
04 · parsed results
organic[]
Documented organic objects include fields such as link, display link, title, description, rank, and global rank when returned.
response.json illustrative
{
"general": {
"search_engine": "google",
"language": "en",
"location": "United States",
"mobile": true
},
"organic": [
{
"rank": 1,
"title": "Trail footwear guide",
"link": "https://example.org/guide"
}
],
"navigation": []
}Optionality rule
Result modules are optional. A missing block is different from an unsuccessful HTTP request, and an empty collection should be interpreted within the exact request context—not as a universal absence.
One contextual request
Move from search intent to validated JSON in three steps.
Your application defines the observation and consumes the response. WebScrapingAPI operates the documented Google Search retrieval and parsing path between them.
- 01
Frame the observation
Choose the query, search surface, Google domain, encoded location, language, country, device, and page window required by the decision.
- 02
Call the server-side endpoint
Send a GET request to
https://serpapi.webscrapingapi.com/v2withapi_key,engine=google, andq. - 03
Validate before use
Inspect the HTTP outcome, parse JSON, read the collections your workflow needs, and preserve the request context with stored results.
Synchronous request
engine=google
Use the standard path when the application should wait for the current parsed Google response.
Queued retrieval
engine=google_async
Submit a Google search and retrieve the finished SERP payload later through the Snapshot API.
Integration
Start with a bounded, failure-aware Google request.
Keep the API key in server-side configuration, encode query values, set an explicit timeout, and surface unsuccessful HTTP outcomes before parsing the response.
Request contract
Test the context your product will use.
The examples send the same representative Google web query with US English mobile context.
- Endpoint
https://serpapi.webscrapingapi.com/v2- Required
api_key+engine=google+q- Context
gl=us+hl=en+device=mobile- Boundary
- 120-second client timeout and explicit HTTP error handling
: "${WSA_API_KEY:?WSA_API_KEY is required}"
curl --get --fail-with-body --max-time 120 \
"https://serpapi.webscrapingapi.com/v2" \
--data-urlencode "api_key=$WSA_API_KEY" \
--data-urlencode "engine=google" \
--data-urlencode "q=best trail shoes" \
--data-urlencode "gl=us" \
--data-urlencode "hl=en" \
--data-urlencode "device=mobile"import os
import requests
api_key = os.environ.get("WSA_API_KEY")
if not api_key:
raise RuntimeError("WSA_API_KEY is required")
response = requests.get(
"https://serpapi.webscrapingapi.com/v2",
params={
"api_key": api_key,
"engine": "google",
"q": "best trail shoes",
"gl": "us",
"hl": "en",
"device": "mobile",
},
timeout=120,
)
response.raise_for_status()
print(response.json())const apiKey = process.env.WSA_API_KEY;
if (!apiKey) throw new Error("WSA_API_KEY is required");
const parameters = new URLSearchParams({
"api_key": apiKey,
"engine": "google",
"q": "best trail shoes",
"gl": "us",
"hl": "en",
"device": "mobile",
});
const response = await fetch(
"https://serpapi.webscrapingapi.com/v2?" + parameters,
{ signal: AbortSignal.timeout(120_000) }
);
if (!response.ok) {
throw new Error("Google Search API status " + response.status);
}
console.log(await response.json());<?php
$apiKey = getenv("WSA_API_KEY");
if ($apiKey === false || $apiKey === "") {
throw new RuntimeException("WSA_API_KEY is required");
}
$endpoint = "https://serpapi.webscrapingapi.com/v2"
. "?engine=google"
. "&api_key=" . rawurlencode($apiKey)
. "&q=" . rawurlencode("best trail shoes")
. "&gl=us&hl=en&device=mobile";
$client = curl_init($endpoint);
curl_setopt_array($client, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($client);
$status = curl_getinfo($client, CURLINFO_RESPONSE_CODE);
$error = curl_error($client);
curl_close($client);
if ($body === false) throw new RuntimeException($error);
if ($status >= 400) throw new RuntimeException("API status " . $status);
echo $body;package main
import (
"fmt"
"io"
"net/http"
"net/url"
"os"
"time"
)
func main() {
apiKey := os.Getenv("WSA_API_KEY")
if apiKey == "" { panic("WSA_API_KEY is required") }
endpoint := "https://serpapi.webscrapingapi.com/v2?engine=google" +
"&api_key=" + url.QueryEscape(apiKey) +
"&q=" + url.QueryEscape("best trail shoes") +
"&gl=us&hl=en&device=mobile"
client := &http.Client{Timeout: 120 * time.Second}
response, err := client.Get(endpoint)
if err != nil { panic(err) }
defer response.Body.Close()
if response.StatusCode >= 400 {
panic(fmt.Sprintf("API status %d", response.StatusCode))
}
body, err := io.ReadAll(response.Body)
if err != nil { panic(err) }
fmt.Println(string(body))
}import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
public final class GoogleSearchApiExample {
public static void main(String[] args) throws Exception {
String apiKey = System.getenv("WSA_API_KEY");
if (apiKey == null || apiKey.isBlank()) {
throw new IllegalStateException("WSA_API_KEY is required");
}
String endpoint = "https://serpapi.webscrapingapi.com/v2"
+ "?engine=google"
+ "&api_key=" + URLEncoder.encode(
apiKey, StandardCharsets.UTF_8)
+ "&q=" + URLEncoder.encode(
"best trail shoes", StandardCharsets.UTF_8)
+ "&gl=us&hl=en&device=mobile";
var request = HttpRequest.newBuilder(URI.create(endpoint))
.timeout(Duration.ofSeconds(120))
.GET().build();
var response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() < 200 || response.statusCode() >= 300) {
throw new RuntimeException("API status " + response.statusCode());
}
System.out.println(response.body());
}
}
using System;
using System.Net;
using System.Net.Http;
var rawApiKey = Environment.GetEnvironmentVariable("WSA_API_KEY");
if (string.IsNullOrWhiteSpace(rawApiKey)) {
throw new InvalidOperationException("WSA_API_KEY is required");
}
var apiKey = WebUtility.UrlEncode(rawApiKey);
var query = WebUtility.UrlEncode("best trail shoes");
var endpoint = "https://serpapi.webscrapingapi.com/v2"
+ "?engine=google&api_key=" + apiKey
+ "&q=" + query
+ "&gl=us&hl=en&device=mobile";
using var client = new HttpClient();
client.Timeout = TimeSpan.FromSeconds(120);
var response = await client.GetAsync(endpoint);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());require "net/http"
require "uri"
api_key = ENV["WSA_API_KEY"]
raise "WSA_API_KEY is required" if api_key.nil? || api_key.empty?
api_key = URI.encode_www_form_component(api_key)
query = URI.encode_www_form_component("best trail shoes")
uri = URI("https://serpapi.webscrapingapi.com/v2" +
"?engine=google&api_key=#{api_key}&q=#{query}" +
"&gl=us&hl=en&device=mobile")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.open_timeout = 10
http.read_timeout = 120
response = http.get(uri.request_uri)
unless response.is_a?(Net::HTTPSuccess)
raise "API status #{response.code}"
end
puts response.bodyBuyer workflows
Turn comparable Google observations into product-specific signals.
Preserve the query fingerprint first. Then apply the storage, calculations, review rules, and decision logic appropriate to the workflow.
SEO intelligence
Position and module monitoring
Compare returned organic positions and optional modules across controlled queries, locales, devices, and result windows.
Explore search monitoring →
Brand visibility
Publisher and domain presence
Observe returned domains for approved query groups while keeping absence and significance rules inside your application.
Explore brand protection →
Market research
Topic and source landscapes
Map returned publishers, titles, and descriptions across comparable search contexts and review periods.
Explore market research →
Search data contract
Historical SERP records
Define the schema, observation timestamp, request fingerprint, validation states, and retention model needed beyond request-time JSON.
Review search-result data →
Product choice
Choose the layer that matches your ownership model.
Google Search API is the engine-specific option for a documented Google request and parsed response. Adjacent products shift retrieval, extraction, or delivery ownership.
Network access
Proxies
Your team owns the search client, retrieval logic, parsing, response model, and maintenance.
Infrastructure
Page retrieval
Scraper API
Request an eligible public page while your application owns extraction and its downstream schema.
Web access API
Current product
Google Search API
Send a contextual Google query and consume documented metadata plus parsed result collections.
Engine-specific SERP response
Interactive retrieval
Browser API
Use a browser-backed REST request with documented waits and interaction steps when Google Search parameters are not the right fit.
Web access API
Operated delivery
Managed Data
Agree the query set, cadence, schema, quality process, and delivery with WebScrapingAPI.
Data program
Production evaluation
Evaluate the complete Google context matrix.
Use representative web and vertical queries, target locales, devices, result windows, optional-module states, empty collections, and unsuccessful HTTP outcomes before selecting a plan.
Workload model
Estimate observations—not keywords alone.
Illustrative request-volume formula
Queries × Contexts × Surfaces × Windows × Frequency
This is a planning model. Current pricing and plan terms remain the commercial source of truth.
Evaluation checklist
Regular web and required vertical queries
Google domain, encoded location, language, and country
Desktop, mobile, and tablet contexts in scope
Pagination windows and optional response modules
HTTP error, timeout, and empty-collection handling
FAQ
Google Search API questions for a grounded evaluation.
Use these answers for product selection, then treat current documentation and representative requests as the implementation source of truth.
What does Google Search API return?
Google Search API returns request context and parsed JSON result collections. Organic results are documented, while navigation and other response modules depend on the query, locale, device, and requested search surface.
Which Google Search parameters can I control?
Use q for the required query. Documented optional controls include tbm, ibp, device, domain, uule, hl, gl, start, and num for search surface, presentation, localization, and pagination.
Which Google search surfaces are documented?
Leave tbm unset for regular web search, or use documented tbm values for images, videos, news, and shopping. Jobs uses the documented ibp control. Validate the returned shape for the surfaces your application needs.
Should every response contain the same result modules?
No. Google result modules vary by query, locale, device, and search vertical. Treat response blocks as optional, distinguish an absent collection from an unsuccessful HTTP request, and read only the modules your application needs.
When should I use google_async?
Use the separately documented google_async engine when your workflow should submit a Google search and retrieve the finished SERP payload through the Snapshot API. The standard google engine is the synchronous request path shown on this page.
How should I integrate Google Search API safely?
Keep api_key in a server-side environment variable, URL-encode query values, set an explicit timeout, and inspect the HTTP status before parsing JSON. Preserve the request context beside stored observations.
Your first Google observation
Test one real query in the context your product depends on.
Start with the synchronous Google engine, validate the returned collections, and keep the request fingerprint with every observation.