Google SERP features

Parsing and response format configuration

You can control and override the default API response format setup defined during API creation in Bright Data control panel. We allow either override by URL parameter brd_json or by relaying a header x-unblock-data-format

Parameter	Type	Required	Default	Accepted values
`brd_json`	URL	No	none	`1`, `html`
`x-unblock-data-format`	HTTP header	No	none	`parsed_light, html, screenshot`

Get response as raw HTML

Add header parameter: x-unblock-data-format: html. Example:

curl --proxy brd.superproxy.io:44445 --proxy-user  brd-customer-<customer-id>-zone-<zone-name>:<zone-password> -k -H "x-unblock-data-format: html" "https://www.google.com/search?q=pizza"

Get response as Full JSON

Add header parameter: x-unblock-data-format: jsonor add URL parameter: brd_json=1. Examples:

Header parameter

curl -k --proxy brd.superproxy.io:44445 --proxy-user brd-customer-<customer_id>-zone-<zone_name>:<zone_password> -k -H "x-unblock-data-format: json" "https://www.google.com/search?q=pizza"

URL Parameter

  curl --proxy brd.superproxy.io:44445 --proxy-user brd-customer-<customer-id>-zone-<zone-name>:<zone-password> -k "https://www.google.com/search?q=pizza&brd_json=1"

Get Full JSON with a structure holding the full HTML as `string`

Add URL parameter: brd_json=html or header parameter: x-unblock-data-format: html Example:

JSON+HTML

  curl --proxy brd.superproxy.io:44445 --proxy-user brd-customer-<customer-id>-zone-<zone-name>:<zone-password> -k "https://www.google.com/search?q=pizza&brd_json=html"

Get light JSON

Add header parameter: x-unblock-data-format: parsed_light or URL parameter brd_json=parsed_light to get a faster response (works twice as fast as Full SERP) with fewer components. Full schema documentation can be seen here: https://docs.brightdata.com/products/serp-api/parsed-json-results#google-response-schema-light-json Examples:

Header parameter

curl -k --proxy brd.superproxy.io:44445 --proxy-user brd-customer-<customer_id>-zone-<zone_name>:<zone_password> -k -H "x-unblock-data-format: parsed_light" "https://www.google.com/search?q=pizza"

URL parameter

curl -k --proxy brd.superproxy.io:44445 --proxy-user brd-customer-<customer_id>-zone-<zone_name>:<zone_password> -k "https://www.google.com/search?q=pizza&brd_json=parsed_light"

Get response as screenshot

Add header parameter: x-unblock-data-format: screenshot . Response will be a binary PNG image. In the example below add --output flag to curl to capture response to image file. Example:

curl --proxy brd.superproxy.io:44445 --proxy-user brd-customer-<customer-id>-zone-<zone-name>:<zone-password> -k -H "x-unblock-data-format: screenshot" "https://www.google.com/search?q=pizza" --output screenshot.png

Automatic search query optimization

Bright Data can automatically optimize eligible Google Search queries before sending them to Google. These adjustments are designed to improve request success while preserving the original search intent. This optional feature is supported by both SERP API and Fast SERP. Because optimization behavior may evolve, some queries may be adjusted while others are sent unchanged.

Native proxy

Enable automatic query optimization by adding the x-unblock-search-rewrite: on request header:

curl --proxy brd.superproxy.io:44445 \
  --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> \
  -k \
  -H 'x-unblock-search-rewrite: on' \
  -H 'x-unblock-data-format: json' \
  'https://www.google.com/search?q=latest+technology+news'

curl --proxy fserp.brd.superproxy.io:44445 \
  --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> \
  -k \
  -H 'x-unblock-search-rewrite: on' \
  -H 'x-unblock-data-format: parsed_light' \
  'https://www.google.com/search?q=latest+technology+news&brd_json=1'

API request

When using the Bright Data API, add "search_rewrite": true to the JSON request body:

curl -X POST 'https://api.brightdata.com/request' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "zone": "<ZONE_NAME>",
    "url": "https://www.google.com/search?q=latest+technology+news",
    "format": "raw",
    "data_format": "parsed_light",
    "search_rewrite": true
  }'

Parsed response fields

When automatic query optimization is enabled, use these fields to understand which query produced the response:

Field	Description
`general.query`	The effective query Bright Data sent to Google after applying any eligible optimization
`general.detected_query`	The query Bright Data detected that Google returned results for
`spelling`	Google’s displayed spelling correction or suggestion, such as a “Did you mean” prompt, when present

