Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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
ParameterTypeRequiredDefaultAccepted values
brd_jsonURLNonone1, html
x-unblock-data-formatHTTP headerNononeparsed_light, html, screenshot

​
Get response as raw HTML

Add header paramater: x-unblock-data-format: html . Example: 
curl --proxy brd.superproxy.io:33335 --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 paramater: x-unblock-data-format: jsonor add URL parameter: brd_json=1. Examples:
Header parameter
curl -k --proxy brd.superproxy.io:33335 --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:33335 --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 structue 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:33335 --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 than Full SERP) with less componenets. Full schema documentation can be seen here: https://docs.brightdata.com/scraping-automation/serp-api/parsed-json-results/parsing-search-results#google-response-schema-light-json Examples:
Header parameter
curl -k --proxy brd.superproxy.io:33335 --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:33335 --proxy-user brd-customer-<customer_id>-zone-<zone_name>:<zone_password> -k -H  "https://www.google.com/search?q=pizza&brd_json=parsed_light"

​
Get response as screenshot

Add header paramater: 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:33335 --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

​
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 elememt. 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:$PASSWORD@brd.superproxy.io:33335 \ 
 "https://www.google.com/search?q=bright+data&brd_json=1&brd_rects=1"

​
Routing configuration

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:33335 \
  -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:33335 \
  -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:33335 \
  -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:33335 \
  -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 parameterAvailabilityPurpose
x-brd-expectZones with custom_expect permissionCustom success/failure validation criteria for response content
x-unblock-data-formatAllControls output format: json, html, light_json, screenshot, parsed
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
brd_rects=1AllShow element rectangle data