scrapeunblocker 0.14.1 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcf8149d49a7e9bea7fe09d3cd6641adcd1915580280238579a9af68819162da
-  data.tar.gz: 74f6c9109e659f7d84231f723160a8f708ad5031d40a768c0e4d203e2f84d95c
+  metadata.gz: 3f62e1ad297dc0829c5aad20c1c09208595bb459b733b87d862c585fe64e12e5
+  data.tar.gz: 9ce26e1db98023c5373d90229f0f9545fc11f71f28ba143e82710305aab6a811
 SHA512:
-  metadata.gz: 02ebb973075735fd92af9ef53a23e000216122cf1a7d9550f65435a8e925f988660305aeed2f77c0c1f2f593849b9b3ed978e52b374830b571ea88075d7b0649
-  data.tar.gz: 371d0ce6d960436f84264fe9e0111797870e658764be0f8ec8538614dbf8546a1379c02dcc82d7315f4e4cac358ba4a6ffbd76313ef14e660b9c8ef72a25f601
+  metadata.gz: 150e385abf9ae36cde1653f4c411ab43d3735f6267fb6c8aab24d43caf37aa3da4dd8c7f6833dd6b207f45b374d01e6112f4a27e4a7007b4bcba2c812ce83b3e
+  data.tar.gz: 2a7c1c9b01e7821b80dfd590e650a2766b56ecccaa28ae16c1b219f6ce2022d7b4d33c2108e33eed17319f794e9c052dbe6977a00964a201b15853fdadeefbf2

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.15.1 (2026-10-29)
+
+- `shopee_product` and `shopee_search` docs: describe `availability` and `inStock`, sold-out variations (`models[].available`, `tierIndex`), `categories` as the breadcrumb path plus `browseCategories`, `isPixPrice` (Brazilian Pix prices) and the JSON `{"status": "not_found", ...}` answer for a product that does not exist. Signatures are unchanged.
+
+## 0.15.0 (2026-10-29)
+
+- 23 new plugin methods on `Client`:
+  - Groceries: `kroger_search(query)` and `kroger_product(product)` (Kroger and its 18 banner stores such as Ralphs and Fred Meyer, priced for one store), `instacart_search(query, retailer: ...)` and `instacart_product(product)` (any retailer on Instacart, priced for a ZIP code), `publix_search(query)` and `publix_product(product)`.
+  - E-commerce: `amazon_offers` (every seller's offer for a product, by `asin:` or `url:`), `amazon_seller` (a seller's public profile and feedback, by `seller_id:` or `url:`), `costco_search(query)` and `costco_product(product)`, `flipkart_search(query)` and `flipkart_product(product_id)`, `lazada_search(query)` and `lazada_product(item_id)` (six markets, `country:`), `allegro_search(query)` and `allegro_product(offer_id)`, `falabella_search(query)` and `falabella_product` (Chile, Colombia and Peru), `magazineluiza_search(query)` and `magazineluiza_product`.
+  - Google: `google_ai_mode(q)` (the AI Mode answer with the pages it cites) and `google_lens(url)` (Google Lens visual matches for an image URL).
+  - AI: `gemini(prompt)` (Google Gemini's answer with its citations and sources).
+- The first argument of `flipkart_product`, `lazada_product`, `allegro_product`, `falabella_search` and `magazineluiza_search` is optional, for calls that pass `url:` instead. `falabella_product` and `magazineluiza_product` take `product_id:` or `url:`.
+- `instacart_search` needs `retailer:` (the retailer's Instacart slug, e.g. `"costco"`); the API answers 400 without it. `instacart_product` takes it too, unless `product` is a link that names the retailer.
+- `shein_search` docs: results also carry `reviewCountText`, and the price filters apply to `price`.
+
+No breaking changes.
+
 ## 0.14.1 (2026-10-25)
 
 - `serp(captcha_pause:)` docs: the API ignores `captcha_pause`; it is kept for compatibility. CAPTCHAs are handled server-side by retrying from other exits.

data/README.md

@@ -149,11 +149,12 @@ jobs = su.career_site_jobs("https://jobs.ashbyhq.com/ramp", keyword: "engineer")
 | Category | Methods |
 | --- | --- |
 | Travel | `skyscanner.flights`, `skyscanner.hotels`, `skyscanner.carhire`, `booking_hotels`, `booking_reviews`, `airbnb_search`, `airbnb_room`, `airbnb_reviews`, `tripadvisor_list`, `tripadvisor_reviews` |
-| Google | `google_local`, `google_images`, `maps_place_details`, `google_trends`, `google_shopping`, `google_jobs`, `google_hotels`, `google_hotels_property`, `google_news`, `google_ads_transparency`, `google_ads_transparency_advertisers` |
+| Google | `google_local`, `google_images`, `maps_place_details`, `google_trends`, `google_shopping`, `google_jobs`, `google_hotels`, `google_hotels_property`, `google_news`, `google_ads_transparency`, `google_ads_transparency_advertisers`, `google_ai_mode`, `google_lens` |
+| AI | `gemini` |
 | Search engines | `bing_search`, `bing_images`, `duckduckgo_search`, `yahoo_search`, `yahoo_images`, `brave_search`, `brave_images` |
-| E-commerce | `amazon_product`, `amazon_search`, `amazon_bestsellers`, `amazon_reviews`, `walmart_search`, `target_search`, `bestbuy_search`, `homedepot_search`, `etsy_search`, `shein_search`, `zalando_search`, `aliexpress_search`, `alibaba_search`, `alibaba_product`, `alibaba1688_search`, `alibaba1688_product`, `tiktok_shop_search`, `tiktok_shop_product`, `tiktok_shop_store`, `oopbuy_search`, `smyths_inventory`, `smyths_details`, `smyths_search`, `smyths_category`, `wish_search`, `wish_product`, `shopee_search`, `shopee_product`, `taobao_search`, `taobao_product` |
+| E-commerce | `amazon_product`, `amazon_search`, `amazon_bestsellers`, `amazon_reviews`, `amazon_offers`, `amazon_seller`, `walmart_search`, `target_search`, `bestbuy_search`, `homedepot_search`, `costco_search`, `costco_product`, `etsy_search`, `shein_search`, `zalando_search`, `aliexpress_search`, `alibaba_search`, `alibaba_product`, `alibaba1688_search`, `alibaba1688_product`, `tiktok_shop_search`, `tiktok_shop_product`, `tiktok_shop_store`, `oopbuy_search`, `smyths_inventory`, `smyths_details`, `smyths_search`, `smyths_category`, `wish_search`, `wish_product`, `shopee_search`, `shopee_product`, `taobao_search`, `taobao_product`, `flipkart_search`, `flipkart_product`, `lazada_search`, `lazada_product`, `allegro_search`, `allegro_product`, `falabella_search`, `falabella_product`, `magazineluiza_search`, `magazineluiza_product` |
 | Classifieds & Resale | `ebay_search`, `vinted_search`, `leboncoin_search` |
-| Groceries | `woolworths_search`, `woolworths_category`, `woolworths_specials`, `woolworths_product`, `coles_search`, `coles_category`, `coles_specials`, `coles_product`, `aldi_au_search`, `aldi_au_category`, `aldi_au_specials`, `aldi_au_product` |
+| Groceries | `woolworths_search`, `woolworths_category`, `woolworths_specials`, `woolworths_product`, `coles_search`, `coles_category`, `coles_specials`, `coles_product`, `aldi_au_search`, `aldi_au_category`, `aldi_au_specials`, `aldi_au_product`, `kroger_search`, `kroger_product`, `instacart_search`, `instacart_product`, `publix_search`, `publix_product` |
 | Real estate | `zillow_search`, `zillow_detail`, `redfin_search`, `redfin_detail`, `rightmove_search`, `idealista_search`, `idealista_detail`, `immobilienscout24_search` |
 | Vehicles | `mobile_de`, `autoscout24_search` |
 | Jobs | `indeed_jobs`, `glassdoor_jobs`, `glassdoor_reviews`, `glassdoor_salaries`, `naukri_jobs`, `wellfound_jobs`, `wellfound_job`, `wellfound_company`, `wellfound_company_search`, `career_site_jobs`, `upwork_jobs` |

data/lib/scrapeunblocker/plugins.rb

@@ -105,6 +105,102 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape every offer (all sellers) for an Amazon product.
+    #
+    # Returns the offers Amazon lists for a product under "All buying options", as JSON. Each
+    # offer has the seller (`sellerName`, `sellerId`, `sellerUrl`, `sellerRating`,
+    # `sellerRatingCount`, `sellerPositivePercent`), `price` + `currency`, `listPrice` and
+    # `savingsPercent`, `shippingPrice` and `totalPrice`, `condition` (as Amazon words it) with
+    # `conditionType` (new, used, collectible, refurbished) and the seller's `conditionNote`,
+    # `delivery` / `deliveryDate`, `alternativeDelivery` (the faster or Prime-member option
+    # Amazon also offers), `shipsFrom`, `soldByAmazon`, `fulfilledByAmazon`, `prime`, the
+    # `offerId` and a `buyBoxWinner` flag. The response also carries the product `title`,
+    # `rating`, `reviewCount`, `image` and `totalOffers`. Page 1 starts with the Buy Box
+    # (featured) offer, also returned as `buyBox`; Amazon shows it whatever filter is set.
+    # Amazon lists 10 other offers per page: follow `nextPage`, or read up to 5 pages in one
+    # call with `pages`. Filter with `condition`, `free_shipping` and `prime`. `shippingPrice`
+    # is 0 for free delivery and null when Amazon shows no delivery promise for the location.
+    # `proxy_country` defaults to the marketplace's home country so prices and delivery are the
+    # ones a local shopper sees; the proxy that served the request is reported as `exitCountry`
+    # and `exitProvider`.
+    #
+    # @param asin [String] Amazon product id (10-char ASIN, e.g. 'B07VGRJDFY'; books use their
+    # ISBN-10). Give either `asin` (with `marketplace`) or a product `url`.
+    # @param url [String] Full Amazon product url, e.g. 'https://www.amazon.de/dp/1847941834'.
+    # The ASIN and marketplace are read from it.
+    # @param marketplace [String] Regional Amazon site whose offers to list. Prices, sellers and
+    # delivery differ per marketplace. One of: amazon.com, amazon.co.uk, amazon.de, amazon.fr,
+    # amazon.it, amazon.es, amazon.nl, amazon.se, amazon.pl, amazon.com.be, amazon.com.tr,
+    # amazon.ca, amazon.com.mx, amazon.com.br, amazon.co.jp, amazon.in, amazon.ae, amazon.sa,
+    # amazon.sg, amazon.com.au. API default: amazon.com.
+    # @param condition [String] Only offers in this condition: all, new, used, used_like_new,
+    # used_very_good, used_good, used_acceptable. Default 'all'. API default: all.
+    # @param free_shipping [Boolean] Only offers with free delivery. API default: false.
+    # @param prime [Boolean] Only Prime-eligible offers. API default: false.
+    # @param page [Integer] 1-based offers page to start at. Amazon lists 10 offers per page
+    # (page 1 also carries the Buy Box offer and the product header). API default: 1.
+    # @param pages [Integer] How many consecutive pages to read in this call (1-5). Reading
+    # stops early at the last page. Each page delivered is billed as one request. API default:
+    # 1.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). Defaults to the marketplace's home country, so prices, shipping costs and delivery
+    # dates are the ones a local shopper sees.
+    # Calls POST /marketplace/amazon-offers.
+    def amazon_offers(asin: nil, url: nil, marketplace: nil, condition: nil, free_shipping: nil, prime: nil, page: nil, pages: nil, proxy_country: nil)
+      post_json("/marketplace/amazon-offers", {
+        asin: asin,
+        url: url,
+        marketplace: marketplace,
+        condition: condition,
+        free_shipping: free_shipping,
+        prime: prime,
+        page: page,
+        pages: pages,
+        proxy_country: proxy_country,
+      })
+    end
+
+    # Scrape an Amazon seller profile.
+    #
+    # Returns an Amazon third-party seller's public profile as JSON: `name`, `logo`,
+    # `storefrontUrl`, the headline `rating`, `ratingCount` and `positivePercent` Amazon shows
+    # (the last 12 months, or lifetime for a seller with few recent ratings; `ratingPeriod` says
+    # which), and `feedbackSummary` for `30d`, `90d`, `12m` and `lifetime` - each with the
+    # average `rating`, `ratingCount`, `positivePercent` / `neutralPercent` / `negativePercent`
+    # (4-5, 3 and 1-2 stars), the matching counts and the 5..1-star histogram. Also `about` (the
+    # seller's own description), `businessName`, `businessAddress` (+ `businessAddressLines`),
+    # `businessDetails` (every row of Amazon's "Detailed Seller Information", e.g. business
+    # type, trade register and VAT number where the marketplace shows them), `contactUrl` and
+    # `recentFeedback` (each with `rating`, `text`, `author`, `date`, `struckThrough` and
+    # `amazonMessage` when Amazon took responsibility for the order). Identify the seller with
+    # `seller_id` (plus `marketplace`), e.g. the `sellerId` of an offer from
+    # `/marketplace/amazon-offers`, or with any Amazon `url` naming the seller. Ratings are per
+    # marketplace. Amazon's own retail sellers show no ratings; those fields are null.
+    #
+    # @param seller_id [String] Amazon seller (merchant) id, e.g. 'A3PEV2IAOYFKM6' - the
+    # `sellerId` of an offer from /marketplace/amazon-offers. Give either `seller_id` (with
+    # `marketplace`) or a `url`.
+    # @param url [String] Any Amazon url that names the seller: the profile
+    # ('https://www.amazon.de/sp?seller=A1J6G6R957S11K'), a storefront ('/s?me=...') or a sold-
+    # by link. The seller id and marketplace are read from it.
+    # @param marketplace [String] Regional Amazon site the seller sells on. Ratings and feedback
+    # are per marketplace. One of: amazon.com, amazon.co.uk, amazon.de, amazon.fr, amazon.it,
+    # amazon.es, amazon.nl, amazon.se, amazon.pl, amazon.com.be, amazon.com.tr, amazon.ca,
+    # amazon.com.mx, amazon.com.br, amazon.co.jp, amazon.in, amazon.ae, amazon.sa, amazon.sg,
+    # amazon.com.au. API default: amazon.com.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). Optional: a seller profile is the same from every country, so by default any
+    # country is used.
+    # Calls POST /marketplace/amazon-seller.
+    def amazon_seller(seller_id: nil, url: nil, marketplace: nil, proxy_country: nil)
+      post_json("/marketplace/amazon-seller", {
+        seller_id: seller_id,
+        url: url,
+        marketplace: marketplace,
+        proxy_country: proxy_country,
+      })
+    end
+
     # Scrape Walmart product search.
     #
     # Searches Walmart for `query` and returns the products as JSON: `name`, `price` and
@@ -221,6 +317,72 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape Costco product search.
+    #
+    # Searches Costco (costco.com, or costco.ca with `domain=ca`) for `query` and returns
+    # `products`: `productId`, `itemNumber`, `title`, `brand`, `url`, `image`, `price` (and
+    # `priceMax` for a price range), `wasPrice`, `currency`, `promotions`, `marketingStatement`,
+    # `rating`, `reviewCount`, `memberOnly`, `onlineOnly`, `warehouseOnly`, `badges`,
+    # `availability`, `inWarehouse`, `shipIt`, `buyableOnline`, `priceShownInCartOnly`, `model`,
+    # `features`, `category`, `categoryPath` and `variantCount`, plus `totalResults`. A keyword
+    # Costco sends to a category page (e.g. 'tv') returns that category, named in
+    # `redirectedTo`. `availability` is for the delivery location in `deliveryLocation`. Sort
+    # with `sort`, start at `page` and collect up to `max_results`.
+    #
+    # @param query [String] What to search for, e.g. 'paper towels', 'kirkland coffee' or 'tv'.
+    # @param sort [String] Result order: relevance, price_low, price_high, rating, newest,
+    # brand. API default: relevance.
+    # @param page [Integer] 1-based results page to start from (24 products per page, as on
+    # costco.com). API default: 1.
+    # @param max_results [Integer] Products to collect from `page` on, 1-240. Up to 120 are
+    # billed as one request. API default: 24.
+    # @param include_out_of_stock [Boolean] Also return products that are out of stock (Costco
+    # hides them by default). API default: false.
+    # @param domain [String] Costco storefront: com, ca ('com' is costco.com, 'ca' is
+    # costco.ca). API default: com.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US').
+    # Leave blank to let the API pick. Costco computes `availability` for the delivery location
+    # it derives from the visitor; it is named in `deliveryLocation`.
+    # Calls POST /marketplace/costco-search.
+    def costco_search(query, sort: nil, page: nil, max_results: nil, include_out_of_stock: nil, domain: nil, proxy_country: nil)
+      post_json("/marketplace/costco-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+        include_out_of_stock: include_out_of_stock,
+        domain: domain,
+        proxy_country: proxy_country,
+      })
+    end
+
+    # Scrape a Costco product.
+    #
+    # Returns one Costco product (costco.com, or costco.ca with `domain=ca`) as JSON:
+    # `productId`, `itemNumber`, `title`, `brand`, `url`, `price`, `discount`, `currency`,
+    # `rating`, `reviewCount`, `memberOnly`, `onlineOnly`, `buyable`, `inWarehouse`, `shipIt`,
+    # `description`, `details`, `features`, `marketingStatement`, `promotionalStatement`,
+    # `shipping`, `manufacturer`, `manufacturerPartNumber`, `upc`, `minQuantity`, `maxQuantity`,
+    # `categoryPath`, `specifications`, `images`, `options` (e.g. every color and size) and
+    # `variants` (item number, option values, UPC). `product` takes a product id, an item number
+    # or a product link.
+    #
+    # @param product [String] A Costco product id ('100361434'), item number ('17767') or
+    # product link (https://www.costco.com/p/-/kirkland-signature-colombian-coffee-dark-
+    # roast-3-lbs/100361434).
+    # @param domain [String] Costco storefront: com, ca ('com' is costco.com, 'ca' is
+    # costco.ca). Defaults to the link's storefront, else 'com'.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US').
+    # Leave blank to let the API pick.
+    # Calls POST /marketplace/costco-product.
+    def costco_product(product, domain: nil, proxy_country: nil)
+      post_json("/marketplace/costco-product", {
+        product: product,
+        domain: domain,
+        proxy_country: proxy_country,
+      })
+    end
+
     # Scrape Etsy product search.
     #
     # Searches Etsy for `query` and returns the products as JSON: `title`, `price` + `currency`
@@ -258,9 +420,10 @@ module ScrapeUnblocker
     #
     # Searches SHEIN (US store) for `query` and returns the products as JSON: `id`, `sku`,
     # `title`, `url`, `price`, `originalPrice`, `currency`, `discountPercent`, `rating`,
-    # `reviewCount`, `category`, `image`, `soldOut` and `storeCode`. Order with `sort`, filter
-    # with `min_price`/`max_price`. Returns SHEIN's first results page (up to 20 products);
-    # SHEIN does not serve deeper pages to automated clients.
+    # `reviewCount`, `reviewCountText`, `category`, `image`, `soldOut` and `storeCode`. Order
+    # with `sort`, filter with `min_price`/`max_price` (enforced on `price`). Returns SHEIN's
+    # first results page (up to 20 products); SHEIN does not serve deeper pages to automated
+    # clients.
     #
     # @param query [String] What to search, e.g. 'summer dress' or 'phone case'.
     # @param sort [String] Ordering: relevance, price_low, price_high. API default: relevance.
@@ -630,15 +793,18 @@ module ScrapeUnblocker
     # Searches a Shopee market (Singapore, Indonesia, Malaysia, Thailand, Vietnam, Philippines,
     # Taiwan or Brazil - `country`) for `q` and returns one page of results: up to 40
     # `products`, each with `position`, `itemId`, `shopId`, `name`, `url`, `image`, `price`,
-    # `originalPrice` (when Shopee shows the crossed-out price), `discountPercent`, `currency`,
-    # `rating` (average stars), `location` (where the seller ships from) and `labels` (promotion
-    # badges). `sort` orders the results, `min_price` / `max_price` filter them, `shop_id` keeps
-    # one shop's products (or lists the shop without `q`), and `url` takes a Shopee search or
-    # category link instead. Shopee shows one page per search, so run several sort orders or
-    # price ranges for more products. `price` is what Shopee shows a signed-out shopper, which
-    # can be a promotional or new-customer price (see `labels`). Not available: stock, units
-    # sold, rating counts and reviews (Shopee does not publish them on the pages these endpoints
-    # read). One unit per call.
+    # `originalPrice` (when Shopee shows the crossed-out price), `discountPercent`,
+    # `isPixPrice`, `currency`, `rating` (average stars), `location` (where the seller ships
+    # from) and `labels` (promotion badges). `sort` orders the results, `min_price` /
+    # `max_price` filter them, `shop_id` keeps one shop's products (or lists the shop without
+    # `q`), and `url` takes a Shopee search or category link instead. Shopee shows one page per
+    # search, so run several sort orders or price ranges for more products. `price` is what
+    # Shopee shows a signed-out shopper, which can be a promotional or new-customer price (see
+    # `labels`). In Brazil a card often shows the Pix price (`isPixPrice: true`): `price` is
+    # then the Pix price and `discountPercent` is measured against the list price, which Shopee
+    # does not show on such a card, so `originalPrice` is null. Not available: per-variation
+    # prices, stock counts, units sold, rating counts and reviews (Shopee does not publish them
+    # on the pages these endpoints read). One unit per call.
     #
     # @param q [String] What to search for, e.g. 'iphone case' or 'air fryer'. Optional with
     # `shop_id`.
@@ -678,14 +844,22 @@ module ScrapeUnblocker
     # (average stars), `labels`, `images`, `shopLocation` and `shop` (`name`, `username`, `url`,
     # `rating`, `ratingCount`, `followers`, `itemCount`, `responseRatePercent`,
     # `isOfficialShop`, `isPreferredPlusSeller`, `location`, `joinedAt`). With `dataLevel: full`
-    # it also has `description`, `brand`, `condition`, `categories`, `videos`, `variations`
-    # (option names), `models` (`modelId`, `name`), `attributes`, `isOfficialShop`,
-    # `isPreOrder`, `estimatedShippingDays` and `createdAt`; `dataLevel: meta` means Shopee
-    # showed only the product's title and main image (some markets), with price, rating and shop
-    # still included. `price` is what Shopee shows a signed-out shopper, which can be a
-    # promotional or new-customer price (see `labels`). Not available: stock, units sold, rating
-    # counts and reviews (Shopee does not publish them on the pages these endpoints read). One
-    # unit per call.
+    # it also has `availability` (`in_stock`, `sold_out` or `unavailable` for a withdrawn
+    # listing) and `inStock`, `description`, `brand`, `condition`, `categories` (the path the
+    # product page's breadcrumb shows, with ids), `browseCategories` (the browse tree, whose ids
+    # Shopee's category links use), `videos`, `variations` (option names), `models` (`modelId`,
+    # `name`, `available` - false for a sold-out variation - and `tierIndex`, the model's option
+    # in each variation), `attributes`, `isOfficialShop`, `isPreOrder`, `estimatedShippingDays`
+    # and `createdAt`; `dataLevel: meta` means Shopee showed only the product's title and main
+    # image (some markets), with price, rating and shop still included. A product Shopee says
+    # does not exist (removed, or never existed) answers 404 with JSON `{"status": "not_found",
+    # ...}`; a 502 means the call could not get an answer from Shopee and can be retried.
+    # `price` is what Shopee shows a signed-out shopper, which can be a promotional or new-
+    # customer price (see `labels`). In Brazil a card often shows the Pix price (`isPixPrice:
+    # true`): `price` is then the Pix price and `discountPercent` is measured against the list
+    # price, which Shopee does not show on such a card, so `originalPrice` is null. Not
+    # available: per-variation prices, stock counts, units sold, rating counts and reviews
+    # (Shopee does not publish them on the pages these endpoints read). One unit per call.
     #
     # @param url [String] A Shopee product link, e.g. https://shopee.sg/Beats-
     # iPhone-17-Case-i.442800909.40270108836 or
@@ -777,6 +951,341 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape Flipkart product search.
+    #
+    # Searches Flipkart (India) for `query` and returns `products`, each with `productId` (the
+    # FSN, e.g. MOBHQV9YCUG4ZQZK), `itemId`, `listingId`, `title`, `brand`, `price`,
+    # `originalPrice` (MRP when discounted), `discountPercent`, `currency` (INR), `rating`,
+    # `ratingCount`, `reviewCount`, `assured` (F-Assured), `sponsored`, `badge` (e.g.
+    # Bestseller), `availability` / `inStock`, `keySpecs`, `category`, `image`, `images` and
+    # `url`. Also `total` (results Flipkart reports), `totalPages` and `nextPage`. `sort` orders
+    # the results, `min_price` / `max_price` filter by price, `page` picks the first page and
+    # `max_results` collects across pages. One unit per Flipkart page read.
+    #
+    # @param query [String] What to search for, e.g. 'iphone 17' or 'running shoes'.
+    # @param sort [String] Result order: relevance, popularity, price_asc, price_desc, newest.
+    # API default: relevance.
+    # @param page [Integer] First Flipkart results page to read (1-100). API default: 1.
+    # @param min_price [Integer] Lowest price in rupees (INR).
+    # @param max_price [Integer] Highest price in rupees (INR).
+    # @param max_results [Integer] Products to collect across pages, 1-240. A page holds 24
+    # products (40 in fashion grids); each page is one unit. API default: 24.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). Leave blank to let the API pick.
+    # Calls POST /marketplace/flipkart-search.
+    def flipkart_search(query, sort: nil, page: nil, min_price: nil, max_price: nil, max_results: nil, proxy_country: nil)
+      post_json("/marketplace/flipkart-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        min_price: min_price,
+        max_price: max_price,
+        max_results: max_results,
+        proxy_country: proxy_country,
+      })
+    end
+
+    # Scrape a Flipkart product.
+    #
+    # Returns one Flipkart (India) product by `product_id` (FSN or `itm` id) or `url`:
+    # `productId`, `itemId`, `listingId`, `title`, `brand`, `description`, `category`,
+    # `breadcrumbs`, `price`, `originalPrice` (MRP), `discountPercent`, `bestPrice` (with bank
+    # offers), `currency`, `availability` / `inStock`, `rating`, `ratingCount`, `reviewCount`,
+    # `ratingBreakdown` (1-5 stars), `aspectRatings` (e.g. Camera, Battery), `assured`,
+    # `selectedAttributes`, `highlights`, `specifications` (group / name / value), `images`,
+    # `variants` (dimension, value, productId, price, available, url), `seller` (name, id,
+    # rating, years on Flipkart), `offerCount`, `offers` (bank and exchange offers),
+    # `deliveryDays`, `cashOnDelivery`, `returnPolicy`, `reviews` (top reviews) and `url`. One
+    # unit per call.
+    #
+    # @param product_id [String] Flipkart product id: the FSN (`pid`, e.g. MOBHQV9YCUG4ZQZK) or
+    # the `itm...` id from a product link.
+    # @param url [String] A Flipkart product link, e.g. https://www.flipkart.com/apple-
+    # iphone-17-black-256-gb/p/itmc61b40459dd98?pid=MOBHQV9YCUG4ZQZK. Used instead of
+    # `product_id`.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). Leave blank to let the API pick.
+    # Calls POST /marketplace/flipkart-product.
+    def flipkart_product(product_id = nil, url: nil, proxy_country: nil)
+      post_json("/marketplace/flipkart-product", {
+        product_id: product_id,
+        url: url,
+        proxy_country: proxy_country,
+      })
+    end
+
+    # Scrape Lazada product search.
+    #
+    # Searches a Lazada market (Singapore, Malaysia, Thailand, Philippines, Vietnam or Indonesia
+    # - `country`) for `query` and returns `products`, each with `position`, `itemId`, `skuId`,
+    # `name`, `price`, `priceText`, `originalPrice` (crossed-out price), `discountPercent`,
+    # `rating`, `reviewCount`, `sold` (units sold, as Lazada rounds it) and `soldText`, `brand`,
+    # `seller` / `sellerId`, `location` (ships from), `inStock`, `lazMall`, `freeShipping`,
+    # `sponsored`, `image` and `url`. Also `total` (results Lazada lets you page through),
+    # `matches` (all matches it reports), `currency` and `nextPage`. `sort` orders the results,
+    # `min_price` / `max_price` filter by price, `page` picks the first page and `max_results`
+    # collects across pages (40 a page). One unit per Lazada page read.
+    #
+    # @param query [String] What to search for, e.g. 'iphone case' or 'air fryer'.
+    # @param country [String] Lazada market: 'sg' (lazada.sg), 'my' (lazada.com.my), 'th'
+    # (lazada.co.th), 'ph' (lazada.com.ph), 'vn' (lazada.vn), 'id' (lazada.co.id). Default 'sg'.
+    # Prices are in that market's currency.
+    # @param sort [String] Result order: relevance, price_asc, price_desc. API default:
+    # relevance.
+    # @param page [Integer] First Lazada results page to read (1-102). API default: 1.
+    # @param min_price [Float] Lowest price, in the market's currency.
+    # @param max_price [Float] Highest price, in the market's currency.
+    # @param max_results [Integer] Products to collect across pages, 1-400. A page holds 40
+    # products; each page is one unit. API default: 40.
+    # Calls POST /marketplace/lazada-search.
+    def lazada_search(query, country: nil, sort: nil, page: nil, min_price: nil, max_price: nil, max_results: nil)
+      post_json("/marketplace/lazada-search", {
+        query: query,
+        country: country,
+        sort: sort,
+        page: page,
+        min_price: min_price,
+        max_price: max_price,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape a Lazada product.
+    #
+    # Returns one Lazada product by `url`, or by `item_id` (+ optional `sku_id`) and `country`:
+    # `itemId`, `skuId`, `title`, `brand`, `description`, `highlights`, `categories`, `price`,
+    # `priceText`, `originalPrice`, `discountPercent`, `currency`, `rating`, `reviewCount`,
+    # `ratingBreakdown` (1-5 stars), `inStock`, `maxQuantity`, `images`, `specifications`,
+    # `variantDimensions` (e.g. colour and storage with their values), `variants` (every SKU
+    # with its attributes, price, image, availability and link), `seller` (id, shop id, name,
+    # positive rating, store highlights, link), `delivery` (option and estimate), `warranties`
+    # and `url`. One unit per call.
+    #
+    # @param item_id [String] Lazada item id (the number after '-i' in a product link, e.g.
+    # 13907853520).
+    # @param url [String] A Lazada product link, e.g. https://www.lazada.sg/products/apple-
+    # iphone-18-pro-max-i13907853520-s124925162667.html. Used instead of `item_id` / `country`.
+    # @param sku_id [String] Optional SKU id (the number after '-s') to select one variant.
+    # @param country [String] Lazada market: 'sg' (lazada.sg), 'my' (lazada.com.my), 'th'
+    # (lazada.co.th), 'ph' (lazada.com.ph), 'vn' (lazada.vn), 'id' (lazada.co.id). Default 'sg'.
+    # Prices are in that market's currency.
+    # Calls POST /marketplace/lazada-product.
+    def lazada_product(item_id = nil, url: nil, sku_id: nil, country: nil)
+      post_json("/marketplace/lazada-product", {
+        item_id: item_id,
+        url: url,
+        sku_id: sku_id,
+        country: country,
+      })
+    end
+
+    # Scrape Allegro search.
+    #
+    # Searches Allegro (Poland) for `query` and returns `products` (offers), each with
+    # `position`, `offerId`, `productId`, `title`, `price`, `currency` (PLN),
+    # `priceWithDelivery`, `deliveryFrom`, `freeDelivery`, `smart` (Allegro Smart!),
+    # `deliveryLabel`, `rating`, `ratingCount`, `recentBuyers` (bought in the last 30 days),
+    # `offersOfProduct`, `quantity`, `sponsored`, `promoted`, `superSeller`, `seller` (id,
+    # login, company, positive feedback %), `parameters`, `image`, `images` and `url`. Also
+    # `total` (all matches), `available` (offers Allegro lets you page through), `lastPage`,
+    # `category` and `nextPage`. Filter with `min_price` / `max_price`, `condition`,
+    # `shipping_from`, `delivery_time`, `offer_type`, `store_city` and `store_region`; `sort`
+    # orders the results; `page` and `max_results` page through them. One unit per Allegro page
+    # read.
+    #
+    # @param query [String] What to search for, e.g. 'iphone 15' or 'lego'.
+    # @param sort [String] Result order: relevance, price_asc, price_desc,
+    # price_with_delivery_asc, price_with_delivery_desc, popularity, ending_soon, newest,
+    # rating. API default: relevance.
+    # @param page [Integer] First Allegro results page to read (1-100). API default: 1.
+    # @param min_price [Float] Lowest price in zloty (PLN).
+    # @param max_price [Float] Highest price in zloty (PLN).
+    # @param condition [String] Item condition: new, like_new, refurbished, used, damaged.
+    # @param shipping_from [String] Where the item ships from: pl, cz, sk, hu, cn, eu,
+    # allegro_warehouse.
+    # @param delivery_time [String] Delivery speed: one_day, two_days, three_days (one_day =
+    # tomorrow).
+    # @param offer_type [String] Offer type: buy_now, auction (buy_now = fixed price).
+    # @param store_city [String] The seller's town, e.g. 'Kraków'.
+    # @param store_region [String] The seller's voivodeship, e.g. 'mazowieckie' or 'slaskie' (or
+    # its number 1-16).
+    # @param max_results [Integer] Offers to collect across pages, 1-300. A page holds about 60
+    # offers; each page is one unit. API default: 60.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'DE',
+    # 'CZ'). Leave blank to let the API pick (recommended: Allegro refuses some countries'
+    # exits).
+    # Calls POST /marketplace/allegro-search.
+    def allegro_search(query, sort: nil, page: nil, min_price: nil, max_price: nil, condition: nil, shipping_from: nil, delivery_time: nil, offer_type: nil, store_city: nil, store_region: nil, max_results: nil, proxy_country: nil)
+      post_json("/marketplace/allegro-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        min_price: min_price,
+        max_price: max_price,
+        condition: condition,
+        shipping_from: shipping_from,
+        delivery_time: delivery_time,
+        offer_type: offer_type,
+        store_city: store_city,
+        store_region: store_region,
+        max_results: max_results,
+        proxy_country: proxy_country,
+      })
+    end
+
+    # Scrape an Allegro offer.
+    #
+    # Returns one Allegro (Poland) offer by `offer_id` or `url`: `offerId`, `productId`,
+    # `title`, `productName`, `brand`, `gtin`, `price`, `originalPrice`, `currency`,
+    # `sellingMode` (buy_now / auction), `available` (stock), `condition`, `rating`,
+    # `ratingCount`, `ratingBreakdown` (1-5 stars), `recentBuyers`, `category`, `breadcrumbs`,
+    # `parameters` (group / name / value), `description`, `images`, `variants`, `seller` (id,
+    # login, Super Seller, feedback, company name and tax id), `location`, `smart`, `delivery`,
+    # `shippingMethods` (name, price, Smart! price), `returnDays`, `warranty`, `endsAt`,
+    # `reviews` and `url`. One unit per call.
+    #
+    # @param offer_id [String] Allegro offer number, e.g. 16680923539 (the number at the end of
+    # an /oferta/ link or its offerId).
+    # @param url [String] An Allegro offer or product link, e.g.
+    # https://allegro.pl/oferta/16680923539 or
+    # https://allegro.pl/produkt/...?offerId=16680923539. Used instead of `offer_id`.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'DE',
+    # 'CZ'). Leave blank to let the API pick (recommended: Allegro refuses some countries'
+    # exits).
+    # Calls POST /marketplace/allegro-product.
+    def allegro_product(offer_id = nil, url: nil, proxy_country: nil)
+      post_json("/marketplace/allegro-product", {
+        offer_id: offer_id,
+        url: url,
+        proxy_country: proxy_country,
+      })
+    end
+
+    # Scrape Falabella product search (Chile, Colombia, Peru).
+    #
+    # Searches a Falabella store (`country`: cl, co or pe) for `query` and returns the products
+    # as JSON: `productId`, `skuId`, `title`, `brand`, `url`, `price` (and `priceMax` for a
+    # price range), `cmrPrice` (price with the Falabella CMR card), `originalPrice` (crossed-out
+    # list price), `discountPercent`, `currency`, `rating`, `reviewCount`, `sellerId` /
+    # `sellerName`, `sponsored`, `bestSeller`, `freeShipping`, `deliveryLabels`, `badges`,
+    # `installmentsWithoutInterest`, `image` / `images`, `topSpecifications` and `variants`
+    # (colour / size options). Sort with `sort`, start at `page`, and collect up to
+    # `max_results` across pages (48 per page, each page billed as one request, see
+    # `pagesFetched`). `url` takes a Falabella search link instead of `query`.
+    #
+    # @param query [String] What to search, e.g. 'zapatillas nike', 'televisor 55' or
+    # 'notebook'.
+    # @param country [String] Falabella store: 'cl' (www.falabella.com, prices in CLP), 'co'
+    # (www.falabella.com.co, prices in COP), 'pe' (www.falabella.com.pe, prices in PEN). Default
+    # 'cl'.
+    # @param sort [String] Order: relevance, price_low, price_high, rating, brand. API default:
+    # relevance.
+    # @param page [Integer] 1-based results page to start from (1-200). API default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-480); Falabella serves 48
+    # per page and each page fetched is billed as one request. API default: 48.
+    # @param url [String] Instead of `query`: a Falabella search link, e.g.
+    # https://www.falabella.com/falabella-cl/search?Ntt=zapatillas (its store, sort and page are
+    # used).
+    # Calls POST /marketplace/falabella-search.
+    def falabella_search(query = nil, country: nil, sort: nil, page: nil, max_results: nil, url: nil)
+      post_json("/marketplace/falabella-search", {
+        query: query,
+        country: country,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+        url: url,
+      })
+    end
+
+    # Scrape one Falabella product's full detail.
+    #
+    # Fetches one Falabella product (by `product_id` + `country`, or `url`) and returns it as
+    # JSON: `productId`, `skuId`, `url`, `title`, `brand`, `description` / `longDescription`,
+    # `price` / `priceMax`, `cmrPrice`, `originalPrice`, `discountPercent`, `currency`,
+    # `available`, `stockUnits` (only when Falabella shows a low-stock count), `rating`,
+    # `reviewCount`, `sellerId` / `sellerName`, `freeShipping`, `deliveryLabels`, `badges`,
+    # `installmentsWithoutInterest`, `breadcrumbs`, `topSpecifications`, `specifications` (name
+    # / value), `images`, `videos`, `returnPolicy` and `variants` (every colour / size SKU with
+    # its own price, availability, delivery options and images). The top-level price fields are
+    # those of `sku` (default the main variant). Companion to `/marketplace/falabella-search`.
+    #
+    # @param product_id [String] Falabella product id, e.g. '17776888' or 'prod11930024' (the
+    # part after /product/ in a product link). Needs `country` unless it is 'cl'.
+    # @param url [String] Instead of `product_id`: a Falabella product link, e.g.
+    # https://www.falabella.com/falabella-cl/product/17776888/iphone-duo-256gb-night-
+    # sky/17776887 (its store and SKU are used).
+    # @param sku [String] Variant (SKU) whose price and availability fill the top-level fields;
+    # default the product's main variant. Every variant is listed in `variants` either way.
+    # @param country [String] With `product_id`: Falabella store: 'cl' (www.falabella.com,
+    # prices in CLP), 'co' (www.falabella.com.co, prices in COP), 'pe' (www.falabella.com.pe,
+    # prices in PEN). Default 'cl'.
+    # Calls POST /marketplace/falabella-product.
+    def falabella_product(product_id: nil, url: nil, sku: nil, country: nil)
+      post_json("/marketplace/falabella-product", {
+        product_id: product_id,
+        url: url,
+        sku: sku,
+        country: country,
+      })
+    end
+
+    # Scrape Magazine Luiza (Magalu) product search.
+    #
+    # Searches Magazine Luiza (magazineluiza.com.br, Brazil) for `query` and returns the
+    # products as JSON: `productId`, `offerId`, `title`, `brand`, `url`, `price`, `bestPrice`
+    # with `bestPriceMethod` (usually the Pix price), `originalPrice` (list price),
+    # `discountPercent`, `currency` (BRL), `installments` (count, amount, interest-free),
+    # `rating`, `reviewCount`, `sellerId` / `sellerName`, `available`, `sponsored`,
+    # `magaluIndica`, `category` / `subcategory`, `badges`, `image` and `variations`. Sort with
+    # `sort`, start at `page`, and collect up to `max_results` across pages (40 per page, each
+    # page billed as one request, see `pagesFetched`). `url` takes a Magalu search link instead
+    # of `query`.
+    #
+    # @param query [String] What to search, e.g. 'geladeira', 'smart tv 55' or 'air fryer'.
+    # @param sort [String] Order: relevance, price_low, price_high, best_selling, rating,
+    # newest, fastest_delivery, price_with_shipping_low. API default: relevance.
+    # @param page [Integer] 1-based results page to start from (1-25). API default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-200); Magalu serves 40
+    # per page and each page fetched is billed as one request. API default: 40.
+    # @param url [String] Instead of `query`: a Magazine Luiza search link, e.g.
+    # https://www.magazineluiza.com.br/busca/geladeira/ (its sort and page are used).
+    # Calls POST /marketplace/magazineluiza-search.
+    def magazineluiza_search(query = nil, sort: nil, page: nil, max_results: nil, url: nil)
+      post_json("/marketplace/magazineluiza-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+        url: url,
+      })
+    end
+
+    # Scrape one Magazine Luiza (Magalu) product's full detail.
+    #
+    # Fetches one Magazine Luiza product (by `product_id` or `url`) and returns it as JSON:
+    # `productId`, `offerId`, `url`, `title`, `brand`, `reference`, `description`,
+    # `keySellingPoints`, `price`, `bestPrice` / `bestPriceMethod`, `originalPrice`,
+    # `discountPercent`, `currency` (BRL), `installments`, `available`, `rating`, `reviewCount`,
+    # `commentCount`, `ratingHistogram`, `ratingAspects`, `reviews` (first page: rating, text,
+    # author, date, photos), `seller` (id, name, legal name, city / state, seller since, score,
+    # total sales, answer and delivery rate), `coupon`, `badges`, `breadcrumbs`,
+    # `specifications` (group / name / value), `variations` (colour, size, capacity... with the
+    # product id of each option), `images`, `videos` and package `dimensions`. Companion to
+    # `/marketplace/magazineluiza-search`.
+    #
+    # @param product_id [String] Magalu product id, e.g. '240354400' or 'jc60hbaa6d' (the part
+    # after /p/ in a product link).
+    # @param url [String] Instead of `product_id`: a Magazine Luiza product link, e.g.
+    # https://www.magazineluiza.com.br/notebook-acer-aspire-go/p/240354400/in/nota/.
+    # Calls POST /marketplace/magazineluiza-product.
+    def magazineluiza_product(product_id: nil, url: nil)
+      post_json("/marketplace/magazineluiza-product", {
+        product_id: product_id,
+        url: url,
+      })
+    end
+
     # Scrape Vinted product search.
     #
     # Searches Vinted for `query` and returns the listings as JSON: `title`, `price` and
