Ads | Oxylabs Documentation

The google_ads source is optimized to retrieve Google Search results page (SERP) with paid ads. This source will return only ten results per page, ensuring the highest chances of paid results showing up. Other than that, it supports the same parameters as regular Web Search.

Request samples

In this example, we make a request to google.nl to retrieve search results for the keyword adidas.

curl 'https://realtime.oxylabs.io/v1/queries' \
--user 'USERNAME:PASSWORD' \
-H 'Content-Type: application/json' \
-d '{
        "source": "google_ads", 
        "domain": "nl", 
        "query": "adidas",
        "parse": true
    }'

import requests
from pprint import pprint


# Structure payload.
payload = {
    'source': 'google_ads',
    'domain': 'nl',
    'query': 'adidas',
    'parse': True
}


# Get response.
response = requests.request(
    'POST',
    'https://realtime.oxylabs.io/v1/queries',
    auth=('USERNAME', 'PASSWORD'),
    json=payload,
)

# Print prettified response to stdout.
pprint(response.json())

const https = require("https");

const username = "USERNAME";
const password = "PASSWORD";
const body = {
    source: "google_ads",
    domain: "nl",
    query: "adidas",
    parse: true,
};

const options = {
    hostname: "realtime.oxylabs.io",
    path: "/v1/queries",
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        Authorization:
            "Basic " + Buffer.from(`${username}:${password}`).toString("base64"),
    },
};

const request = https.request(options, (response) => {
    let data = "";

    response.on("data", (chunk) => {
        data += chunk;
    });

    response.on("end", () => {
        const responseData = JSON.parse(data);
        console.log(JSON.stringify(responseData, null, 2));
    });
});

request.on("error", (error) => {
    console.error("Error:", error);
});

request.write(JSON.stringify(body));
request.end();

https://realtime.oxylabs.io/v1/queries?source=google_ads&domain=nl&query=adidas&parse=true&access_token=12345abcde

<?php

$params = array(
    'source' => 'google_ads',
    'domain' => 'nl',
    'query' => 'adidas',
    'parse' => true
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://realtime.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "USERNAME" . ":" . "PASSWORD");


$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	const Username = "USERNAME"
	const Password = "PASSWORD"

	payload := map[string]interface{}{
		"source": "google_ads",
		"domain": "nl",
		"query":  "adidas",
		"parse":  true,
	}

	jsonValue, _ := json.Marshal(payload)

	client := &http.Client{}
	request, _ := http.NewRequest("POST",
		"https://realtime.oxylabs.io/v1/queries",
		bytes.NewBuffer(jsonValue),
	)

	request.SetBasicAuth(Username, Password)
	response, _ := client.Do(request)

	responseText, _ := ioutil.ReadAll(response.Body)
	fmt.Println(string(responseText))
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace OxyApi
{
    class Program
    {
        static async Task Main()
        {
            const string Username = "USERNAME";
            const string Password = "PASSWORD";

            var parameters = new {
                source = "google_ads",
                domain = "nl",
                query = "adidas",
                parse = true
            };

            var client = new HttpClient();

            Uri baseUri = new Uri("https://realtime.oxylabs.io");
            client.BaseAddress = baseUri;

            var requestMessage = new HttpRequestMessage(HttpMethod.Post, "/v1/queries");
            requestMessage.Content = JsonContent.Create(parameters);

            var authenticationString = $"{Username}:{Password}";
            var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
            requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);

            var response = await client.SendAsync(requestMessage);
            var contents = await response.Content.ReadAsStringAsync();

            Console.WriteLine(contents);
        }
    }
}

package org.example;

import okhttp3.*;
import org.json.JSONObject;
import java.util.concurrent.TimeUnit;

public class Main implements Runnable {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String USERNAME = "USERNAME";
    public static final String PASSWORD = "PASSWORD";

    public void run() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("source", "google_ads");
        jsonObject.put("domain", "nl");
        jsonObject.put("query", "adidas");
        jsonObject.put("parse", true);

        Authenticator authenticator = (route, response) -> {
            String credential = Credentials.basic(USERNAME, PASSWORD);
            return response
                    .request()
                    .newBuilder()
                    .header(AUTHORIZATION_HEADER, credential)
                    .build();
        };

        var client = new OkHttpClient.Builder()
                .authenticator(authenticator)
                .readTimeout(180, TimeUnit.SECONDS)
                .build();

        var mediaType = MediaType.parse("application/json; charset=utf-8");
        var body = RequestBody.create(jsonObject.toString(), mediaType);
        var request = new Request.Builder()
                .url("https://realtime.oxylabs.io/v1/queries")
                .post(body)
                .build();

