Skip to main content

​
Google Header Parameters

The Bright Data SERP API accepts the following parameters to control the format of Google search responses.

​
Parsing

ParameterTypeRequiredDefaultAccepted values
brd_jsonstringNonone1, html
x-unblock-data-formatHTTP headerNononeparsed_light

​
Raw HTML

Default response format. No additional parameter is required. 
curl --proxy brd.superproxy.io:33335 --proxy-user brd-customer-<customer-id>-zone-<zone-name>:<zone-password> "https://www.google.com/search?q=pizza"

​
brd_json

ValueResponse
brd_json=1Parsed JSON
brd_json=htmlParsed JSON with an additional "html" field containing the raw HTML
  curl --proxy brd.superproxy.io:33335 --proxy-user brd-customer-<customer-id>-zone-<zone-name>:<zone-password> "https://www.google.com/search?q=pizza&brd_json=1"
For the full JSON response schema and field descriptions, see Parsed JSON results.

​
x-unblock-data-format: parsed_light

ValueResponse
parsed_lightParsed JSON limited to top 10 organic results, approximately 50% lower latency than full JSON parsing
curl -k --proxy brd.superproxy.io:33335 --proxy-user brd-customer-<customer_id>-zone-<zone_name>:<zone_password> -H "x-unblock-data-format: parsed_light" "https://www.google.com/search?q=pizza"

​
x-unblock-data-format: screenshot, html, parsed

ValueResponse

combination of: screenshot,html,parsed

Zip archive with multiple response formats bundled together
curl -k --proxy brd.superproxy.io:33335 --proxy-user brd-customer-<customer_id>-zone-<zone_name>:<zone_password> -H "x-unblock-data-format: screenshot,html,parsed" "https://www.google.com/search?q=pizza"

​
Request Headers

The following headers can be passed with your SERP API requests to control behavior, session pinning, output format, and more.
HeaderAvailabilityPurpose
x-brd-expectZones with custom_expect permissionCustom success/failure validation criteria for response content
x-brd-data-formatAllControls output format: parsed, screenshot, json, extract-network, etc.
x-brd-url-fragmentAll (browser step)Appends a URL fragment (#...) to the request URL for browser rendering
x-brd-sessionAllSets a customer session ID to pin requests to the same peer/IP
x-request-priorityAllRequest priority hint - may influence internal routing decisions
x-brd-get-rate-limitAllWhen present, response includes current rate limit info headers
cookieZones with cookie_whitelist or header_whitelist containing cookieCustomer cookies forwarded to target site (filtered by whitelist)
Any header in header_whitelist ruleZones with cust_head permissionCustom headers forwarded verbatim to the target site

​
Examples

Pin requests to the same IP with x-brd-session: 
curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:33335 \
  -H 'x-brd-session: my-session-123' \
  "https://www.google.com/search?q=bright+data"
Control output format with x-brd-data-format: 
curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:33335 \
  -H 'x-brd-data-format: json' \
  "https://www.google.com/search?q=bright+data"
Wait for a specific element with x-brd-expect (requires custom_expect permission): 
curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:33335 \
  -H 'x-brd-expect: {"element": "#search"}' \
  "https://www.google.com/search?q=bright+data"
Append a URL fragment with x-brd-url-fragment: 
curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:33335 \
  -H 'x-brd-url-fragment: !/results/section2' \
  "https://www.google.com/search?q=bright+data"
Get rate limit info with x-brd-get-rate-limit: 
curl -vk \
  -x brd-customer-$CUSTOMER_ID-zone-$ZONE:$PASSWORD@brd.superproxy.io:33335 \
  -H 'x-brd-get-rate-limit: true' \
  "https://www.google.com/search?q=bright+data"