@@ -1300,6 +1809,228 @@ module ScrapeUnblocker
       })
     end
 
+    # Search Kroger and its banner stores (Ralphs, Fred Meyer, King Soopers, ...).
+    #
+    # Products matching `query` on Kroger or one of its banner sites (`banner`: kroger, ralphs,
+    # fredmeyer, kingsoopers, frysfood, smithsfoodanddrug, qfc, dillons, bakersplus, citymarket,
+    # gerbes, foodfourless, harristeeter, marianos, metromarket, picknsave, jaycfoods, payless,
+    # foodsco), priced for one store. Returns `products` in the site's order with `productId`
+    # (Kroger's 13-digit id), `upc`, `gtin14`, `name`, `brand`, `size`, `url`, `image`, `price`
+    # (what the shopper pays now), `regularPrice`, `salePrice`, `onSale`, `savings`, `promotion`
+    # (`type` sale / price_drop / multibuy / must_buy / bogo, `text`, multibuy `quantity` and
+    # `quantityPrice`, `expiresAt`), `unitPrice` (`price`, `unit`, `text`), `soldBy` (unit /
+    # weight; weighed items carry Kroger's per-item estimate), `available`, `stockLevel` (HIGH /
+    # LOW / TEMPORARILY_OUT_OF_STOCK), `maxOrderQuantity`, `fulfillment` (`pickup`, `delivery`,
+    # `inStore`, `ship`: whether the store offers the product that way), `aisle` (`number`,
+    # `description`, `side`, `bay`, `shelf`), `rating`, `reviewCount`, `categories`,
+    # `snapEligible` and `offers` (extra deals such as 'Save $2 each when you buy 3'), plus
+    # `position` and `sponsored`. `totalResults` is the site's total match count; one call
+    # returns the first page (up to 24 products). `brand` narrows the search to one or more
+    # brands. `store` names the store the prices are for: `storeId`, `name`, `banner`,
+    # `address`, `latitude`, `longitude`, `fulfillmentMethods`, `hours`, `pricesFor` (pickup or
+    # inStore) and `selectedBy` (store_id / zip / default); with `zip`, `nearbyStores` lists the
+    # banner's other stores near it. Prices are in USD and depend on the store. One billed unit
+    # per call.
+    #
+    # @param query [String] What to search for, e.g. 'milk', 'coca cola', 'gluten free bread'.
+    # @param banner [String] Which Kroger-family store site to use: 'kroger' (Kroger), 'ralphs'
+    # (Ralphs), 'fredmeyer' (Fred Meyer), 'kingsoopers' (King Soopers), 'frysfood' (Fry's Food),
+    # 'smithsfoodanddrug' (Smith's), 'qfc' (QFC), 'dillons' (Dillons), 'bakersplus' (Baker's),
+    # 'citymarket' (City Market), 'gerbes' (Gerbes), 'foodfourless' (Food 4 Less),
+    # 'harristeeter' (Harris Teeter), 'marianos' (Mariano's), 'metromarket' (Metro Market),
+    # 'picknsave' (Pick 'n Save), 'jaycfoods' (Jay C Food Stores), 'payless' (Pay Less),
+    # 'foodsco' (FoodsCo). Host names (ralphs.com) and common spellings (food4less, smiths,
+    # frys) work too. API default: kroger.
+    # @param brand [String] Only products of these brands, e.g. 'Kroger' or 'Kroger|Simple
+    # Truth' (separate several with | or ,).
+    # @param store_id [String] Kroger store id (8 digits, e.g. '01400929'): prices, stock and
+    # aisles are that store's. The id is shown as `store.storeId` in every answer and in
+    # `nearbyStores` when you search by `zip`.
+    # @param zip [String] US ZIP code: prices for the banner's nearest store to it that takes
+    # online orders (the nearest store at all when none does). The answer lists the nearby
+    # stores in `nearbyStores`. Leave both `store_id` and `zip` blank for the banner's default
+    # store.
+    # @param max_results [Integer] Products to return, 1-24 (the first page of results). API
+    # default: 24.
+    # Calls POST /groceries/kroger-search.
+    def kroger_search(query, banner: nil, brand: nil, store_id: nil, zip: nil, max_results: nil)
+      post_json("/groceries/kroger-search", {
+        query: query,
+        banner: banner,
+        brand: brand,
+        store_id: store_id,
+        zip: zip,
+        max_results: max_results,
+      })
+    end
+
+    # Kroger product details (Kroger, Ralphs, Fred Meyer, King Soopers, ...).
+    #
+    # One product from Kroger or one of its banner sites, by Kroger product id, UPC / GTIN
+    # barcode or product link, priced for one store. `product` has `productId` (Kroger's
+    # 13-digit id), `upc`, `gtin14`, `name`, `brand`, `size`, `url`, `image`, `price` (what the
+    # shopper pays now), `regularPrice`, `salePrice`, `onSale`, `savings`, `promotion` (`type`
+    # sale / price_drop / multibuy / must_buy / bogo, `text`, multibuy `quantity` and
+    # `quantityPrice`, `expiresAt`), `unitPrice` (`price`, `unit`, `text`), `soldBy` (unit /
+    # weight; weighed items carry Kroger's per-item estimate), `available`, `stockLevel` (HIGH /
+    # LOW / TEMPORARILY_OUT_OF_STOCK), `maxOrderQuantity`, `fulfillment` (`pickup`, `delivery`,
+    # `inStore`, `ship`: whether the store offers the product that way), `aisle` (`number`,
+    # `description`, `side`, `bay`, `shelf`), `rating`, `reviewCount`, `categories`,
+    # `snapEligible` and `offers` (extra deals such as 'Save $2 each when you buy 3'), and the
+    # product page details: `description`, `highlights`, `images` (every angle, large),
+    # `ingredients`, `allergens`, `nutrition` (`servingSize`, `servingsPerContainer`,
+    # `nutrients` with amount, unit and % daily value), `dietary`, `claims`, `organic`,
+    # `glutenFree`, `kosher`, `nonGmo`, `taxonomy` (category paths), `countryOfOrigin`,
+    # `storage`, `dimensions`, `weight`, `ratingBreakdown`, `alcohol` and `ageRestricted`.
+    # `store` names the store the prices are for: `storeId`, `name`, `banner`, `address`,
+    # `latitude`, `longitude`, `fulfillmentMethods`, `hours`, `pricesFor` (pickup or inStore)
+    # and `selectedBy` (store_id / zip / default). One billed unit per call.
+    #
+    # @param product [String] The product: Kroger's 13-digit product id ('0001111041700'), a UPC
+    # or GTIN barcode ('011110417005'), or a product link from any banner
+    # (https://www.kroger.com/p/kroger-2-reduced-fat-milk/0001111041700). A link picks its
+    # banner by itself.
+    # @param banner [String] Which Kroger-family store site to use: 'kroger' (Kroger), 'ralphs'
+    # (Ralphs), 'fredmeyer' (Fred Meyer), 'kingsoopers' (King Soopers), 'frysfood' (Fry's Food),
+    # 'smithsfoodanddrug' (Smith's), 'qfc' (QFC), 'dillons' (Dillons), 'bakersplus' (Baker's),
+    # 'citymarket' (City Market), 'gerbes' (Gerbes), 'foodfourless' (Food 4 Less),
+    # 'harristeeter' (Harris Teeter), 'marianos' (Mariano's), 'metromarket' (Metro Market),
+    # 'picknsave' (Pick 'n Save), 'jaycfoods' (Jay C Food Stores), 'payless' (Pay Less),
+    # 'foodsco' (FoodsCo). Host names (ralphs.com) and common spellings (food4less, smiths,
+    # frys) work too. Default 'kroger'.
+    # @param store_id [String] Kroger store id (8 digits, e.g. '01400929'): prices, stock and
+    # aisles are that store's. The id is shown as `store.storeId` in every answer and in
+    # `nearbyStores` when you search by `zip`.
+    # @param zip [String] US ZIP code: prices for the banner's nearest store to it that takes
+    # online orders (the nearest store at all when none does). The answer lists the nearby
+    # stores in `nearbyStores`. Leave both `store_id` and `zip` blank for the banner's default
+    # store.
+    # Calls POST /groceries/kroger-product.
+    def kroger_product(product, banner: nil, store_id: nil, zip: nil)
+      post_json("/groceries/kroger-product", {
+        product: product,
+        banner: banner,
+        store_id: store_id,
+        zip: zip,
+      })
+    end
+
+    # Scrape Instacart product search.
+    #
+    # Searches one retailer's Instacart catalogue (Costco, Aldi, Publix, Safeway, Kroger, CVS,
+    # Sprouts, ... named by `retailer`) for `query` and returns `products` in Instacart's order,
+    # priced at the store Instacart assigns to `zip`: `id` (item id), `productId`, `name`,
+    # `brand`, `size`, `packageSize`, `price`, `priceText`, `wasPrice`, `onSale`, `unitPrice`
+    # (`price`, `per`, `text`), `soldBy` (each / weight), `estimatedWeight`, `promotions`
+    # (`text`, `type`), `available`, `stockLevel`, `rating`, `reviewCount`, `category`,
+    # `storeBrand`, `dietary`, `aisle`, `image` and `url`, plus `store` (the shop, its location
+    # id and the ZIP code used) and `totalResults`. Prices are Instacart's prices in USD, which
+    # can differ from the retailer's in-store prices. Up to `max_results` products, billed one
+    # unit per 30.
+    #
+    # @param query [String] What to search for, e.g. 'milk', 'greek yogurt', 'paper towels'.
+    # @param retailer [String] The retailer's Instacart slug: the part after /store/ in an
+    # Instacart link, e.g. 'costco', 'aldi', 'publix', 'safeway', 'kroger', 'cvs', 'sprouts',
+    # 'wegmans', 'sams-club'. An Instacart store link is accepted too.
+    # @param zip [String] 5-digit US ZIP code of the delivery area. Instacart prices and stock
+    # belong to the store serving it. Default 94105 (San Francisco).
+    # @param max_results [Integer] Products to return, 1-300, in Instacart's order. Billed one
+    # unit per 30. API default: 30.
+    # Calls POST /groceries/instacart-search.
+    def instacart_search(query, retailer: nil, zip: nil, max_results: nil)
+      post_json("/groceries/instacart-search", {
+        query: query,
+        retailer: retailer,
+        zip: zip,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape an Instacart product.
+    #
+    # One product of a retailer on Instacart, priced at the store Instacart assigns to `zip`:
+    # the search fields (`id`, `productId`, `name`, `brand`, `size`, `packageSize`, `price`,
+    # `wasPrice`, `onSale`, `unitPrice`, `soldBy`, `promotions`, `available`, `stockLevel`,
+    # `rating`, `reviewCount`, `category`, `dietary`, `aisle`, `image`, `url`) plus
+    # `description`, `ingredients`, `directions`, `warnings`, the product page `sections` and
+    # the `images` gallery, and `store`. `product` is an Instacart product id, an item id from a
+    # search result or a product link. One unit per call.
+    #
+    # @param product [String] An Instacart product id ('16902650'), an item id from a search
+    # result ('items_4142-16902650') or a product link
+    # (https://www.instacart.com/products/16902650-...).
+    # @param retailer [String] The retailer's Instacart slug: the part after /store/ in an
+    # Instacart link, e.g. 'costco', 'aldi', 'publix', 'safeway', 'kroger', 'cvs', 'sprouts',
+    # 'wegmans', 'sams-club'. An Instacart store link is accepted too. Optional when `product`
+    # is a link carrying `retailerSlug`.
+    # @param zip [String] 5-digit US ZIP code of the delivery area. Instacart prices and stock
+    # belong to the store serving it. Default 94105 (San Francisco).
+    # Calls POST /groceries/instacart-product.
+    def instacart_product(product, retailer: nil, zip: nil)
+      post_json("/groceries/instacart-product", {
+        product: product,
+        retailer: retailer,
+        zip: zip,
+      })
+    end
+
+    # Scrape Publix grocery search.
+    #
+    # Searches publix.com (US) for `query` at one store and returns `products`: `productId`,
+    # `itemCode`, `title`, `brand`, `size`, `url`, `image`, `price`, `priceText`, `unit` (e.g.
+    # 'lb' for items sold by weight), `wasPrice`, `currency`, `onSale`, `promotion` (`type` such
+    # as BOGO, `message`, `conditions`, `validThrough`, `savings`), `hasCoupon`, `soldByWeight`,
+    # `aisle`, `category`, `categoryPath` and `storeId`, plus `store` (the store the prices are
+    # for), `totalResults`, `totalPages` and `nextPage`. Publix publishes a price online only
+    # while an item is on promotion, so `price` is null for the rest. A keyword Publix sends to
+    # a category returns that category, named in `redirectedTo`; one it sends to a page that
+    # lists no products (the weekly ad, cake ordering, store locations) answers with no products
+    # and `sentElsewhere` true.
+    #
+    # @param query [String] What to search for, e.g. 'milk', 'cheerios' or 'chicken breast'.
+    # @param store_id [String] Publix store number whose prices and promotions to return, e.g.
+    # '1614'. Give this or `zip`; with neither, a store in Lakeland, FL is used. The store used
+    # is named in `store`.
+    # @param zip [String] US ZIP code; the nearest Publix store is used, e.g. '33801'.
+    # @param page [Integer] 1-based results page to start from (48 products per page). API
+    # default: 1.
+    # @param max_results [Integer] Products to collect from `page` on, 1-480. Each page fetched
+    # is billed one unit. API default: 48.
+    # Calls POST /groceries/publix-search.
+    def publix_search(query, store_id: nil, zip: nil, page: nil, max_results: nil)
+      post_json("/groceries/publix-search", {
+        query: query,
+        store_id: store_id,
+        zip: zip,
+        page: page,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape a Publix product.
+    #
+    # Returns one publix.com (US) product at one store as `product`: the search fields
+    # (`productId`, `itemCode`, `title`, `brand`, `size`, `price`, `wasPrice`, `promotion`,
+    # `aisle` and so on) plus `images`, `description`, `ingredients`, `directions`, `allergens`,
+    # `available`, `categories`, `badges`, `couponCount`, `smartLabelUrl` and `relatedProducts`,
+    # and `store`, the store the price is for. Publix publishes a price online only while an
+    # item is on promotion.
+    #
+    # @param product [String] A Publix product id ('RIO-PCI-103438') or product link
+    # (https://www.publix.com/pd/cheerios-cereal-large-size/RIO-PCI-103438).
+    # @param store_id [String] Publix store number whose prices and promotions to return, e.g.
+    # '1614'. Give this or `zip`; with neither, a store in Lakeland, FL is used. The store used
+    # is named in `store`.
+    # @param zip [String] US ZIP code; the nearest Publix store is used, e.g. '33801'.
+    # Calls POST /groceries/publix-product.
+    def publix_product(product, store_id: nil, zip: nil)
+      post_json("/groceries/publix-product", {
+        product: product,
+        store_id: store_id,
+        zip: zip,
+      })
+    end
+
     # Smyths Toys UK product stock, price, details and listings.
     #
     # Smyths Toys UK (smythstoys.com) as JSON, in four modes. `mode=product` (the default when
@@ -2109,6 +2840,94 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape a Google AI Mode answer.
+    #
+    # Asks Google AI Mode (the `udm=50` AI Mode tab, not the AI Overview on a results page) the
+    # question `q` and returns its full answer as JSON: `answer.text` (plain text),
+    # `answer.markdown` and `answer.blocks` (paragraphs, headings, lists, tables and code, in
+    # order), `references` (the pages the answer cites: `title`, `url`, `domain`, `source`,
+    # `snippet`), `links` (links written into the answer text) and `followUps` (the follow-up
+    # questions Google closes the answer with, if any). Set `proxy_country` to ask from a market
+    # - the Google market (`gl`) follows it - and `hl` for the answer's language. Answers differ
+    # between identical requests, as they do for a person.
+    #
+    # @param q [String] The question to ask Google AI Mode, e.g. 'how to learn python fast'.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). The Google market (`gl`) follows it unless `gl` is set.
+    # @param gl [String] Optional Google market override (ISO-2, e.g. 'us', 'de'). Default:
+    # `proxy_country`, else 'us'.
+    # @param hl [String] Language Google answers in, e.g. 'en', 'de', 'pt-BR'. Default 'en'.
+    # Calls POST /search/google-ai-mode.
+    def google_ai_mode(q, proxy_country: nil, gl: nil, hl: nil)
+      post_json("/search/google-ai-mode", {
+        q: q,
+        proxy_country: proxy_country,
+        gl: gl,
+        hl: hl,
+      })
+    end
+
+    # Search Google Lens with an image URL.
+    #
+    # Runs a Google Lens search for the image at `url` and returns its visual matches as JSON
+    # (usually ~60). Every match carries `title`, `url` (the page the image is on), `domain`,
+    # `source` (site name), `imageUrl` (the matching image), `thumbnailUrl`, `width`, `height`
+    # and `position`; product matches add `price` and `currency` (and `product` details) when
+    # Google has them, and `priceText`, `rating` and `reviews` as the tile shows them.
+    # `relatedSearches` lists what Lens recognised in the image (e.g. 'Eiffel Tower', with its
+    # Knowledge Graph id) and `aiOverview` is Google's own description of the image when it is
+    # ready in time (else null). Shopping matches follow the country the request comes from -
+    # set `proxy_country` for a market (a US request is served from a European exit, where
+    # Google loads Lens matches; `proxyCountry` in the response says which).
+    #
+    # @param url [String] Public http(s) URL of the image to search with, e.g. a product photo.
+    # Google fetches the image itself.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). Shopping matches and prices follow the country Google sees the request from.
+    # @param gl [String] Optional Google market override (ISO-2). Default: `proxy_country`, else
+    # 'us'.
+    # @param hl [String] Google UI language, e.g. 'en', 'de'. Default 'en'.
+    # @param max_results [Integer] Optional cap on the visual matches returned (1-100; default:
+    # all, usually ~60).
+    # Calls POST /images/google-lens.
+    def google_lens(url, proxy_country: nil, gl: nil, hl: nil, max_results: nil)
+      post_json("/images/google-lens", {
+        url: url,
+        proxy_country: proxy_country,
+        gl: gl,
+        hl: hl,
+        max_results: max_results,
+      })
+    end
+
+    # Ask Google Gemini and get its answer and cited sources.
+    #
+    # Asks Google Gemini (gemini.google.com, signed out) one question and returns `answer`
+    # (plain text) and `answerMarkdown`, `citations` (pages cited inline: `position`, `title`,
+    # `url`, `domain`, `siteName`, `description`, `citedText` - the answer sentences that page
+    # backs - and `firstCitedAt`, the character offset of the first of them), `sources` (pages
+    # Gemini consulted when it searched the web: `position`, `title`, `url`, `domain`),
+    # `webSearch` (whether it searched the web), `followUpPrompts` (`label`, `prompt`),
+    # `richBlocks` (cards Gemini drew that have no text, e.g. a sports score or image strip,
+    # left out of the answer), `model` (the model label the app shows), `location` and
+    # `locationCountry` (where Gemini placed the visitor), `complete` and `conversationId`.
+    # `country` asks from that country. Answers vary between identical calls, as they do for
+    # people. One unit per call.
+    #
+    # @param prompt [String] The question to ask Gemini, as a user would type it, e.g. 'best CRM
+    # for small business' (max 4000 characters). Each call starts a new conversation.
+    # @param country [String] Two-letter country code to ask from, e.g. US, GB, DE. Gemini
+    # answers for where it locates the visitor (local results, currency, language defaults);
+    # `locationCountry` in the answer says where it placed this call. Leave blank for any
+    # European location.
+    # Calls POST /ai/gemini.
+    def gemini(prompt, country: nil)
+      post_json("/ai/gemini", {
+        prompt: prompt,
+        country: country,
+      })
+    end
+
     # Search Bing.
     #
     # Searches Bing for `keyword` in a real browser and returns the results page as JSON:
@@ -3925,7 +4744,7 @@ module ScrapeUnblocker
     # @param video [String] Video id (dQw4w9WgXcQ) or any YouTube video URL.
     # @param lang [String] Preferred caption language code, e.g. 'en'. Omit for the
     # default/first track. A prefix like 'en' matches 'en-US'.
-    # @param format [String] Output shape: text, segments. 'segments' returns timestamps; 'text'
+    # @param format [String] Output shape: segments, text. 'segments' returns timestamps; 'text'
     # returns only the joined plaintext. API default: segments.
     # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
     # 'DE') for the watch page. Defaults to US.

data/lib/scrapeunblocker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ScrapeUnblocker
-  VERSION = "0.14.1"
+  VERSION = "0.15.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scrapeunblocker
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.15.1
 platform: ruby
 authors:
 - ScrapeUnblocker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies: []
 description: JS-rendered pages that bypass Cloudflare, DataDome, PerimeterX and Akamai,
   plus Google SERP and 100+ ready-made site plugins (Amazon, Walmart, Zillow, Google