        try (var response = client.newCall(request).execute()) {
            if (response.body() != null) {
                try (var responseBody = response.body()) {
                    System.out.println(responseBody.string());
                }
            }
        } catch (Exception exception) {
            System.out.println("Error: " + exception.getMessage());
        }

        System.exit(0);
    }

    public static void main(String[] args) {
        new Thread(new Main()).start();
    }
}

{
    "source": "google_ads", 
    "domain": "nl", 
    "query": "adidas",
    "parse": true
}

We use synchronous Realtime integration method in our examples. If you would like to use Proxy Endpoint or asynchronous Push-Pull integration, refer to the integration methods section.

Request parameter values

Generic

Basic setup and customization options for scraping Google ads.

Parameter Description Default Value

Parameter	Description	Default Value
source	Sets the scraper.	`google_ads`
query	UTF-encoded keyword.	-
`render`	Enables JavaScript rendering when set to `html`. More info.	-
`parse`	Returns parsed data when set to `true`. Explore output data dictionary.	`false`
`callback_url`	URL to your callback endpoint. More info.	-
`user_agent_type`	Device type and browser. The full list can be found here.	`desktop`

source

Sets the scraper.

google_ads

query

UTF-encoded keyword.

render

Enables JavaScript rendering when set to html. More info.

parse

Returns parsed data when set to true. Explore output data dictionary.

false

callback_url

URL to your callback endpoint. More info.

user_agent_type

Device type and browser. The full list can be found here.

desktop

- mandatory parameter

Localization

Adapt search results to specific geographical locations, domains, and languages.

Parameter Description Default Value

Parameter	Description	Default Value
`geo_location`	The geographical location that the result should be adapted for. Using this parameter correctly is extremely important to get the right data. For more information, read about our suggested `geo_location` parameter structures here.	-
`domain`	Domain localization for Google. The full list of available domains can be found here.	`com`
`locale`	`Accept-Language` header value which changes your Google search page web interface language. More info.	-
`context`: `results_language`	Results language. List of supported Google languages can be found here.	-

geo_location

The geographical location that the result should be adapted for. Using this parameter correctly is extremely important to get the right data. For more information, read about our suggested geo_location parameter structures here.

domain

Domain localization for Google. The full list of available domains can be found here.

com

locale

Accept-Language header value which changes your Google search page web interface language. More info.

context: results_language

Results language. List of supported Google languages can be found here.

Pagination

Controls for managing the pagination and retrieval of search results.

Parameter Description Default Value

Parameter	Description	Default Value
`start_page`	Starting page number.	`1`
`pages`	Number of pages to retrieve.	`1`

start_page

Starting page number.

1

pages

Number of pages to retrieve.

1

Filtering

Options to filter and refine search results based on various criteria.

Parameter Description Default Value

Parameter	Description	Default Value
`context`: `udm`	`udm` parameter allows switching between different search tabs, such as images, places, or videos, to customize the type of results displayed. Find the accepted values here.	-
`context`: `tbm`	To-be-matched or `tbm` parameter. Accepted values are: `app`, `blg`, `bks`, `dsc`, `isch`, `nws`, `pts`, `plcs`, `rcp`, `lcl`	-
`context`: `tbs`	`tbs` parameter. This parameter is like a container for more obscure google parameters, like limiting/sorting results by date as well as other filters some of which depend on the `tbm` parameter (e.g. `tbs=app_os:1` is only available with `tbm` value `app`). More info here.	-

context:

udm

udm parameter allows switching between different search tabs, such as images, places, or videos, to customize the type of results displayed. Find the accepted values here.

context: tbm

To-be-matched or tbm parameter. Accepted values are: app, blg, bks, dsc, isch, nws, pts, plcs, rcp, lcl

context: tbs

tbs parameter. This parameter is like a container for more obscure google parameters, like limiting/sorting results by date as well as other filters some of which depend on the tbm parameter (e.g. tbs=app_os:1 is only available with tbm value app). More info here.

Other

Additional advanced settings and controls for specialized requirements.

Parameter Description Default Value

Parameter	Description	Default Value
`context`: `nfpr`	`true` will turn off spelling auto-correction	`false`

context: nfpr

true will turn off spelling auto-correction

false

Context parameters

All context parameters should be added to the context array as objects with key and value pairs, e.g.:

...
"context": [
    {
        "key": "filter",
        "value": "0"
    }
]
...

Structured data

google_ads structured output

