Shopping Search

The google_shopping_search source returns search results from Google Shopping. Each rendered result includes a product token which is required to collect product data using the google_shopping_product source.

Request samples

In the code example below, we search for "Nvidia RTX" to obtain the product token in the response.

curl 'https://realtime.oxylabs.io/v1/queries' \
--user 'USERNAME:PASSWORD' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google_shopping_search",
    "query": "nvidia rtx",
    "render": "html",
    "parse": true
    }'

import requests
from pprint import pprint


# Structure payload.
payload = {
    "source": "google_shopping_search",
    "query": "nvidia rtx",
    "render": "html",
    "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_shopping_search",
    query: "nvidia rtx",
    render: "html",
    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();

<?php

$params = array(
    'source' => 'google_shopping_search',
    'query' => 'nvidia rtx',
    'render' => 'html',
    '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_shopping_search",
		"query":  "nvidia rtx",
		"render": "html",
		"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_shopping_search",
                query = "nvidia rtx",
                render = "html",
                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.JSONArray;
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_shopping_search");
        jsonObject.put("query", "nvidia rtx");
        jsonObject.put("render", "html");
        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();
    }
}

Note: Only rendered parsed jobs will return product tokens.

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

Parameter

Description

Default Value

source

Sets the scraper.

google_shopping_search

query

The keyword or phrase to search for.

render

Enables JavaScript rendering. Must be set to html to get product tokens. 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

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.

Note: make sure your localization parameters for google_shopping_product and google_shopping_search sources are the same (none if not defined). Regional misalignment between the sources may result in incomplete or inaccurate data.

Pagination

Controls for managing the pagination and retrieval of search results.

Parameter

Description

Default Value

start_page

Starting page number.

1

pages

Number of pages to retrieve.

1

Context parameters

Advanced options for tailoring the search context or controls for specialized requirements. Context parameters should be added to a context array as shown below:

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

Parameter

Description

Default Value

context: sort_by

Sort product list by a given criteria. r applies default Google sorting, rv - by review score, p - by price ascending, pd - by price descending.

r

context: min_price

Minimum price of products to filter.

context: max_price

Maximum price of products to filter.

context: nfpr

true will turn off spelling auto-correction.

Structured data

Below you can find a structured output example for google_shopping_search.

998KB

google_shopping_search-output.json

Open

Output data dictionary

HTML example

JSON structure

The table below presents a detailed list of each search page element we parse, along with its description and data type. The table also includes some metadata.

Key

Description

Type

url

The URL to the Google Shopping search page for the query.

string

page

The current page number of the search results.

integer

results

An object containing detailed search results.

object

pla (optional)

A list of product listing ads with their respective details.

array

filters (optional)

List of various filters.

array

organic

A list of unpaid listings with their respective details.

array

search_information

A list of details for the submitted search query.

object

search_information.query

The original search term.

string

search_information.showing_results_for

The search term the search results are shown for. `query` and `showing_results_for` may differ if Google auto-corrected the provided search term.

string

last_visible_page

Value identifying the maximum page number visible in the search query results page. (-1 when loading of more results is initiated by scrolling).

integer

parse_status_code

The status code of the parsing job. You can see the parser status codes described here.

integer

created_at

The timestamp when the scraping job was created.

timestamp

updated_at

The timestamp when the scraping job was finished.

timestamp

status_code

The status code of the scraping job. You can see the scraper status codes described here.

integer

job_id

The ID of the job associated with the scraping job.

string

In the following sections, parsed JSON code snippets are shortened where more than one item for the result type is available.

Paid Listing Ads

An array of objects containing Product Listing Ads (PLA) for the product. (Illustrative example)

