Google SERP features

Configure Bright Data SERP API (31 languages) features including response format, parsing options and header overrides for Google search results.

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:

SERP API

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'

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:

1. Getting rectangle data will increase response time. Expect response time to range between 5 seconds to 60 seconds per request.
2. 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:$[e-mail]: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:$[e-mail]: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:$[e-mail]: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:$[e-mail]: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:$[e-mail]: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