Shopping Search

The google_shopping_search source is designed to retrieve Google Shopping search results.

Request samples

In this example, we make a request to retrieve the first 4 pages of Google Shopping search for the search term adidas, sorted by descending price and minimum price of $20.

curl 'https://realtime.oxylabs.io/v1/queries' \
--user 'USERNAME:PASSWORD' \
-H 'Content-Type: application/json' \
-d '{
        "source": "google_shopping_search",
        "domain": "com",
        "query": "adidas",
        "pages": 4,
        "parse": true,
        "context": [
            {
                "key": "sort_by",
                "value": "pd"
            },
            {
                "key": "min_price",
                "value": 20
            }
        ]
    }'

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 Shopping search results.

ParameterDescriptionDefault Value

source

Sets the scraper.

google_shopping_search

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 results to specific geographical locations, domains, and languages.

ParameterDescriptionDefault 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.

-

Pagination

Controls for managing the pagination and retrieval of search results.

ParameterDescriptionDefault Value

start_page

Starting page number.

1

pages

Number of pages to retrieve.

1

Filtering

Advanced options for tailoring and refining the search context.

ParameterDescriptionDefault 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.

-

Other

Additional advanced settings and controls for specialized requirements.

ParameterDescriptionDefault Value

context: nfpr

true will turn off spelling auto-correction.

-

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

Below you can find a structured output example for google_shopping_search.

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.

KeyDescriptionType

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.

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

...
  "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)DescriptionType

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)DescriptionType

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": "/shopping/product/1503163696221055935?q=adidas&uule=w+CAIQICINdW5pdGVkIHN0YXRlcw&gl=us&hl=en&prds=eto:9260750834573489043_0,pid:17425630667348523786,rsk:PC_12455715925962143981&sa=X&ved=0ahUKEwikoMX_iNOGAxVvFbkGHV6uDZcQ8gIInBgoAA",
        "type": "grid",
        "price": 100,
        "title": "Adidas Samba OG 'White Black' 9",
        "rating": 4.7,
        "currency": "USD",
        "delivery": "Delivery by Tue, Jun 18 \u00b7 Free 30-day returns",
        "merchant": {
            "url": "/url?url=https://www.adidas.com/us/samba-og-shoes/B75806.html&rct=j&q=&esrc=s&opi=95576897&sa=U&ved=0ahUKEwikoMX_iNOGAxVvFbkGHV6uDZcQguUECKIY&usg=AOvVaw1uGHW41BiuoKTfeYo2le3u",
            "name": "adidas"
        },
        "price_str": "$100.00",
        "thumbnail": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcSEQPCgQtOW8Swse-SyzsEBKqqzGJO_l9lcKaq7hIeSPfLqrBv5sKJiligHh3eUZ7XoWnvwJfL2&usqp=CAE",
        "product_id": "1503163696221055935",
        "pos_overall": 1,
        "reviews_count": 5028
    },
]
...
Key (organic)DescriptionType

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.

integer

title

The title of the product listing.

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

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

Last updated