...
  "pla": [
    {
        "items": [
            {
                "pos": 1,
                "url": "/aclk?sa=l&ai=DChcSEwiY8fLUi9OGAxVtj1AGHYnVBj0YABABGgJkZw&gclid=EAIaIQobChMImPHy1IvThgMVbY9QBh2J1QY9EAQYASABEgKpS_D_BwE&sig=AOD64_2DguiyFTR4GRY6Ww9o__l9HgJC_A&ctype=5&q=&ved=0ahUKEwj-6ezUi9OGAxWiWUEAHdbxAgsQww8I2xA&adurl=",
                "price": "$2,199.00",
                "title": "Polycade Sente: Black",
                "seller": "Polycade",
                "thumbnail": "https://encrypted-tbn0.gstatic.com/shopping?q=tbn:ANd9GcS59ZNOrZH96cy_cOgzxL52VoJYq9iPl7q8g26f9odcuG8pY8ZRxe9YMhkZDPnFAZDyP04lu29gy57ObwsKpWHb_pzQBja34tkErnSAz3nw&usqp=CAE"
            },
            {
                "pos": 2,
                "url": "/aclk?sa=l&ai=DChcSEwiY8fLUi9OGAxVtj1AGHYnVBj0YABADGgJkZw&gclid=EAIaIQobChMImPHy1IvThgMVbY9QBh2J1QY9EAQYAiABEgJwHvD_BwE&sig=AOD64_0LFB8jrHwNdEkmOdjcjGOdhQ9ZVg&ctype=5&q=&ved=0ahUKEwj-6ezUi9OGAxWiWUEAHdbxAgsQww8I3hA&adurl=",
                "price": "$2,199.00",
                "title": "Polycade Sente: White",
                "seller": "Polycade",
                "thumbnail": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQ2onFg_aXbg8LTX3qJT9f9XdiFrl_SNLXlpKhSjCQQ2c5EmQcrNXPwCMphjugJUhWctBpRVC0BiS4OUnq0FRAeQ4BXEWI6FuvZvGERsLc&usqp=CAE"
            },
                                ...
        ],
        "pos_overall": 1
    }
],
...

Key (pla)

Description

Type

items

All PLAs available within the page.

array

pos

An indicator denoting the position of a given item among PLA results.

integer

url

The URL of the product.

string

price

The price of the product in the listing ad.

string

title

The title of the product in the listing ad.

string

rating

The rating of the product.

integer

seller

The seller of the product in the listing ad.

string

thumbnail

The URL of the thumbnail image of the product.

string

reviews_count

The count of reviews for the product.

optional

pos_overall

An indication of the position of the result within the SERP.

integer

Filters

...
"filters": [
    {
        "name": "Show only",
        "values": [
            {
                "url": "/search?sca_esv=bbd3241cb3940ce2&sca_upv=1&gl=us&hl=en&tbm=shop&q=adidas&tbs=mr:1,sales:1&sa=X&ved=0ahUKEwikoMX_iNOGAxVvFbkGHV6uDZcQ7KEGCJ4WKAA",
                "value": "On sale"
            }
        ]
    },
    {
        "name": "Price",
        "values": [
            {
                "url": "/search?sca_esv=bbd3241cb3940ce2&sca_upv=1&gl=us&hl=en&tbm=shop&q=adidas&tbs=mr:1,price:1,ppr_max:40&sa=X&ved=0ahUKEwikoMX_iNOGAxVvFbkGHV6uDZcQvSsIohYoAA",
                "value": "Up to $40"
            },
                                ...
                                {
                "url": "/search?sca_esv=bbd3241cb3940ce2&sca_upv=1&gl=us&hl=en&tbm=shop&q=adidas&tbs=mr:1,price:1,ppr_min:90&sa=X&ved=0ahUKEwikoMX_iNOGAxVvFbkGHV6uDZcQvSsIpRYoAw",
                "value": "Over $90"
            }
        ]
    },
    {
        "name": "Color",
        "values": [
            {
                "url": "/search?sca_esv=bbd3241cb3940ce2&sca_upv=1&gl=us&hl=en&tbm=shop&q=adidas&tbs=mr:1,color:specific,color_val:black&sa=X&ved=0ahUKEwikoMX_iNOGAxVvFbkGHV6uDZcQtSsIrBYoAA",
                "value": "Black"
            },
                                ...
                                {
                "url": "/search?sca_esv=bbd3241cb3940ce2&sca_upv=1&gl=us&hl=en&tbm=shop&q=adidas&tbs=mr:1,color:specific,color_val:pink&sa=X&ved=0ahUKEwikoMX_iNOGAxVvFbkGHV6uDZcQtSsIshYoBg",
                "value": "Pink"
            }
        ]
    },
                        ...
]

