1. Bright Data
  2. Proxies & Scraping Infra
  3. SERP API

API

Learn about Bright Data’s API for SERP API, advanced guidelines, and some tips for optimal use.

Note: If you haven't yet set up a SERP API zone see our Quick tutorial guide, to get you up to speed with the basics and ready to move on to some advanced targeting below. 

Sending a Basic API Request with SERP API

Here's an example of the most simple SERP API request using cURL that returns a structured unparsed HTML:

curl --proxy zproxy.brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> -k "https://www.google.com/search?q=pizza"

 Here's a breakdown of the request above:

brd.superproxy.io

 Address of our load balancer that will find the fastest Super Proxy for your request

22225

 Infrastructure port of our Super Proxies that is used to receive your requests

-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME> 

 Username authentication. In its most basic form, it defines your username and what zone you will use for your request. 

<ZONE_PASSWORD> 

 Zone password. All zones have passwords that are used for authentication
"https://www.google.com/search?q=pizza" Replace with your target domain. This is just an example of querying the "pizza" keyword on Google search.

You can find your API credentials including Username (Customer_ID), Zone name, and Password, within your proxy zone’s ‘Access parameters’ tab.

For an in-depth interactive display of all the API use cases, integrations, and preferences, please see our SERP API examples page (you need to be signed in).

Authentication methods

  • Proxy API - When you send a request using your SERP API zone you'll need to use the same type of credentials that we saw above <CUSTOMER_ID> and <ZONE_PASSWORD>.
  • Account management API - When you sent a request regarding managing your account, you'll need to use an API token as your authentication method.

Parsing with SERP API

By default, a SERP API response returns an unparsed structured HTML of the targeted SERP. If you would like to receive a parsed JSON response, add one of the following parameters at the end of your search query: 

    • “&brd_json=1” - Returns a single parsed JSON (instead of a raw HTML) 
      • curl --proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> -k "https://www.google.com/search?q=pizza&brd_json=1"
    • “&brd_json=html” - Returns a single parsed JSON which contains an "html" field (with the raw HTML in addition to the other parsed fields)
       
      • curl --proxy brd.superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> -k "https://www.google.com/search?q=pizza&brd_json=html"
    • Note: Parsing is supported for both Google and Bing search engines

See our parsing article for a deeper look into the types of data we extract from a raw SERP HTML.

Google SERP - Supported Services & features

In addition to Search results, Bright Data's SERP API offers a wealth of data by supporting the targeting of various Google SERP services and features.

Google SERP features that can be targeted: Search, Shopping, Maps, Images, Hotels, Videos, Trends, Reviews, News and Jobs.

Explore below how SERP API supports the targeting of each of these features.

Search

Best for: Extracting traditional search results, including web page titles, URLs, ranking, snippets, widgets, and so much more

Country & Language Targeting

'gl' - Two-letter country code used to define the preferred country for the search

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&gl=us"

'hl' - Two-letter language code used to define the preferred page's language

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&hl=en"

'uule' - Stands for the encoded location you want to use for your search and will be used to change geo-location. A CSV with all available uule values can be downloaded here.

The value of column "Canonical Name" from the CSV can be used as a raw string to the API

Example: &uule=New+York,New+York,United+States

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&uule=w+CAIQICINVW5pdGVkK1N0YXRlcw"

Search Results Customization

'start' - Define the result offset - results to start from the selected value.

  • 'start=0' (default) - first page of results
  • 'start=10' - second page of results
  • 'start=20' - third page of results, etc.

    curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&start=10"

'num' - Defines the number of Search results to return.

  • 'num=10' (default) - returns 10 results
  • 'num=100' - returns 100 results 
    curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&num=100"

A note re 'num' support: Due to some recent changes made by Google to their Search results and their potential effect on the 'num' parameter, we created a backup feature to ensure continuous support of 'num' in the event that Google drops support for 'num' in the future. Learn more about it and see how to activate it. 

Shopping

Best for: Accessing Google product listings, prices, reviews, and availability to facilitate e-commerce research and analysis.

'tbm=shop' -  Simply add this parameter to the end of your search query to retrieve Google "Shopping" results

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=transformers&tbm=shop"

Maps

Best for: Gathering data on locations, addresses, businesses, reviews, and directions for mapping and location-based services.

Country & Language Targeting

'gl' - Two-letter country code used to define the preferred country for the "Maps" search

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/maps/search/hotels+new+york/?gl=us"

'hl' - Two-letter language code used to define the "Maps" page's language

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/maps/search/hotels+new+york/?hl=enw+york/?gl=us"

Maps Search Results Customization

'start' - Define the result offset - results to start from the selected value.

  • 'start=0' (default) - first page of results
  • 'start=10' - second page of results
  • 'start=20' - third page of results, etc.
     
    curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/maps/search/hotels+new+york/?start=20"

'num' - Defines the number of Maps results to return.

Parsing

Similar to Search above- by default, a SERP API request returns an unparsed structured HTML of the targeted SERP. If you would like to receive a parsed JSON response, add one of the following parameters at the end of your Google Maps Search query: 

  • “&brd_json=1” - Returns a single parsed JSON (instead of a raw HTML)
  • “&brd_json=html” - Returns a single parsed JSON which contains an "html" field (with the raw HTML in addition to the other parsed fields)

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/maps/search/hotels+new+york/?brd_json=1"

