Get started with Search Researcher Result (SRR) API

Important: This API is currently only available for researchers based in the European Union (EU).

Approved researchers can obtain results from Google Search with the Search Researcher Result (SRR) API. To learn more about the Researcher Program, go to the Researcher Program website.

What you need to use SRR API

To send a request to the SRR API, you need these 3 items:

• A Google Account that’s approved for access
• The Research Product ID that was provided in the application approval email
• A request string of the path page you want to scrape, which begins with “/search?”.

About the Search Researcher Result API (SRR API)

Approved researchers can send search requests to Google Search and retrieve responses with the Search Researcher Result API (SRR API). The SRR API is an authenticated API that grants each research project a given number of requests per day. The responses returned are nearly the same as a standard HTTP request sent from a browser.

Get started with the SRR API in OAuth Playground

You can verify access and explore send requests with the OAuth Playground. The OAuth tokens and authorization codes from the OAuth Playground are available for a short time, as documented in the tool. While you can continue to refresh the tokens, it’s recommended to write your own application if you plan to use the API for a longer time.

Step 1: Open a project

1. Sign in to the Google Account that was used to request access to the Search Researcher Result API.
2. To begin, you must be approved to use the Search Researcher Result API and have received an email with the Project ID.
3. Go to https://console.cloud.google.com.
4. If displayed, accept the Google Cloud Console Terms of Services.
5. At the top left, click Select a project.
   1. To create a new project:
      1. At the top right of the pop-up window, click NEW PROJECT.
      2. Enter a name for the project.
      3. Select the location you want to place the project.
      4. At the bottom right, click Create.
   2. To select an existing project:
      1. To find the project you want to open, use the search bar or navigate the folder.
      2. Click the project that you want.
      3. At the bottom right, click Open.

Step 2: Set up the Search Researcher Result API

1. In a new tab, go to https://console.cloud.google.com/apis/library/searchresearcherresults.googleapis.com.
2. To turn on the Search Researcher Result API, click Enable.

Step 3: Authorize the Search Researcher Result API

1. In a new tab, go to https://developers.google.com/oauthplayground.
2. In the section “Step 1 Select & Authorize APIs,” enter this string in the text field: “https://www.googleapis.com/auth/searchresearcherresults.researcherProject.readonly”.
3. At the bottom right, click Authorize APIs.
4. In the screen that displays, click Allow.
5. Click Exchange authorization code for tokens.

Step 4: Send an API request

1. From the application approval email you received, copy your Project ID.
2. In the section “Step 3 Configure request to API,” set the parameters:
   • HTTP Method = POST Request
   • Request URI = "https://searchresearcherresults.googleapis.com/v1/researcherprojects/{ADD YOUR PROJECT ID HERE}:runQuery"

3. Click Enter request body and enter your query parameters “Request Body,” with the format "query": "/search?q={ADD YOUR QUERY HERE}".
   Tip: For more information on how to format queries, go to How to format queries.

4. Click Send the Request.
5. In the left panel, check your result:
   • If the request is successful, the result begins with “HTTP/ 1.1 200 OK”.
   • If the request is unsuccessful, the result begins with “HTTP/ 1.1 403 FORBIDDEN”. Make sure you’re signed in with the same Google Account that was used to request access to the Search Researcher Result API.

Format queries & interpret results

The SRR API accepts up to 1000 requests a day per project. Once 1000 requests have been sent, the API returns an error. If you send too many requests from your project in a short time, you may also temporarily receive “resource exhaustion” errors.

How to format queries

The API expects one input field named query. The query field value must include the path of the search page you want to use. For example, If you want to search “Google” use the value /search?q=google to create the query https://www.google.com/search?q=google.

You can access the API with a curl request like this:

curl -H "Content-type: application/json" \

 -H "Authorization: Bearer {OAuth Credential}" \

 -d '{"query": "/search?q=google"}' -X POST \

 https://searchresearcherresults.googleapis.com/v1/researcherprojects/1234:runQuery

• Replace {OAuth Credential} with an OAuth token.
• Replace the number 1234 with your Project ID. 

If your query is successful, you’ll find a response like this in the htmlContent field:

{

 "htmlContent": "\u003c!doctype html\u003e\u003chtml itemscope=\"\"itemtype=\"http://schema.org/SearchResultsPage\"

 ..."

}

Request parameter examples

Most requests that a browser makes to www.google.com with a path of /search? are supported with the same parameters that a browser issues through HTTP.

Common parameters include:

• &q= Query to execute a search for
• &gl= Specify a country or region
• &hl= Specify a language
• &start= Specify results past page one
• &tbm= Specify a search mode:

  • Supported values are isch, vid,bks, nws

About the format of query results

• The SRR API returns a response in the htmlContent field. The HTML in the SRR response is the same as a request that originates from a browser. If you want to render the response in a browser, Chrome browser is the most compatible.
• When the response is rendered in a browser, some content that may be included in the response doesn’t display on the page. The content that doesn’t display in the browser includes external Javascript and some images.

• You can extract the content you want to use from either the HTML result or the page rendered in the browser.

Tip: Although SRR API requests are authenticated with your Google Account, your account information isn’t used to generate the HTML of the returned results page. The results page reflects a signed-out experience.