If your application needs the original query exactly as submitted, retain it in your application. In parsed responses, general.query contains the effective query sent to Google.

For information about comparing general.query and general.detected_query, see How to detect query truncation.

Get element rectangle information BETA

Add URL parameter brd_rects=1 in order to get results rectangle area as displayed on search result screen. This allows you to know when, in relation to viewport (which signifies screen resolution used to render the page) how much space does the result take on the visible screen.viewport (screen size) can be found in general element. Notes:

Getting rectangle data will increase response time. Expect response time to range between 5 seconds to 60 seconds per request.
In BETA version you must also relaybrd_json=1 URL parameter in addition to brd_rects=1 .

Response elements which have rectangle information:

organic
videos
images
people_also_ask
ai_overview
related_searches
perspectives
forums
pagination
latest_posts

Example:

curl -vx \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:44445 \ 
 "https://www.google.com/search?q=bright+data&brd_json=1&brd_rects=1"

How to configure routing

Pin requests to the same IP with x-brd-session. This feature will attempt to keep the same proxy IP address which was used previously.

curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:44445 \
  -H 'x-brd-session: my-session-123' \
  "https://www.google.com/search?q=bright+data"

Page Load configuration

Wait for a specific element with x-brd-expect (requires custom_expect permission). Use this option in order to prevent premature response, and wait till specific element is rendered by google.

curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:44445 \
  -H 'x-brd-expect: {"element": "#search"}' \
  "https://www.google.com/search?q=bright+data"

URL Control configuration

Append a URL fragment with x-brd-url-fragment: Use this option if you need to maintain a base URL address, and append a suffix by your logic.

curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:44445 \
  -H 'x-brd-url-fragment: !/results/section2' \
  "https://www.google.com/search?q=bright+data"

Get current rate limit

Get rate limit info with x-brd-get-rate-limit: Get current target website rate limit, response is

curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:44445 \
  -H 'x-brd-get-rate-limit: true' \
  "https://www.google.com/search?q=bright+data"   

Request Headers: Summary

The following headers can be passed with your SERP API requests to control behavior, session pinning, output format, and more.

Header or URL parameter	Availability	Purpose
`x-brd-expect`	Zones with `custom_expect` permission	Custom success/failure validation criteria for response content
`x-unblock-data-format`	All	Controls output format: `json, html, light_json, screenshot, parsed`
`x-brd-url-fragment`	All (browser step)	Appends a URL fragment (`#...`) to the request URL for browser rendering
`x-brd-session`	All	Sets a customer session ID to pin requests to the same peer/IP
`x-request-priority`	All	Request priority hint - may influence internal routing decisions
`x-brd-get-rate-limit`	All	When present, response includes current rate limit info headers
`cookie`	Zones with `cookie_whitelist` or `header_whitelist` containing `cookie`	Customer cookies forwarded to target site (filtered by whitelist)
Any header in `header_whitelist` rule	Zones with `cust_head` permission	Custom headers forwarded verbatim to the target site
`brd_rects=1`	All	Show element rectangle data
`x-unblock-search-rewrite`	SERP API and Fast SERP	Set to `on` to allow Bright Data to optimize eligible search queries before sending them
`search_rewrite`	SERP API JSON requests	Set to `true` in the JSON request body to allow Bright Data to optimize eligible search queries before sending them

Get started

Data extraction

Web access

AI training data

Proxy networks

Parsing and response format configuration

Get response as raw HTML

Get response as Full JSON

Get Full JSON with a structure holding the full HTML as `string`

Get light JSON

Get response as screenshot

Automatic search query optimization

Native proxy

API request

Parsed response fields

Get element rectangle information BETA

How to configure routing

Page Load configuration

URL Control configuration

Get current rate limit

Request Headers: Summary

​Parsing and response format configuration

​Get response as raw HTML

​Get response as Full JSON

​Get Full JSON with a structure holding the full HTML as string

​Get light JSON

​Get response as screenshot

​Automatic search query optimization

​Native proxy

​API request

​Parsed response fields

​Get element rectangle information BETA

​How to configure routing

​Page Load configuration

​URL Control configuration

​Get current rate limit

​Request Headers: Summary

Parsing and response format configuration

Get response as raw HTML

Get response as Full JSON

Get Full JSON with a structure holding the full HTML as `string`

Get light JSON

Get response as screenshot

Automatic search query optimization

Native proxy

API request

Parsed response fields

Get element rectangle information BETA

How to configure routing

Page Load configuration

URL Control configuration

Get current rate limit

Request Headers: Summary