How to Invoke the API

This document describes how to invoke the Web Search Service API using REST.

Make a request

To retrieve search results, send an HTTP GET request to the service URI with search parameters passed as query parameters.

The format for the URI is: none https://websearchservice.googleapis.com/v1:search?[parameters]

Three query parameters are required with each search request:

  • Client ID - Set clientContext.clientId to the designated partner client ID (e.g., example-client-id).
  • End User IP - Set userContext.ipAddress for regional routing and abuse prevention (e.g., 192.168.1.1).
  • Search query - Set searchQuery.query to the target search expression.

All other query parameters are optional.

Example curl Request

curl -X GET \
  -H "X-Goog-Api-Key: YOUR_API_KEY" \
  "https://websearchservice.googleapis.com/v1:search?searchQuery.query=google+cloud&clientContext.clientId=example-client-id&userContext.ipAddress=192.168.1.1&pageSize=10"

Query parameters

For the complete list and definitions of all available query parameters (such as pageSize, safe search, and date filters), see the REST reference.

Response data

If the request succeeds, the server returns a 200 OK HTTP status code and search results in JSON format (SearchResponse).

For the complete schema and field descriptions of the response data, see the REST reference.