Images

Best for: Extracting image search results, including the actual image files, titles, descriptions, and image URLs.

'tbm=isch'  - Simply add this parameter to the end of your search query to retrieve Google "Images" results

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&tbm=isch"

'download' - Download image on the proxy side and post it to Google using POST request

  • default - download-and-post if google isn't able to download the image
  • 'download=1' - force download-and-post image
  • 'download=0' - regular GET request with image URL
curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/searchbyimage?image_url=https%3A%2F%2Flive.staticflickr.com%2F213%2F491726079_4f46636859_w.jpg&download=1”

Search by Image

SERP API supports Google reverse image search (officially "Google Search by Image"). See our guide on how to search by image.

Hotels

Best for: Retrieving hotel-related information such as hotel names, pricing, ratings, availability, and reviews within the hotel industry and travel research from Google Travel (google.com/travel)

Please note: In order to target Hotels and data with Google Travel, you need to enable the "Allow hotel requests" feature within your SERP API zone on the control panel 

Occupancy

'hotel_occupancy' -  Number of guests to book a room for (up to 4).

  • hotel_occupancy=1 - for 1 guest
  • hotel_occupancy=2 (default) - for 2 guests
curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&hotel_occupancy=4"

Dates

'hotel_dates' - Check-in date and check-out date. It should be separated by a comma ",".

Format: YYYY-MM-DD,YYYY-MM-DD

Examples:

Videos

Best for: Access video search results, including video titles, descriptions, and video URLs.

'tbm=vid'  - Simply add this parameter to the end of your search query to retrieve Google "Videos" results

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=transformers&tbm=vid"

Trends

Best for: Monitoring the popularity and search volume trends of specific topics over time to gain valuable insights into market trends and user interests from Google Trends (google.com/trends)

Country & Language Targeting

'geo' - Two-letter country code used to define the preferred country for the "Trends" search

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/trends/explore?q=pizza&geo=us"

'hl' - Two-letter language code used to define the "Maps" page's language

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/trends/explore?q=pizza&hl=de"

Date Range

'date'  - Time range to search. Available values are:

  • now 1-H - Past hour
  • now 4-H - Past 4 hours
  • now 1-d - Past day
  • now 7-d - Past 7 days
  • today 1-m - Past 30 days
  • today 3-m - Past 90 days
  • today 12-m (default) - Past 12 months
  • today 5-y - Past 5 years
  • 2020-07-01 2020-12-31 - custom date range
curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://trends.google.com/trends/explore?q=pizza&date=now+1-d"

Category

'cat' - Category to search within. By default, search within all categories.

You can find list of all the numeric categories here.

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://trends.google.com/trends/explore?q=pizza&cat=3"

Property

'gprop' - Google property to filter on. Defaults to Google Search.

Values: images, news, froogle (for Google Shopping), youtube

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://trends.google.com/trends/explore?q=pizza&gprop=images"

Reviews

Best for: Gathering customer reviews and ratings for businesses, products, or services to assess reputation and sentiment analysis.

'fid' - Feature id what you want to fetch reviews to.

fid parameter can be found in knowledge.fid field of google search response. For example: https://www.google.com/search?q=hilton%20new%20york%20midtown

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/reviews?fid=0x808fba02425dad8f%3A0x6c296c66619367e0"

Language

'hl' - Preferred language, two-letter language code

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/reviews?fid=0x808fba02425dad8f%3A0x6c296c66619367e0&hl=de"

Sort

'sort' - The way reviews are sorted. Possible values are:

  • sort=qualityScore (default) - most relevant first
  • sort=newestFirst - newest first
  • sort=ratingHigh - highest rating first
  • sort=ratingLow - lowest rating first
curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/reviews?fid=0x808fba02425dad8f%3A0x6c296c66619367e0&sort=newestFirst"

Filter

'filter' - Filter keyword. Will respond with reviews that contain specified keywords only. Example:

filter=awesome - search for reviews containing the 'awesome' word

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/reviews?fid=0x808fba02425dad8f%3A0x6c296c66619367e0&filter=awesome"

Start

'start' - Define the result offset - results to start from the selected value.

  • start=0 (default) - first page of results
  • start=10 - second page of results
  • start=20 - third page of results, etc.
curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/reviews?fid=0x808fba02425dad8f%3A0x6c296c66619367e0&start=10"

News

Best for: Extracting news articles, headlines, publishers, dates, and URLs to stay updated on the latest news and developments.

'tbm=nws'- Simply add this parameter to the end of your search query to retrieve Google "News" results

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=Yankees&tbm=nws"

Jobs

Best for: Accessing job listings, titles, descriptions, companies, locations, and application details for employment research and recruitment purposes.

'ibp=htl;jobs' - Simply add this parameter to the end of your search query to retrieve Google "Jobs" results

curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>:<ZONE_PASSWORD> ”https://www.google.com/search?q=pizza&ibp=htl%3Bjobs"

 

Was this article helpful?