Key (filters)

Description

Type

name

The name of the filter category

string

values

Filter options available within the category.

array

values.url

The URL representing the filtered search query for this filter option.

string

values.value

The display name of the filter option

string

values.merchant_id (optional)

The ID of the merchant associated with this filter option.

string

Organic

An array of objects containing details of organic search results.

...
"organic": [
    {
        "pos": 1,
        "url": "https://www.google.com/shopping/product/16307418470740744792?q=nvidia+rtx&hl=en&udm=28&sei=j5fsaPC2FYWQur8P293m8A8&gl=us",
        "type": "grid",
        "price": 3090,
        "title": "NVIDIA GeForce RTX 5090 32GB GDDR7 Graphics Card",
        "token": "eyJjYXRhbG9naWQiOiAiMTYzMDc0MTg0NzA3NDA3NDQ3OTIiLCAiZ3BjaWQiOiAiMjM4NTIwNzk2NTI4MjUxMzUzOSIsICJpbWFnZURvY2lkIjogIjkyMjY0MjkwODMxMzQ4NDkwNDUiLCAibWlkIjogIiIsICJwdm8iOiAiMjMiLCAicHZ0IjogImhnIiwgInJkcyI6ICJQQ18yMzg1MjA3OTY1MjgyNTEzNTM5fFBST0RfUENfMjM4NTIwNzk2NTI4MjUxMzUzOSIsICJwcm9kdWN0aWQiOiAiIiwgInF1ZXJ5IjogIm52aWRpYSBydHgifQ==",
        "rating": 4.6,
        "currency": "USD",
        "delivery": "Free delivery by Fri",
        "merchant": {
            "name": "eBay"
        },
        "price_str": "$3,090.00",
        "thumbnail": "<THUMBNAIL_STR>",
        "product_id": "1503163696221055935",
        "pos_overall": 1,
        "reviews_count": 311
    },
]
...

Key (organic)

Description

Type

pos

The position of the product in the search results.

integer

url

The URL of the product page.

string

type

The type of listing layout.

string

price

The price of the product in the specified currency.

float

title

The title of the product listing.

string

token

The product token.

string

rating (optional)

The average user rating of the product, typically out of 5.

integer

currency

The currency code for the product price.

string

delivery

Delivery details, including estimated delivery date and return policy.

string

merchant (optional)

An object containing details about the merchant selling the product.

object

merchant.url

The URL of the merchant's page.

string

merchant.name

The name of the merchant.

string

price_str

The product price as a string, including the currency symbol.

string

thumbnail

The URL of the product's thumbnail image.

string

product_id

A unique identifier for the product.

string

pos_overall

The overall position of the product in the search results.

integer

reviews_count (optional)

The total number of reviews for the product.

integer

PreviousShopping NextShopping Product

Last updated 3 months ago

Was this helpful?

Good morning

hashtagRequest samples

hashtagRequest parameter values

hashtagGeneric

hashtagLocalization

hashtagPagination

hashtagContext parameters

hashtagStructured data

hashtagOutput data dictionary

hashtagJSON structure

hashtagPaid Listing Ads

hashtagFilters

hashtagOrganic

Request samples

Request parameter values

Generic

Localization

Pagination

Context parameters

Structured data

Output data dictionary

JSON structure

Paid Listing Ads

Filters

Organic