{
    "results": [
      {
        "content": {
          "url": "https://www.google.nl/search?q=adidas&uule=w+CAIQICILbmV0aGVybGFuZHM&gl=nl&hl=nl",
          "page": 1,
          "results": {
            "paid": [
              {
                "pos": 1,
                "url": "https://www.adidas.nl/",
                "desc": "Verhalen, looks en sportkleding bij adidas® Sinds 1949. Ontdek de officiële adidas® shop. Of je nu sport of relaxt, geef een boost aan je prestaties en stijl in de adidas® shop.",
                "title": "Officiële shop adidas® - Klassiekers & exclusieve items",
                "data_rw": "https://www.google.nl/aclk?sa=l&ai=DChcSEwiWl6aS-6uBAxWXkmgJHZLLC74YABAAGgJ3Zg&gclid=EAIaIQobChMIlpemkvurgQMVl5JoCR2Sywu-EAMYASAAEgJRofD_BwE&sig=AOD64_2CbsJk2pXa0T2IqTfvVb1wKZvM8g&q&adurl",
                "sitelinks": {
                  "inline": [
                    {
                      "url": "https://www.adidas.nl/dames?grid=true",
                      "title": "adidas® Dames"
                    },
                    {
                      ...
                    }
                  ]
                },
                "url_shown": "https://www.adidas.nl",
                "pos_overall": 10
              }
            ],
            "images": {
              "items": [
                {
                  "alt": "adidas Forum Low Schoenen - Wit | adidas Officiële Shop",
                  "pos": 1,
                  "source": "https://www.adidas.nl/forum-low-schoenen/FY7756.html"
                },
                {
                  ...
                }
              ],
              "pos_overall": 5
            },
            "organic": [
              {
                "pos": 1,
                "url": "https://www.adidas.nl/",
                "desc": "Sportwinkel voor adidas schoenen en kleding. Shop o.a. Originals, Voetbal, Hardlopen en gym artikelen op de officiële adidas NL website.",
                "title": "adidas Officiële Website Nederland | Sportwinkel",
                "sitelinks": {
                  "expanded": [
                    {
                      "url": "https://www.adidas.nl/outlet",
                      "title": "Outlet"
                    },
                    {
                      ...
                    },
                    {
                      "url": "https://www.adidas.nl/kinderen",
                      "title": "Kinderen"
                    }
                  ]
                },
                "url_shown": "https://www.adidas.nl",
                "pos_overall": 1
              },
              {
                ...
              },
              {
                "pos": 7,
                "url": "https://www.jdsports.nl/merk/adidas-originals/",
                "desc": "De volledige adidas Originals collectie bij JD Sports Nederland. adidas Originals trainingspak, slippers & sneakers in exclusieve kleuren.",
                "title": "adidas Originals trainingspak, slippers & sneakers zwart & ...",
                "url_shown": "https://www.jdsports.nl› merk › adidas-originals",
                "pos_overall": 9
              }
            ],
            "knowledge": {
              "title": "Adidas",
              "images": [
                "iVBORw0KGgoAAAANSUhEUgAAAHcAAABQCAMAAAAUTho2AAAAY1BMVEX///8AAACdnZ1hYWF7e3tdXV3h4eFFRUWmpqbx8fFPT0/V1dXq6ur6+vq1tbXl5eVVVVVra2uRkZE9PT0ZGRnOzs44ODi9vb1xcXGGhobFxcUsLCysrKwzMzMdHR0TExMkJCST6SYPAAAFMUlEQVRogcVZ2YKqMAwFAaFAkUUFUUf//ysvbZNSaDMyCt68OEOgp6TJyYLnrSF5dVplnb8Jr32/+T7s7ccf5PZl1OzsK+HfRM0rH+XyPVRxsKPsvwVbPExYP/oOatb4M+m/gGocrJbj5qjTg9Wy2xq3dcL6fr41cODGDbfG3RMvnG0NfHHjxlvjcuKFi62Bb27c4+Y0fXYD11vjnghLH7YCbJn6dTCWkGAb1EOJtHQgXniLkoeFYmWgJTdZ+tf1YRO1cqX+4w83cLIyaq9dGGipcOM+2Jqow8FqQVpK3cAr0jSbEiPQUubGXa/kuR2nC/8ALRGxlK6DerpbKwMtMeKF1yh5Ds5kC7G0c+M+P6dpIgEALfGrW/15yfOClqiS5/NYIkx5BnXpVlcf41KmhE5su5KHoCXsxDq3doWSJ3avDLRExdLnJQ9lSqClxK39+dy1QvfKpdJym1akvF/y5BAsL2ipJ9Rvtg9DF/SEPwlTIi0RsVS+BVuIuQXyzu+0RHHLGzSdgRODc1DVI6iJ9uFMr+8WphNcB1eITgzUbJWSh5vUCMFCmRJoicgef6Lp9mk+iTmcMCWqiVhaXvLs5+wEvMOPzoVRTTnAwpKH2RSBwULRNDxJOMCykmfn8g/knd87McoB2gUv++N+FJyDqh6hE6PahwUlD8E72GoRNI0lD7HrBTT9oqbJf1dTDrAgll6MLYiS5w5qwgEWlDyUrXC6TKiBligHWNCZvuAdKuOBmih5ltD0zi3FLkl2BXRitVvde7n74fr92YM0YQTsYC8j1Z3juU9F0uAQMJH4tblP4m4xJfzfuOV/wm2TwYFsItgcl5C3cYswbeLuxry+6rpK55D+MlyOdnu18IC7C8OwyyfqANUa91SX6ql8WKyDDzws6WJ1sxZjbB9KKgT+GUmkLBznO1cDbqtzaSMvy094bKSUFMMws9hP4jJrWjPxZ2YlL4nLrZGHIPd8ktdP49nYuPxpXTZxmV1QSVx7tCRwZxlDHBSWoNdy/CCUjAv8pLHeq4kLVdjTUAtcMOcjTbURYxgKHFuOZbm4UyXzSqyl69cEDy+WJmmPFq5SN1JdPDWuqu6e0i9xvBfDblQBqFotDrkc25FM4z4BSN18n+GqGUAJJQy7Iq40UgPxzRvElZfBr6sgCEqmOq4xMAvAlRsfJ6v7Ge4Jdg1yAFx1mw4zhrjK18qbEUMBHhjIXeHWo2WkdFPc2jQSHlbomeEkpAbcMeLuYaLAhD3PfHZronZo9K/tFFeqjXTYK0BZJhlN4Alwp19fUuEV0gDjnWprieQHc1Awy0fBxMyaJ8OZ8faAO4/Vm6qYGvt9g1XeN0Pc+ffTzDrfxjhfo9QPp7gXdddUDedrfHCvNe7gZH1daYboVGk6ViiqcEvU71iPqWib+fNxpkZ/1sejjtUYZHG2V5XyA0IAXRMmRgl8O8D98PMMl0/CG9QhsJg+thRw9/7j8UB3UNyEsRWKw2I4PklQnYq2mvfAeQZfqTtjqW5HvlLmuvYC46T5SlHxbWp7bD7SoNQdboIHPWw+inQGMPkZLsZRpEcuInAj9ec5inQq0LxRaAeVPZOjY048ZzNk4jrUAtcxRJ28G5hGRooNLD01t5aY5N+DlQhV/rUSYexZfQYQoRFcZahxPT52aY08lWhSbxhVyln+2ZmOI+QqL8t6IzO2cx/7pcOufAxJs868TDQWqGBJNRimuZy8XPQmwzYL0XZgoOS3avC4+NJ7TKgx3FnRiadCuAz+lNXCf45RLRf/B6q/PRO4flx7AAAAAElFTkSuQmCC"
              ],
              "factoids": [
                {
                  "links": [
                    {
                      "href": "/search?sca_esv=565570927&gl=nl&hl=nl&q=adidas+aandelenkoers&stick=H4sIAAAAAAAAAONgecRoxi3w8sc9YSndSWtOXmNU5-IKzsgvd80rySypFJLkYoOy-KV4ubj10_UNU8rMTcvSUngWsYokpmSmJBYrJCbmpaTmpOZl56cWFQMAFq2xOVIAAAA&sa=X&ved=2ahUKEwi_pp6S-6uBAxXAh_0HHfISDAcQ6BN6BAhKEAI",
                      "title": "Aandelenkoers"
                    },
                    {
                      ...
                    }
                  ],
                  "title": "Aandelenkoers",
                  "content": "ADS (ETR) € 170,90 -0,20 (-0,12%)14 sep 17:43 CEST - Disclaimer"
                },
                {
                  ...
                },
                {
                  "links": [
                    {
                      "href": "/search?sca_esv=565570927&gl=nl&hl=nl&q=adidas+beurs&sa=X&ved=2ahUKEwi_pp6S-6uBAxXAh_0HHfISDAcQ6BMoAHoECFQQAg",
                      "title": "Beurs"
                    },
                    {
                      "href": "/search?sca_esv=565570927&gl=nl&hl=nl&q=Deutsche+B%C3%B6rse:+ADS&stick=H4sIAAAAAAAAAONgVuLUz9U3MDNOqcxexCriklpaUpyckargdHhbUXGqlYKjSzAA1vflrCQAAAA&sa=X&ved=2ahUKEwi_pp6S-6uBAxXAh_0HHfISDAcQmxMoAXoECFQQAw",
                      "title": "Deutsche Börse: ADS"
                    }
                  ],
                  "title": "Beurs",
                  "content": "Deutsche Börse: ADS"
                }
              ],
              "subtitle": "Bedrijf",
              "description": "Adidas AG is een Duitse multinational, opgericht en gevestigd in Herzogenaurach, Duitsland, die schoenen, kleding en accessoires ontwerpt en produceert. Het is de grootste fabrikant van sportkleding in Europa en de op één na grootste ter wereld, na Nike.",
              "related_searches": [
                {
                  "url": "/search?sca_esv=565570927&gl=nl&hl=nl&q=Nike&si=ALGXSlZS0YT-iRe81F2cKC9lM9KWTK4y0m5Atx8g9YliNNw2mQ1KNk4tlt4bFDSc4NSQLjoQ-vCfp5VZjzAXWikRLPCiUPiH-mOH7_cmQFsmf2z83S2EU2EOpnBI8OdBJXAiGRnoX0ydR5k-eMMITDBqkFZ9mrJ6UwS_U63P0J1T-oSWGmQQ6GNH5ccal-6QMsHpIrNROn0BGlDTfD6GarlvzXqNi-CRVT4R20kaKPvTWmsRRH8JeiMRyMX8Ex7aYsJr1iVLszn5EKHqZtj_rlGyxItbVDzNKQ%3D%3D&sa=X&ved=2ahUKEwi_pp6S-6uBAxXAh_0HHfISDAcQxA16BAhMEAU",
                  "title": "Nike",
                  "section_title": "Mensen zoeken ook naar"
                },
                {
                  ...
                },
                {
                  "url": "/search?sca_esv=565570927&gl=nl&hl=nl&q=Reebok&si=ALGXSlYh1-GEPndq7qMo--O-TPixQtNN4JMroSxgItz5kq0stLoU8Q_ZNH58zk1o0S-SXC9cxPPLJ78Mz2ie2KaCE9G4Q9yl23tVTaG5rRyKrfdJYzV29xX2O0Ik23POfs_d81weX8VaRe4_cf3ZkyFOYvw82PyxsqmS3GF_fXwBBLjbODPEQax0Nf1q1GBTsXoAxeHLAWmsGguZMB4xwAD_4A-e3B0Vy5_5zC7tmLq8SoPlqlgtHN1WvxQ2KxwtpeMFaXU7Mqw53TMR-P6mKadGD8EKqGlbZXtA73qUWORpELm1VjLvg2Q%3D&sa=X&ved=2ahUKEwi_pp6S-6uBAxXAh_0HHfISDAcQxA16BAhMEAs",
                  "title": "Reebok",
                  "section_title": "Mensen zoeken ook naar"
                }
              ]
            },
            "navigation": [
              {
                "pos": 1,
                "url": "/search?sca_esv=565570927&gl=nl&hl=nl&q=adidas&tbm=isch&source=lnms&sa=X&ved=2ahUKEwi_pp6S-6uBAxXAh_0HHfISDAcQ0pQJegQIDhAB",
                "title": "Afbeeldingen"
              },
              {
                ...
              }
            ],
            "instant_answers": [
              {
                "type": "unknown",
                "_parsed": false,
                "pos_overall": 4
              }
            ],
            "related_searches": {
              "pos_overall": 11,
              "related_searches": [
                "adidas schoenen",
                "adidas voetbalschoenen",
                "adidas yeezy",
                "adidas originals",
                "adidas wiki",
                "adidas slippers",
                "adidas store",
                "adidas superstar"
              ]
            },
            "search_information": {
              "query": "adidas",
              "showing_results_for": "adidas",
              "total_results_count": 1110000000
            },
            "total_results_count": 1110000000
          },
          "last_visible_page": -1,
          "parse_status_code": 12000
        },
        "created_at": "2023-09-15 06:13:50",
        "updated_at": "2023-09-15 06:13:52",
        "page": 1,
        "url": "https://www.google.nl/search?q=adidas&uule=w+CAIQICILbmV0aGVybGFuZHM&gl=nl&hl=nl",
        "job_id": "7108332062523787265",
        "status_code": 200,
        "parser_type": ""
      }
    ]
  }

Explore output data dictionary for each Web SERP feature (including paid results), offering a brief description, screenshot, parsed JSON code snippet, and a table defining each parsed field.

PreviousNews Search NextReverse Image Search

Last updated 10 days ago