scrapeunblocker 0.15.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f62e1ad297dc0829c5aad20c1c09208595bb459b733b87d862c585fe64e12e5
-  data.tar.gz: 9ce26e1db98023c5373d90229f0f9545fc11f71f28ba143e82710305aab6a811
+  metadata.gz: 4a9fdb57b21c1b655ba3ec6bc4c87f0907872ccdf9ad279035e028192b7f4414
+  data.tar.gz: adfa7124cb12d1eac3aed2a818070be619a80e8a243e6d1816b34f534cb4601a
 SHA512:
-  metadata.gz: 150e385abf9ae36cde1653f4c411ab43d3735f6267fb6c8aab24d43caf37aa3da4dd8c7f6833dd6b207f45b374d01e6112f4a27e4a7007b4bcba2c812ce83b3e
-  data.tar.gz: 2a7c1c9b01e7821b80dfd590e650a2766b56ecccaa28ae16c1b219f6ce2022d7b4d33c2108e33eed17319f794e9c052dbe6977a00964a201b15853fdadeefbf2
+  metadata.gz: c6765faaf5a348e030ea3c102d5574b05d3f0105526b1141d4bb9b2257eb8fb3ec5c9ab96c6b934f8d0d6b2d026eaec0821a247670fb18c9382243ac32fc2206
+  data.tar.gz: 806142bbf00967541f0a32b88afa96485416f46505266647b41ee2ed13bbbe53c0c0f50210ec53138c13118ae5df4c9afdb701b2d0e6e601311e07055c95a22b

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.17.0 (2026-10-30)
+
+- 29 new plugin methods on `Client`:
+  - E-commerce, new sites: `mediamarkt_search(query)` and `mediamarkt_product(product_id)` (MediaMarkt in ten countries and Saturn), `cdiscount_search(query)` and `cdiscount_product(sku)`, `idealo_search(query)` and `idealo_offers(product_id)` (price comparison in six countries), `rakuten_search(query)` and `rakuten_product()` (Rakuten Ichiba, Japan), `indiamart_search(query)` and `indiamart_product()`, `bedbathandbeyond_search(query)` and `bedbathandbeyond_product(product)`, `petco_search(query)` and `petco_product(product)`, `neobits_product(product)`, `lowes_search(query)` and `lowes_product(product_id)`, `menards_search(query)` and `menards_product()`, `grainger_search(query)` and `grainger_product(sku)`.
+  - Product pages next to existing searches: `walmart_product()`, `ebay_product()`, `etsy_product()`, `bestbuy_product(sku)`, `target_category(category)` and `target_product(tcin)`, `aliexpress_product(product_id)`.
+  - AI: `chatgpt(prompt)` (ChatGPT's answer with the sites it cites).
+- The first argument of the product methods that also take a link, and of the searches that also take a search link, is optional, for calls that pass `url:` instead. `rakuten_product`, `indiamart_product`, `menards_product`, `walmart_product`, `ebay_product` and `etsy_product` take keyword options only (`product_id:` / `sku:` / `item_id:` / `listing_id:` or `url:`).
+- Plugin method comments no longer describe exit or proxy details (`exitProvider`); API responses no longer carry them.
+
+No breaking changes.
+
+## 0.16.0 (2026-10-29)
+
+- Add `maps_reviews`: Google Maps reviews of a place in Google's sort orders (relevant, newest, highest, lowest) with exact ISO dates, original and translated text, authors, photos, owner replies and page tokens. `POST /maps/reviews`.
+
 ## 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.

data/README.md

@@ -149,11 +149,11 @@ 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_ai_mode`, `google_lens` |
-| AI | `gemini` |
+| Google | `google_local`, `google_images`, `maps_place_details`, `maps_reviews`, `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`, `chatgpt` |
 | 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`, `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` |
+| E-commerce | `amazon_product`, `amazon_search`, `amazon_bestsellers`, `amazon_reviews`, `amazon_offers`, `amazon_seller`, `walmart_search`, `walmart_product`, `target_search`, `target_category`, `target_product`, `bestbuy_search`, `bestbuy_product`, `homedepot_search`, `costco_search`, `costco_product`, `etsy_search`, `etsy_product`, `shein_search`, `zalando_search`, `aliexpress_search`, `aliexpress_product`, `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`, `mediamarkt_search`, `mediamarkt_product`, `cdiscount_search`, `cdiscount_product`, `idealo_search`, `idealo_offers`, `rakuten_search`, `rakuten_product`, `indiamart_search`, `indiamart_product`, `bedbathandbeyond_search`, `bedbathandbeyond_product`, `petco_search`, `petco_product`, `neobits_product`, `lowes_search`, `lowes_product`, `menards_search`, `menards_product`, `grainger_search`, `grainger_product` |
+| Classifieds & Resale | `ebay_product`, `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`, `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` |

data/lib/scrapeunblocker/plugins.rb

@@ -79,8 +79,8 @@ module ScrapeUnblocker
     # `reviewsGated` is `true` and `reviews` is empty; the rating, histogram and customers-say
     # data, including its review excerpts, are still returned. Every field is always present and
     # is `null` when the page does not show it. `proxy_country` defaults to the marketplace's
-    # home country; the proxy that served the request is reported as `exitCountry` (its country)
-    # and `exitProvider` (its type: `isp`, `residential` or `datacenter`).
+    # home country; the country of the proxy that served the request is reported as
+    # `exitCountry`.
     #
     # @param asin [String] Amazon product id (10-char ASIN, e.g. 'B07PXGQC1Q'; books use their
     # ISBN-10). Give either `asin` (with `marketplace`) or a product `url`.
@@ -121,8 +121,8 @@ module ScrapeUnblocker
     # 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`.
+    # ones a local shopper sees; the country of the proxy that served the request is reported as
+    # `exitCountry`.
     #
     # @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`.
@@ -230,6 +230,38 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape one Walmart product's full detail.
+    #
+    # Fetches one Walmart product page (by `item_id` or `url`) and returns it as JSON: `itemId`,
+    # `title`, `brand`, `model`, `upc`, `price`, `wasPrice`, `listPrice`, `unitPrice` (e.g. per
+    # ounce, where Walmart shows one), `currency`, `rollback` / `clearance`, `availability` and
+    # `inStock`, `condition`, `seller` (name, Walmart or marketplace seller, its rating and
+    # review count), `additionalSellerCount`, `fulfillment` (shipping, pickup and delivery:
+    # available or not, date, fee, store or place), `returnPolicy`, `rating`, `reviewCount`,
+    # `reviewSummary` (star histogram, recommend percentage, aspect scores), the first
+    # `reviews`, `categories`, `shortDescription`, `description`, `highlights`,
+    # `specifications`, `warranty`, `variantOptions` and every `variants` entry (its own item
+    # id, attributes, price, stock), `images` and `videos`. Fulfillment dates and the store are
+    # what Walmart quotes for the US location it assigns to the request (`location` names it),
+    # not a ZIP code or store you choose. Other sellers' offers are not on the product page:
+    # only their count (`additionalSellerCount`) is returned. Companion to
+    # `/marketplace/walmart-search`.
+    #
+    # @param item_id [String] Walmart item id - the number at the end of a product link, e.g.
+    # '18638703162' for walmart.com/ip/.../18638703162.
+    # @param url [String] Instead of `item_id`: a walmart.com product link, e.g.
+    # https://www.walmart.com/ip/HP-15-6-inch-Laptop/18638703162.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2). Defaults to
+    # US: walmart.com refuses most other countries.
+    # Calls POST /marketplace/walmart-product.
+    def walmart_product(item_id: nil, url: nil, proxy_country: nil)
+      post_json("/marketplace/walmart-product", {
+        item_id: item_id,
+        url: url,
+        proxy_country: proxy_country,
+      })
+    end
+
     # Scrape Target product search.
     #
     # Searches Target for `query` and returns the products as JSON: `tcin`, `title`, `brand`,
@@ -257,6 +289,70 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape a Target category listing.
+    #
+    # Lists the products of one Target category (by id or category link; a brand page's id or
+    # link works too) as JSON: `category` (id, name, link, and `type`: category or brand),
+    # `breadcrumbs`, `totalResults`, `totalPages`, and `products` with `tcin`, `title`, `brand`,
+    # `price` (`priceMax` for a family priced as a range), `originalPrice` and `priceType` when
+    # on sale, `formattedPrice`, `currency`, `rating`, `ratingCount`, `promotions`, `image` and
+    # `url`. Sort with `sort`, start at `page` and collect up to `max_results` across pages
+    # (Target serves at most 50 pages of 24). Filters in a category link (...Z<facet>) are not
+    # applied. Each page fetched is billed as one request (`pagesFetched`).
+    #
+    # @param category [String] Target category: its id (e.g. '5xtro', the part after N- in a
+    # category link) or a target.com category link, e.g. https://www.target.com/c/coffee-makers-
+    # tea-espresso-kitchen-appliances-dining/-/N-5xtro. A brand page (/b/<brand>/-/N-<id>) lists
+    # that brand.
+    # @param sort [String] Order: relevance, price_low, price_high, rating, best_selling,
+    # newest. API default: relevance.
+    # @param page [Integer] 1-based page to start from (1-50, 24 products per page). API
+    # default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-240); each page fetched
+    # is billed as one request. API default: 24.
+    # Calls POST /marketplace/target-category.
+    def target_category(category, sort: nil, page: nil, max_results: nil)
+      post_json("/marketplace/target-category", {
+        category: category,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape one Target product.
+    #
+    # Returns one Target product by `tcin` or `url` as JSON: `tcin` (and `parentTcin` when it is
+    # one variant of a product family), `title`, `brand`, `url`, `dpci`, `upc`, `productType`,
+    # `price` (`priceMax` for a family priced as a range), `originalPrice` / `savings` /
+    # `savingsPercent` / `priceType` when on sale, `priceNote` (e.g. 'When purchased online'),
+    # `currency` (USD), `promotions`, `rating`, `ratingCount`, `reviewCount`,
+    # `ratingDistribution`, `recommendedPercent`, `questionCount`, `description`, `highlights`,
+    # `specifications`, `image` / `images`, `category` / `categories`, `selectedVariant` and
+    # `variants` (every colour / size with its own TCIN, price, link, image and shipping / store
+    # availability), `fulfillment` (sold out, shipping status and delivery dates to `zip`,
+    # pickup status, date and quantity at `store_id`, aisle) and `packageDimensions`. Prices are
+    # target.com's online prices. Companion to `/marketplace/target-search`, whose `tcin` it
+    # takes. One unit per call.
+    #
+    # @param tcin [String] Target item number (TCIN), e.g. '52580270' (the number after A- in a
+    # product link).
+    # @param url [String] Instead of `tcin`: a target.com product link, e.g.
+    # https://www.target.com/p/hamilton-beach-coffee-maker/-/A-52580270 (a `?preselect=` variant
+    # in the link is honoured).
+    # @param store_id [String] Target store whose pickup and shelf stock is reported, e.g.
+    # '1375' (default 1375, Minneapolis Nicollet Mall).
+    # @param zip [String] US ZIP code shipping dates are quoted for (default 55403).
+    # Calls POST /marketplace/target-product.
+    def target_product(tcin = nil, url: nil, store_id: nil, zip: nil)
+      post_json("/marketplace/target-product", {
+        tcin: tcin,
+        url: url,
+        store_id: store_id,
+        zip: zip,
+      })
+    end
+
     # Scrape Best Buy product search.
     #
     # Searches Best Buy (US) for `query` and returns the products as JSON: `sku`, `title`,
@@ -288,6 +384,32 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape one Best Buy product.
+    #
+    # Returns one Best Buy (US) product by `sku` or `url` as JSON: `sku`, `title`, `brand`,
+    # `model`, `upc`, `productType`, `condition`, `url`, `price`, `originalPrice` / `savings` /
+    # `savingsPercent` (when on sale), `currency` (USD), `available` with `availableForShipping`
+    # / `availableForPickup` / `availableForDelivery` (nationwide, not for one store or ZIP
+    # code), `rating`, `reviewCount`, `description`, `features`, `includedItems`,
+    # `specifications` (group / name / value), `image` and `images` (full size), `category` and
+    # `categories` (root to leaf), `seller` (Best Buy or a Marketplace seller id),
+    # `openBoxOffers` (Excellent / Good / Fair with their prices and links), `dimensions` and
+    # `releaseDate`. Companion to `/marketplace/bestbuy-search`, whose `sku` it takes. One unit
+    # per call.
+    #
+    # @param sku [String] Best Buy SKU, e.g. '6613868' (the number after /sku/ in a product
+    # link, or its skuId=).
+    # @param url [String] Instead of `sku`: a bestbuy.com product link, e.g.
+    # https://www.bestbuy.com/product/hp-omnibook-x-flip/JJGQJRKGTJ/sku/6613868 or
+    # https://www.bestbuy.com/site/-/6613868.p?skuId=6613868.
+    # Calls POST /marketplace/bestbuy-product.
+    def bestbuy_product(sku = nil, url: nil)
+      post_json("/marketplace/bestbuy-product", {
+        sku: sku,
+        url: url,
+      })
+    end
+
     # Scrape Home Depot product search.
     #
     # Searches Home Depot for `query` and returns the products as JSON: `itemId`, `title`,
@@ -416,6 +538,39 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape one Etsy listing's full detail.
+    #
+    # Fetches one Etsy listing (by `listing_id` or `url`) and returns it as JSON: `listingId`,
+    # `title`, `price` (the lowest price when variations differ, `priceMax` the highest),
+    # `originalPrice` / `onSale` / `discountPercent` / `saleEnds` during a sale, `currency` and
+    # `shopperRegion`, `availability` and `quantityAvailable`, `rating` and `reviewCount`,
+    # `reviewSummary` (item quality, shipping and service scores, recommend percentage, review
+    # tags and categories), the first `reviews`, `shop` (name, id, owner, location, rating,
+    # review count, sales, years on Etsy, Star Seller), `variations` (each menu with its options
+    # and their prices), `description`, `materials`, `highlights`, `category`, `shipping` (cost,
+    # origin, ships from, estimated delivery, processing time, returns), `images` and `video`.
+    # Prices, shipping cost and VAT follow the shopper location Etsy assigns to the request,
+    # which can differ from `proxy_country`: `currency` and `shopperRegion` say which one a
+    # response used (e.g. EUR / BE), so read them before comparing prices. Shop review and sales
+    # counts are Etsy's rounded figures ("4.7k sales" is 4700). Companion to `/marketplace/etsy-
+    # search`.
+    #
+    # @param listing_id [String] Etsy listing number, e.g. '1702915637' (the number in
+    # etsy.com/listing/1702915637/...).
+    # @param url [String] Instead of `listing_id`: an etsy.com listing link, e.g.
+    # https://www.etsy.com/listing/1702915637/solstice-mug.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2). Defaults to
+    # US. Etsy prices in the currency of the shopper location it assigns, which can differ from
+    # this country; `currency` and `shopperRegion` say which one a response used.
+    # Calls POST /marketplace/etsy-product.
+    def etsy_product(listing_id: nil, url: nil, proxy_country: nil)
+      post_json("/marketplace/etsy-product", {
+        listing_id: listing_id,
+        url: url,
+        proxy_country: proxy_country,
+      })
+    end
+
     # Scrape SHEIN product search.
     #
     # Searches SHEIN (US store) for `query` and returns the products as JSON: `id`, `sku`,
@@ -501,6 +656,40 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape one AliExpress product.
+    #
+    # Returns one AliExpress item by `product_id` or `url`, priced in `currency` and shipped to
+    # `country`, as JSON: `productId`, `url`, `title`, `price` (the default SKU), `priceMin` /
+    # `priceMax` across SKUs, `priceFormatted`, `originalPrice` / `originalPriceMax`, `discount`
+    # and `discountPercent`, `currency`, `rating`, `reviewCount`, `soldText` and `orders`,
+    # `inStock`, `store` (name, ids, link, country, open since, positive feedback, ratings),
+    # `shipping` (each option: method, fee, free, ships from / to, delivery days and dates,
+    # deliverable), `skuProperties` (e.g. colour, size, ships from, with images), `variants`
+    # (every SKU with its attributes, price, original price, availability, stock and image),
+    # `specifications`, `images`, `categoryId` and `descriptionUrl` (the seller's HTML
+    # description). One unit per call.
+    #
+    # @param product_id [String] AliExpress item id, e.g. '1005010503016514' (the number in
+    # /item/<id>.html; `productId` from /goods/aliexpress-search).
+    # @param url [String] Instead of `product_id`: an AliExpress item link, e.g.
+    # https://www.aliexpress.com/item/1005010503016514.html (any storefront: .com, .us, de., fr.
+    # ...).
+    # @param country [String] Ship-to country (ISO-2, e.g. 'US', 'DE', 'GB'). Shipping options,
+    # delivery times and whether the item is sold at all depend on it. API default: US.
+    # @param currency [String] Price currency, e.g. 'USD', 'EUR', 'GBP'. One of: USD, EUR, GBP,
+    # CAD, AUD, NZD, CHF, SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN, TRY, ILS, AED, SAR, JPY, KRW,
+    # SGD, MYR, THB, IDR, PHP, VND, INR, BRL, MXN, CLP, COP, PEN, ZAR, UAH, KZT. API default:
+    # USD.
+    # Calls POST /goods/aliexpress-product.
+    def aliexpress_product(product_id = nil, url: nil, country: nil, currency: nil)
+      post_json("/goods/aliexpress-product", {
+        product_id: product_id,
+        url: url,
+        country: country,
+        currency: currency,
+      })
+    end
+
     # Scrape Alibaba.com product search results.
     #
     # Searches Alibaba.com for `q` and returns the products as JSON: `productId`, `title`,
@@ -1286,6 +1475,734 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape MediaMarkt search.
+    #
+    # Searches a MediaMarkt shop (`country` de, at, ch, nl, be, es, it = MediaWorld, pl, hu, tr;
+    # `banner=saturn` for Saturn Germany) for `query` and returns `products`, each with
+    # `position`, `productId`, `offerId` (marketplace offers), `title`, `brand`, `ean`, `url`,
+    # `image`, `breadcrumbs`, `price`, `strikePrice` and `strikePriceType` (RRP = manufacturer's
+    # recommended price, LOP = lowest price of the last 30 days), `discountPercent`, `currency`,
+    # `installment`, `marketplace`, `seller` (marketplace seller with rating), `rating`,
+    # `reviewCount`, `availability` (online status, deliverable, store pickup, delivery window
+    # and shipping cost), `energyEfficiency`, `highlights` (key features), `badges`,
+    # `refurbishedFrom` and `sponsored`. Also `total`, `lastPage`, `nextPage` and `listingUrl`
+    # (the category or brand listing MediaMarkt sends this query to, when it does). `sort`
+    # orders the results; `page` and `max_results` page through them (MediaMarkt shows 12 per
+    # page and 30 pages at most). One unit per results page used.
+    #
+    # @param query [String] What to search for, e.g. 'iphone 17' or 'waschmaschine'.
+    # @param country [String] MediaMarkt shop: de, at, ch, nl, be, es, it, pl, hu, tr (default
+    # de; it = MediaWorld). API default: de.
+    # @param banner [String] mediamarkt (default) or saturn (Saturn Germany, with country=de).
+    # API default: mediamarkt.
+    # @param language [String] Site language where the shop has several: be = nl or fr, ch = de,
+    # fr or it. Default: the shop's first.
+    # @param sort [String] Result order: relevance, price_asc, price_desc, rating, bestseller,
+    # newest. API default: relevance.
+    # @param page [Integer] First results page to read (1-30). API default: 1.
+    # @param max_results [Integer] Products to collect across pages, 1-120. A page holds 12
+    # products; each page is one unit. API default: 12.
+    # Calls POST /marketplace/mediamarkt-search.
+    def mediamarkt_search(query, country: nil, banner: nil, language: nil, sort: nil, page: nil, max_results: nil)
+      post_json("/marketplace/mediamarkt-search", {
+        query: query,
+        country: country,
+        banner: banner,
+        language: language,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape a MediaMarkt product.
+    #
+    # Returns one MediaMarkt / Saturn / MediaWorld product by `product_id` (with `country` /
+    # `banner`) or `url`: `productId`, `title`, `rawTitle`, `brand`, `ean`, `url`,
+    # `breadcrumbs`, `kind`, `price`, `strikePrice`, `strikePriceType`, `discountPercent`,
+    # `currency`, `vatRate`, `installment`, `marketplace`, `seller`, `rating`, `reviewCount`,
+    # `ratingBreakdown` (1-5 stars), `availability` (online status, deliverable, store pickup,
+    # delivery window and shipping cost), `energyEfficiency` (class, label and data sheet),
+    # `highlights`, `specifications` (group / name / value / unit), `images`, `variants`
+    # (dimension, value, product id, price, online status), `badges`, `refurbishedFrom`,
+    # `description` and the latest `reviews`. Store-level stock needs a chosen store and is not
+    # included. One unit per call.
+    #
+    # @param product_id [String] MediaMarkt product number, e.g. 3071615 (the number at the end
+    # of a product link, or `productId` from the search results).
+    # @param url [String] A product link, e.g. https://www.mediamarkt.de/de/product/_apple-
+    # iphone-18-pro-max-256gb-silver-3071615.html. Used instead of `product_id`; its shop and
+    # language win over `country`, `banner` and `language`.
+    # @param country [String] MediaMarkt shop: de, at, ch, nl, be, es, it, pl, hu, tr (default
+    # de; it = MediaWorld). API default: de.
+    # @param banner [String] mediamarkt (default) or saturn (Saturn Germany, with country=de).
+    # API default: mediamarkt.
+    # @param language [String] Site language where the shop has several: be = nl or fr, ch = de,
+    # fr or it. Default: the shop's first.
+    # Calls POST /marketplace/mediamarkt-product.
+    def mediamarkt_product(product_id = nil, url: nil, country: nil, banner: nil, language: nil)
+      post_json("/marketplace/mediamarkt-product", {
+        product_id: product_id,
+        url: url,
+        country: country,
+        banner: banner,
+        language: language,
+      })
+    end
+
+    # Scrape Cdiscount search.
+    #
+    # Searches Cdiscount (France) for `query` and returns `products`, each with `position`,
+    # `productId` (the SKU), `offerId`, `title`, `url`, `image`, `images`, `price`,
+    # `strikePrice` (the crossed-out reference price, only when Cdiscount shows one),
+    # `discountPercent`, `currency` (EUR), `rating`, `reviewCount`, `seller` (id, name,
+    # `isCdiscount`), `marketplace`, `fulfilledByCdiscount`, `cdiscountAVolonte`,
+    # `freeShipping`, `deliveryLabel`, `condition`, `highlights` (key specs), `badges`
+    # (promotions) and `brandId`. Also `total`, `lastPage` and `nextPage`. Search results show
+    # the brand only as an id; the product endpoint has the brand name. `page` and `max_results`
+    # page through the results. One unit per Cdiscount page read.
+    #
+    # @param query [String] What to search for, e.g. 'iphone 15' or 'machine a laver'.
+    # @param page [Integer] First Cdiscount results page to read (1-100). API default: 1.
+    # @param max_results [Integer] Products to collect across pages, 1-300. A page holds about
+    # 47 products; each page is one unit. API default: 47.
+    # Calls POST /marketplace/cdiscount-search.
+    def cdiscount_search(query, page: nil, max_results: nil)
+      post_json("/marketplace/cdiscount-search", {
+        query: query,
+        page: page,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape a Cdiscount product.
+    #
+    # Returns one Cdiscount (France) product by `sku` or `url`: `productId`, `offerId`, `title`,
+    # `brand`, `ean`, `manufacturerReference`, `url`, `breadcrumbs`, `price`, `priceWithoutVat`,
+    # `strikePrice` and `strikePriceType`, `discountPercent`, `ecoParticipation`, `currency`,
+    # `available`, `maxQuantity`, `preorder`, `condition`, `seller` (Cdiscount or the
+    # marketplace seller), `marketplace`, `fulfilledByCdiscount`, `cdiscountAVolonte`,
+    # `delivery` (free shipping, label, ships from), `offers` (count of new and used offers and
+    # the lowest price of each), `rating`, `reviewCount`, `ratingBreakdown` (1-5 stars),
+    # `criteriaRatings`, `highlights`, `specifications` (group / name / value), `description`,
+    # `images`, `videos`, `variants` (attributes, price, url), `energyClass`,
+    # `repairabilityIndex`, `installments`, `badges`, `documents` and the latest `reviews`. The
+    # individual marketplace offers and their sellers' ratings are not included. One unit per
+    # call.
+    #
+    # @param sku [String] Cdiscount product id (SKU), e.g. ip17256black - the part after
+    # f-<number>- in a product link, or `productId` from the search results.
+    # @param url [String] A Cdiscount product link, e.g.
+    # https://www.cdiscount.com/telephonie/telephone-mobile/apple-iphone-17-256gb-
+    # black/f-14404-ip17256black.html. Used instead of `sku`.
+    # Calls POST /marketplace/cdiscount-product.
+    def cdiscount_product(sku = nil, url: nil)
+      post_json("/marketplace/cdiscount-product", {
+        sku: sku,
+        url: url,
+      })
+    end
+
+    # Scrape idealo search.
+    #
+    # Searches idealo (price comparison; `country` de, at, uk, fr, it or es) for `query` and
+    # returns `products`, each with `position`, `type` (product = a price comparison of many
+    # shops, offer = a single shop offer idealo has not matched to a product), `productId`,
+    # `offerId`, `title`, `subtitle`, `characteristics`, `url` (the product's price comparison,
+    # or the shop link of a single offer), `image`, `lowestPrice`, `basePrice` (unit price text,
+    # when idealo shows one), `offerCount`, `usedOnly`, `cheapestShop` (id, name, shipping cost,
+    # delivery, free-return days), `rating` (stars, rounded to half a star by idealo),
+    # `reviewCount`, `testGrade` (the average press test grade, where 1 is best), `energyClass`,
+    # `bargainSavingPercent`, `bestsellerRank`, `categoryId` and `variantOf`. Also `total`,
+    # `productCount`, `lastPage` and `nextPage`, and `currency`. `sort` orders the results
+    # (relevance or price_asc); `page` and `max_results` page through them. Use
+    # `/marketplace/idealo-offers` for all shop offers of one product. One unit per idealo page
+    # read.
+    #
+    # @param query [String] What to search for, e.g. 'iphone 17' or 'kaffeevollautomat'.
+    # @param country [String] idealo site: de, at, uk, fr, it, es (default de; uk =
+    # idealo.co.uk). API default: de.
+    # @param sort [String] Result order: relevance, price_asc (price_asc = cheapest first). API
+    # default: relevance.
+    # @param page [Integer] First idealo results page to read (1-100). API default: 1.
+    # @param max_results [Integer] Products to collect across pages, 1-300. A page holds 60
+    # products; each page is one unit. API default: 60.
+    # Calls POST /marketplace/idealo-search.
+    def idealo_search(query, country: nil, sort: nil, page: nil, max_results: nil)
+      post_json("/marketplace/idealo-search", {
+        query: query,
+        country: country,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape idealo offers of a product.
+    #
+    # Returns one idealo price comparison by `product_id` or `url` (`country` de, at, uk, fr, it
+    # or es): the product (`productId`, `title`, `brand`, `url`, `images`, `lowestPrice`,
+    # `highestPrice`, `currency`, `offerCount`, `rating`, `reviewCount`, `pros`, `cons`,
+    # `variants` with their own price range and offer count) and `offers`, cheapest first, each
+    # with `position`, `offerKey`, `title` (the shop's own product title), `price`,
+    # `shippingCost`, `totalPrice`, `delivery` (the shop's delivery estimate as idealo prints
+    # it), `carriers`, `freeReturns`, `paymentMethods`, `shop` (id, name, rating, rating count,
+    # marketplace and the marketplace seller), `variantId`, `variantName` and `url` (idealo's
+    # click-out link). Offers are the new-item offers idealo lists by default; `max_results`
+    # collects more than the first 20. One unit for the product and its first 20 offers, plus
+    # one per further block of 20.
+    #
+    # @param product_id [String] idealo product id, e.g. 207643424 (the number in a price
+    # comparison link, or `productId` from the search results).
+    # @param url [String] An idealo price comparison link, e.g.
+    # https://www.idealo.de/preisvergleich/OffersOfProduct/207643424_-iphone-17-apple.html. Used
+    # instead of `product_id`; its site sets the country.
+    # @param country [String] idealo site: de, at, uk, fr, it, es (default de; uk =
+    # idealo.co.uk).
+    # @param max_results [Integer] Offers to collect, 1-200. The first 20 come with the product;
+    # each further block of 20 is one more unit. API default: 20.
+    # Calls POST /marketplace/idealo-offers.
+    def idealo_offers(product_id = nil, url: nil, country: nil, max_results: nil)
+      post_json("/marketplace/idealo-offers", {
+        product_id: product_id,
+        url: url,
+        country: country,
+        max_results: max_results,
+      })
+    end
+
+    # Scrape Rakuten Ichiba (Japan) product search.
+    #
+    # Searches Rakuten Ichiba (rakuten.co.jp) for `query` and returns `products`, each with
+    # `position`, `itemId`, `itemCode`, `shopId` / `shopCode` / `shopName`, `title`, `subtitle`,
+    # `url`, `price` (yen, tax included; `priceMax` when variants are priced differently),
+    # `points` (Rakuten points a signed-out shopper earns) and `pointMultiplier`, `rating`,
+    # `reviewCount`, `shippingFee` / `freeShipping`, `deliveryEstimate`, `nextDayDelivery`,
+    # `unitPrice` / `unitPriceText` / `packCount`, `subscriptionPrice`, `saleEnds`, `ranking`
+    # (daily genre rank), `soldOut`, `used`, `preOrder`, `superDeal`, `hasVariants`, `genreId` /
+    # `genres`, `tags` and `image` / `images`. Rakuten's sponsored results come back in
+    # `sponsored` (same fields). Also `totalResults`, `reachableResults` (how far Rakuten lets
+    # the search be paged), `relatedKeywords` and `nextPage`. Sort with `sort`, filter with
+    # `min_price` / `max_price` / `genre_id`, start at `page` and collect up to `max_results`
+    # across pages (45 per page, each page billed as one request, see `pagesFetched`). `url`
+    # takes a Rakuten search link instead of `query`.
+    #
+    # @param query [String] What to search, in Japanese or English, e.g. 'iphone', 'コーヒー' or
+    # 'ナイキ スニーカー'.
+    # @param sort [String] Order: relevance, price_low, price_high, newest, review_count,
+    # review_score. API default: relevance.
+    # @param page [Integer] 1-based results page to start from (1-150; Rakuten lets a search be
+    # paged through to 6750 items). API default: 1.
+    # @param min_price [Integer] Lowest price, in yen.
+    # @param max_price [Integer] Highest price, in yen.
+    # @param genre_id [String] Limit to one Rakuten genre (category) id, e.g. '100227' (food) -
+    # every result's `genreId` is one.
+    # @param max_results [Integer] Items to collect across pages (1-450); Rakuten serves 45 per
+    # page and each page read is billed as one request. API default: 45.
+    # @param url [String] Instead of `query`: a Rakuten search link, e.g.
+    # https://search.rakuten.co.jp/search/mall/coffee/?s=2 (its keyword, genre, sort, page and
+    # price filter are used).
+    # Calls POST /marketplace/rakuten-search.
+    def rakuten_search(query = nil, sort: nil, page: nil, min_price: nil, max_price: nil, genre_id: nil, max_results: nil, url: nil)
+      post_json("/marketplace/rakuten-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        min_price: min_price,
+        max_price: max_price,
+        genre_id: genre_id,
+        max_results: max_results,
+        url: url,
+      })
+    end
+
+    # Scrape one Rakuten Ichiba (Japan) item's full detail.
+    #
+    # Fetches one Rakuten Ichiba item (by `product_id` '<shopCode>/<itemCode>' or `url`) and
+    # returns it as JSON: `itemId`, `itemCode`, `shopId` / `shopCode` / `shopName`, `url`,
+    # `title`, `tagline`, `description`, `condition`, `price` / `priceMax` (yen, tax included),
+    # `freeShipping`, `available`, `stockQuantity` (when the shop shares it), `deliveryMessage`,
+    # `orderLimit`, `rating`, `reviewCount`, `reviewsUrl`, `genreId`, `breadcrumbs`,
+    # `shopCategories`, `attributes` (name / value / unit), `variantOptions`, `variants` (every
+    # SKU with its options, price, availability, stock, JAN code and image) and `images`. The
+    # top-level price and stock are those of `variant_id` when given. Rakuten points are shown
+    # on search results (`/marketplace/rakuten-search`), not here. Companion to
+    # `/marketplace/rakuten-search`.
+    #
+    # @param product_id [String] The item as '<shopCode>/<itemCode>', e.g. 'dai-one/15-128-a'
+    # (the two path parts of an item link; search results give them as `shopCode` and
+    # `itemCode`).
+    # @param url [String] Instead of `product_id`: a Rakuten item link, e.g.
+    # https://item.rakuten.co.jp/dai-one/15-128-a/ (a `variantId` in it is used).
+    # @param variant_id [String] SKU whose price and stock fill the top-level fields, e.g.
+    # 'r-sku00003161'; by default the item's lowest price and overall availability. Every SKU is
+    # listed in `variants` either way.
+    # Calls POST /marketplace/rakuten-product.
+    def rakuten_product(product_id: nil, url: nil, variant_id: nil)
+      post_json("/marketplace/rakuten-product", {
+        product_id: product_id,
+        url: url,
+        variant_id: variant_id,
+      })
+    end
+
+    # Scrape IndiaMART B2B product search.
+    #
+    # Searches IndiaMART for `query` and returns `products`, each with `position`, `productId`,
+    # `title`, `url` (the IndiaMART product page, or the supplier's catalogue page when
+    # `hasProductPage` is false - only products with a page can be fetched with
+    # `/marketplace/indiamart-product`), `price` (number, null when the supplier asks for a
+    # quote) and `priceText`, `currency`, `unit` (the price is per this unit),
+    # `minOrderQuantity`, `category` / `categoryId`, `specifications` (name / value),
+    # `description`, `image`, `brochureUrl`, `supplier` (`id`, `name`, `city`, `district`,
+    # `state`, `country`, `businessType`, `verifiedExporter`, `trustSeal`, `gstVerified`,
+    # `iecVerified`, `rating`, `ratingCount`, `memberSince`, `exporterSince`, `exportsTo`,
+    # `website`) and `moreFromSupplier` (the supplier's other matching products). IndiaMART
+    # shows visitors outside India its export catalogue, so results are IndiaMART's verified
+    # exporters, 10 a page and 2 pages (up to 20 products per search); `totalResults` is
+    # IndiaMART's own count of all matches. Supplier phone numbers, e-mails and contact names
+    # are not returned. `url` takes an IndiaMART search link instead of `query`.
+    #
+    # @param query [String] What to search, e.g. 'steel pipe', 'cotton t shirt' or 'solar
+    # panel'.
+    # @param page [Integer] 1-based results page to start from (1-2); 10 products a page. API
+    # default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-20); IndiaMART serves 10
+    # per page and shows 2 pages. Each page read is billed as one request. API default: 20.
+    # @param url [String] Instead of `query`: an IndiaMART search link, e.g.
+    # https://dir.indiamart.com/search.mp?ss=steel+pipe (its keyword is used).
+    # Calls POST /marketplace/indiamart-search.
+    def indiamart_search(query = nil, page: nil, max_results: nil, url: nil)
+      post_json("/marketplace/indiamart-search", {
+        query: query,
+        page: page,
+        max_results: max_results,
+        url: url,
+      })
+    end
+
+    # Scrape one IndiaMART product and its supplier.
+    #
+    # Fetches one IndiaMART product (by `product_id` or `url`) and returns it as JSON:
+    # `productId`, `title`, `name`, `url`, `price` (null when the supplier asks for a quote) /
+    # `priceText`, `currency`, `unit`, `minOrderQuantity`, `description`, `specifications` (name
+    # / value), `category` / `categoryId` / `parentCategory` / `group`, `deliveryTime`,
+    # `packagingDetails`, `productionCapacity`, `portOfDispatch`, `paymentTerms`, `image` /
+    # `images`, `brochureUrl` and `supplier` (`id`, `name`, `city`, `state`, `country`,
+    # `businessType`, `additionalBusiness`, `yearEstablished`, `employees`, `annualTurnover`,
+    # `legalStatus`, `gstVerified`, `trustSeal`, `mobileVerified`, `emailVerified`, `rating`,
+    # `ratingCount`, `memberSince`, `topExportCountries`, `website`, `logo`). Supplier phone
+    # numbers, e-mails, people's names and street addresses are not returned. Companion to
+    # `/marketplace/indiamart-search`.
+    #
+    # @param product_id [String] IndiaMART product id, e.g. '2854548650133' (the number at the
+    # end of a /proddetail/ link; search results give it as `productId`).
+    # @param url [String] Instead of `product_id`: an IndiaMART product link, e.g.
+    # https://www.indiamart.com/proddetail/stainless-steel-347h-pipes-2854548650133.html.
+    # Calls POST /marketplace/indiamart-product.
+    def indiamart_product(product_id: nil, url: nil)
+      post_json("/marketplace/indiamart-product", {
+        product_id: product_id,
+        url: url,
+      })
+    end
+
+    # Scrape Bed Bath & Beyond product search.
+    #
+    # Searches Bed Bath & Beyond (bedbathandbeyond.com, US) for `query` and returns the products
+    # as JSON: `productId`, `sku`, `title`, `url`, `image`, `price` (the lowest option price)
+    # and `priceMax` (the top of the range when options differ), `priceText`, `priceType` (SALE
+    # or STANDARD), `currency` (USD), `comparePrice` with `compareType` (MSRP, COMPARE_AT or
+    # WAS), `discountPercent`, `regularPrice`, `hasOptions`, `optionCount`, `rating`,
+    # `reviewCount`, `badge` (e.g. Best Seller), `onSale`, `fastDelivery`, `rewards` (Welcome
+    # Rewards dollars) and `sponsored`. Sort with `sort`, start at `page`, and collect up to
+    # `max_results` across pages (about 60 per page, each page billed as one request, see
+    # `pagesFetched`). Keywords the site maps to a department (e.g. 'rugs') return that
+    # department's listing, named in `redirectedTo`. `url` takes a search link instead of
+    # `query`.
+    #
+    # @param query [String] What to search, e.g. 'bath towels', 'office chair' or 'table lamp'.
+    # @param sort [String] Order: relevance, on_sale, best_selling, price_low, price_high,
+    # rating, newest. API default: relevance.
+    # @param page [Integer] 1-based results page to start from (1-100). API default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-300); the site serves
+    # about 60 per page and each page fetched is billed as one request. API default: 60.
+    # @param url [String] Instead of `query`: a Bed Bath & Beyond search link, e.g.
+    # https://www.bedbathandbeyond.com/search?keywords=towels (its sort and page are used).
+    # Calls POST /marketplace/bedbathandbeyond-search.
+    def bedbathandbeyond_search(query = nil, sort: nil, page: nil, max_results: nil, url: nil)
+      post_json("/marketplace/bedbathandbeyond-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+        url: url,
+      })
+    end
+
+    # Scrape one Bed Bath & Beyond product's full detail.
+    #
+    # Fetches one Bed Bath & Beyond product (by id or link) and returns it as JSON: `productId`,
+    # `sku`, `url`, `title`, `brand`, `brandUrl`, `manufacturerPartNumber`, `price` with
+    # `priceLabel` (e.g. 'Sale Starts at' when options are priced differently), `comparePrice`
+    # with `compareLabel` (MSRP, Was, At other retailer), `savings`, `savingsPercent`,
+    # `currency` (USD), `inStock`, `rating`, `reviewCount`, `ratingHistogram`, `badge`,
+    # `shortDescription`, `description`, `countryOfOrigin`, `freeShipping`,
+    # `internationalShipping`, `firstListed`, `breadcrumbs`, `specifications` (group / name /
+    # value), `optionCount`, `defaultOptionId`, `options` (up to 100: option id, title, size /
+    # colour attributes, price, regular price, compare price, on-sale flag, stock and quantity
+    # on hand), `images` and `videos`. Prices are those shown to a signed-out shopper. Companion
+    # to `/marketplace/bedbathandbeyond-search`.
+    #
+    # @param product [String] A Bed Bath & Beyond product id (e.g. '5296998', the number before
+    # /product.html) or a product link.
+    # Calls POST /marketplace/bedbathandbeyond-product.
+    def bedbathandbeyond_product(product)
+      post_json("/marketplace/bedbathandbeyond-product", {
+        product: product,
+      })
+    end
+
+    # Scrape Petco product search.
+    #
+    # Searches Petco (petco.com, US) for `query` and returns the products as JSON: `sku`,
+    # `productId`, `title`, `familyName`, `brand`, `url`, `image`, `price`, `listPrice`,
+    # `autoshipPrice` (the Repeat Delivery price), `onSale`, `currency` (USD), `rating`,
+    # `reviewCount`, `description`, `category`, `autoshipEligible`, `pickupEligible`,
+    # `sameDayDeliveryEligible`, `inStoreOnly`, `prescriptionFood`, `attributes` (brand,
+    # flavour, life stage...) and `variations` (every size / colour with its SKU, url and
+    # prices). Sort with `sort`, narrow with `brand`, `fulfillment` (delivery, autoship, pickup,
+    # same_day) and `min_price` / `max_price`, start at `page` and collect up to `max_results`
+    # (48 per page, each page billed as one request, see `pagesFetched`). A term Petco sends to
+    # a brand or category page (e.g. a brand name) returns that page's listing, named in
+    # `redirectedTo`. Prices are the online prices a signed-out shopper sees; store-specific
+    # stock and member (Vital Care) prices are not included.
+    #
+    # @param query [String] What to search, e.g. 'dog food', 'cat litter' or 'fish tank'.
+    # @param sort [String] Order: relevance, price_low, price_high, rating, popular, newest,
+    # name_asc, name_desc. API default: relevance.
+    # @param page [Integer] 1-based results page to start from (1-200), 48 products per page as
+    # on petco.com. API default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-480); each page of 48
+    # fetched is billed as one request. API default: 48.
+    # @param brand [String] Only this brand, as petco.com names it (e.g. 'Purina Pro Plan'; the
+    # `brands` list of a search shows the names).
+    # @param fulfillment [String] Only products offered this way: delivery, autoship, pickup,
+    # same_day.
+    # @param min_price [Float] Lowest price to include (USD).
+    # @param max_price [Float] Highest price to include (USD).
+    # @param url [String] Instead of `query`: a petco.com search link, e.g.
+    # https://www.petco.com/shop/en/petcostore/search?query=dog%20food.
+    # Calls POST /marketplace/petco-search.
+    def petco_search(query = nil, sort: nil, page: nil, max_results: nil, brand: nil, fulfillment: nil, min_price: nil, max_price: nil, url: nil)
+      post_json("/marketplace/petco-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+        brand: brand,
+        fulfillment: fulfillment,
+        min_price: min_price,
+        max_price: max_price,
+        url: url,
+      })
+    end
+
+    # Scrape one Petco product's full detail.
+    #
+    # Fetches one Petco product (by SKU or link) and returns it as JSON: `sku`, `catEntryId`,
+    # `parentSku`, `url`, `title`, `brand`, `upc`, `price`, `listPrice`, `autoshipPrice`,
+    # `pickupPrice`, `onSale`, `currency` (USD), `availability`, `inStock`, `availableQuantity`
+    # (online stock), `rating`, `reviewCount`, `ratingHistogram`, `recommendedPercent`,
+    # `description`, `highlights`, `ingredients`, `directions`, `specifications` (group / name /
+    # value), `attributes` (size / weight / colour of this variant), `dimensions`, `petType`,
+    # `category`, `breadcrumbs`, fulfillment flags (`autoshipEligible`, `pickupEligible`,
+    # `sameDayDeliveryEligible`, `onlineOnly`, `inStoreOnly`), `prescriptionRequired`,
+    # `discontinued`, `images`, `variants` (every size / colour with its SKU, url, prices and
+    # stock) and the first `reviews` (up to 10). A link's own variant is returned; a SKU picks
+    # that variant. Prices are the online prices a signed-out shopper sees (no member or store
+    # prices). Companion to `/marketplace/petco-search`.
+    #
+    # @param product [String] A Petco SKU (the number a product link ends in, e.g. '3748364') or
+    # a petco.com product link.
+    # Calls POST /marketplace/petco-product.
+    def petco_product(product)
+      post_json("/marketplace/petco-product", {
+        product: product,
+      })
+    end
+
+    # Scrape one Neobits product.
+    #
+    # Fetches one product from Neobits (neobits.com, US B2B electronics and IT reseller) by item
+    # number or link and returns it as JSON: `itemNumber`, `url`, `title`, `brand`, `brandUrl`,
+    # `mfrPartNumber`, `price`, `listPrice`, `savings`, `discountPercent`, `priceDrop`,
+    # `currency` (USD), `stockStatus` (e.g. In Stock, SHIPS SOON), `inStock`, `stockNote`,
+    # `leadTime` (the brand's average lead time when shown), `rating`, `reviewCount`,
+    # `questionCount`, `description`, `specifications` (name / value), `breadcrumbs` and
+    # `images`. Neobits search is not offered: the site gates its search and listing pages
+    # behind a reCAPTCHA for automated traffic.
+    #
+    # @param product [String] A Neobits item number (the 'Item #' on a product page, e.g.
+    # '27956233') or a neobits.com product link (ending in _p<item>.html).
+    # Calls POST /marketplace/neobits-product.
+    def neobits_product(product)
+      post_json("/marketplace/neobits-product", {
+        product: product,
+      })
+    end
+
+    # Scrape Lowe's product search.
+    #
+    # Searches Lowe's (lowes.com, US) for `query` at one store and returns `products`:
+    # `productId` (Lowe's item id), `itemNumber`, `modelNumber`, `brand`, `title`, `url`,
+    # `image`, `rating`, `reviewCount`, `price`, `wasPrice`, `savings`, `savingsPercent` and
+    # `saleEnds` (promotions), `clearance`, `minPrice` / `maxPrice` (items with options),
+    # `priceType` (store, network = Lowe's online price, sos = special order), `currency`,
+    # `availability` (`pickup` with the units on hand at the store, `parcel`, `delivery`,
+    # `expeditedDelivery`), `sponsored`, `marketplace`, `bullets` and `specifications`, plus
+    # `store` (the store the prices and stock are for) and paging totals. Set the store with
+    # `store_id` or `zip` (default: store 1845, Chicago-Brickyard, IL). Results come in Lowe's
+    # own order; `free_delivery` keeps free-delivery items only. Start at `page` and collect up
+    # to `max_results` across pages (24 per page, each page billed as one request, see
+    # `pagesFetched`). A broad keyword Lowe's sends to a category landing page (e.g. patio
+    # furniture) is answered from the landing page's first category tile that names the keyword;
+    # `category` names it (null for a plain search). A landing page without such a tile answers
+    # 404: search a more specific term.
+    #
+    # @param query [String] What to search, e.g. 'cordless drill', 'garden hose' or 'interior
+    # paint'.
+    # @param page [Integer] 1-based results page to start from (1-30, 24 products per page). API
+    # default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-72); each page fetched is
+    # billed as one request. API default: 24.
+    # @param store_id [String] Lowe's store number whose prices and stock to return, e.g.
+    # '1845'. Give this or `zip`; with neither, store 1845 (Chicago-Brickyard, IL) is used. The
+    # store used is named in `store`.
+    # @param zip [String] US ZIP code; the nearest Lowe's store is used, e.g. '60639'.
+    # @param free_delivery [Boolean] Only items Lowe's delivers for free. API default: false.
+    # @param url [String] Instead of `query`: a Lowe's search link, e.g.
+    # https://www.lowes.com/search?searchTerm=garden+hose (its offset and storeId are used).
+    # Calls POST /marketplace/lowes-search.
+    def lowes_search(query = nil, page: nil, max_results: nil, store_id: nil, zip: nil, free_delivery: nil, url: nil)
+      post_json("/marketplace/lowes-search", {
+        query: query,
+        page: page,
+        max_results: max_results,
+        store_id: store_id,
+        zip: zip,
+        free_delivery: free_delivery,
+        url: url,
+      })
+    end
+
+    # Scrape one Lowe's product.
+    #
+    # Fetches one Lowe's product (by `product_id` or `url`) priced for one store and returns it
+    # as JSON: `productId`, `itemNumber`, `modelNumber`, `upc`, `brand`, `title`, `url`,
+    # `rating`, `reviewCount`, `price`, `wasPrice`, `savings`, `savingsPercent`, `saleEnds`,
+    # `clearance`, `priceType`, `currency`, `storeId`, `availability` (`pickup` with the units
+    # on hand at the store and at `nearbyStores`, `parcel`, `delivery`, `expeditedDelivery` with
+    # lead times), `description`, `bullets`, `specifications` (name / value / group), `images`,
+    # `videos`, `documents`, `category`, `dimensions`, `weightLbs`, `buyable` and `status`, plus
+    # `store`. Set the store with `store_id` or `zip` (default: store 1845, Chicago-Brickyard,
+    # IL). Companion to `/marketplace/lowes-search`.
+    #
+    # @param product_id [String] Lowe's item id, e.g. '5016412045' (the number at the end of a
+    # product link; the `productId` of a search result).
+    # @param url [String] Instead of `product_id`: a Lowe's product link, e.g.
+    # https://www.lowes.com/pd/CRAFTSMAN-20-volt-Max-Drill/5016412045.
+    # @param store_id [String] Lowe's store number whose prices and stock to return, e.g.
+    # '1845'. Give this or `zip`; with neither, store 1845 (Chicago-Brickyard, IL) is used. The
+    # store used is named in `store`.
+    # @param zip [String] US ZIP code; the nearest Lowe's store is used, e.g. '60639'.
+    # Calls POST /marketplace/lowes-product.
+    def lowes_product(product_id = nil, url: nil, store_id: nil, zip: nil)
+      post_json("/marketplace/lowes-product", {
+        product_id: product_id,
+        url: url,
+        store_id: store_id,
+        zip: zip,
+      })
+    end
+
+    # Scrape Menards product search.
+    #
+    # Searches Menards (menards.com, US) for `query` and returns `products`: `itemId`, `sku`
+    # (the Menards SKU), `modelNumber` (when Menards lists it), `title`, `brand`, `url`,
+    # `image`, `price` (shelf price before the mail-in rebate), `regularPrice` (everyday low
+    # price), `onSale`, `rebate` and `rebateLabel` (Menards' rebate, usually 11%),
+    # `priceAfterRebate` (null when the maker's advertised-price policy moves it to checkout:
+    # `priceInCheckout` true, `minimumAdvertisedPrice`), `unitOfMeasure`, `currency`,
+    # `availability` (`pickup`, `delivery`, `stockAtStore`, `stockMessage`, `deliveryMessage`),
+    # `variationCount` and `categoryId`, plus `totalResults`, `facets` and `store` (the store
+    # the prices and stock are for). Set the store with `store_id` or `zip`; without one Menards
+    # shows its default online prices and no store stock. Sort with `sort`, filter with
+    # `min_price` / `max_price`, `in_stock_today`, `delivery_eligible` and `pickup_eligible`,
+    # start at `page` and collect up to `max_results` across pages (40 per page, each page
+    # billed as one request, see `pagesFetched`). A keyword Menards sends to a category returns
+    # that category's products (`redirectedTo`); a Menards SKU returns no products and the
+    # product link in `redirectedTo`. A keyword Menards sends to a page of category tiles (e.g.
+    # interior paint) or one with no matches answers 404.
+    #
+    # @param query [String] What to search, e.g. 'cordless drill', 'garden hose' or '2x4
+    # lumber'.
+    # @param sort [String] Order: relevance, price_low, price_high, title_asc, title_desc,
+    # brand_asc, brand_desc. API default: relevance.
+    # @param page [Integer] 1-based results page to start from (1-100, 40 products per page).
+    # API default: 1.
+    # @param max_results [Integer] Products to collect across pages (1-120); each page fetched
+    # is billed as one request. API default: 40.
+    # @param min_price [Float] Lowest price to include (USD).
+    # @param max_price [Float] Highest price to include (USD).
+    # @param store_id [String] Menards store number whose prices and stock to return, e.g.
+    # '3181'. Give this or `zip`; with neither, Menards' default (online) prices are returned
+    # and `stockAtStore` is 0. The store used is named in `store`.
+    # @param zip [String] US ZIP code; the nearest Menards store is used, e.g. '55401'.
+    # @param in_stock_today [Boolean] Only items in stock today at the store (needs `store_id`
+    # or `zip`). API default: false.
+    # @param delivery_eligible [Boolean] Only items eligible for delivery. API default: false.
+    # @param pickup_eligible [Boolean] Only items eligible for in-store pickup. API default:
+    # false.
+    # Calls POST /marketplace/menards-search.
+    def menards_search(query, sort: nil, page: nil, max_results: nil, min_price: nil, max_price: nil, store_id: nil, zip: nil, in_stock_today: nil, delivery_eligible: nil, pickup_eligible: nil)
+      post_json("/marketplace/menards-search", {
+        query: query,
+        sort: sort,
+        page: page,
+        max_results: max_results,
+        min_price: min_price,
+        max_price: max_price,
+        store_id: store_id,
+        zip: zip,
+        in_stock_today: in_stock_today,
+        delivery_eligible: delivery_eligible,
+        pickup_eligible: pickup_eligible,
+      })
+    end
+
+    # Scrape one Menards product.
+    #
+    # Fetches one Menards product (by `url` or `sku`) and returns it as JSON: `itemId`, `sku`,
+    # `modelNumber`, `title`, `brand`, `url`, `price` (shelf price), `regularPrice` (everyday
+    # low price), `onSale` and `saleEnds`, `minimumAdvertisedPrice` and `priceInCheckout` (items
+    # whose maker lets Menards show its price only in checkout: `price` is then null), `rebate`,
+    # `rebateLabel`, `rebateEnds`, `priceAfterRebate`, `offerPrice`, `currency`, `availability`,
+    # `storeId`, `description`, `features`, `specifications` (name / value), `images` and
+    # `breadcrumbs`. Prices are Menards' default online prices (the store in `storeId`); for one
+    # store's prices and stock use `/marketplace/menards-search` with `store_id` or `zip`.
+    #
+    # @param url [String] A Menards product link, e.g.
+    # https://www.menards.com/main/electrical/electrical-tools-accessories/electrical-hand-
+    # tools/southwire-reg-7-1-2-mc-rotary-cutter/mccut/p-60893668339-c-6455.htm (the `url` of a
+    # search result).
+    # @param sku [String] Instead of `url`: the Menards SKU shown on the product page and in
+    # search results, e.g. '3646903'.
+    # Calls POST /marketplace/menards-product.
+    def menards_product(url: nil, sku: nil)
+      post_json("/marketplace/menards-product", {
+        url: url,
+        sku: sku,
+      })
+    end
+
+    # Scrape Grainger product search.
+    #
+    # Searches Grainger (grainger.com, US industrial supplies) for `query` and returns
+    # Grainger's first result rows (up to 25 items, in Grainger's order) as `products`:
+    # `position`, `sku` (Grainger item number), `productId`, `title`, `brand`,
+    # `manufacturerModel`, `url`, `image`, `price` (Grainger's signed-out Web Price),
+    # `priceLabel`, `priceType`, `wasPrice`, `quantityPricing`, `currency`, `status` (e.g.
+    # Sellable) and `specifications` (name / value, e.g. thread size, voltage, material).
+    # Grainger answers a keyword with the product category that matches it best: `category`
+    # names it, `totalResults` counts that category's matches, and `categories` lists the other
+    # matching categories with counts and links (search one of them by passing its link as
+    # `url`). A keyword that leads to a department page (subcategory tiles, no products) is
+    # answered from the subcategory holding the product line that matches it most often:
+    # `category` names that subcategory, `totalAcrossCategories` counts the department and
+    # `categories` lists its subcategories. Only the first result rows are returned (no paging).
+    # Stock is not included: Grainger checks it per ZIP code after the page loads.
+    #
+    # @param query [String] What to search, e.g. 'safety glasses', 'hex bolt', 'cordless drill'
+    # or a manufacturer model.
+    # @param max_results [Integer] Items to return (1-25); Grainger's first result rows for the
+    # keyword. API default: 25.
+    # @param url [String] Instead of `query`: a Grainger search link, e.g.
+    # https://www.grainger.com/search?searchQuery=hex+bolt.
+    # Calls POST /marketplace/grainger-search.
+    def grainger_search(query = nil, max_results: nil, url: nil)
+      post_json("/marketplace/grainger-search", {
+        query: query,
+        max_results: max_results,
+        url: url,
+      })
+    end
+
+    # Scrape one Grainger product.
+    #
+    # Fetches one Grainger item (by `sku`, the Grainger item number, or `url`) and returns it as
+    # JSON: `sku`, `productId`, `title`, `brand`, `manufacturerModel`, `url`, `price` (signed-
+    # out Web Price), `priceLabel`, `priceType`, `wasPrice`, `unitOfMeasure` (e.g. 'pkg. of
+    # 100'), `quantityPricing`, `currency`, `status`, `discontinued`, `sellInfo`,
+    # `shippingWeight`, `description`, `specifications` (name / value, including UNSPSC and
+    # country of origin), `images`, `documents` (spec sheets, drawings), `alternateSkus` and
+    # `breadcrumbs`. Stock is not included: Grainger checks it per ZIP code after the page
+    # loads.
+    #
+    # @param sku [String] Grainger item number, e.g. '1XE66' or '22TA59' (the `sku` of a search
+    # result).
+    # @param url [String] Instead of `sku`: a Grainger product link, e.g.
+    # https://www.grainger.com/product/Hex-Head-Cap-Screw-Stainless-1XE66.
+    # Calls POST /marketplace/grainger-product.
+    def grainger_product(sku = nil, url: nil)
+      post_json("/marketplace/grainger-product", {
+        sku: sku,
+        url: url,
+      })
+    end
+
+    # Scrape one eBay listing's full detail.
+    #
+    # Fetches one eBay listing (by `item_id` + `marketplace`, or `url`) on any supported eBay
+    # site and returns it as JSON: `itemId`, `title`, `status` (active / ended), `price` +
+    # `currency`, `originalPrice` (list or was price), `listingFormat` (buy_it_now, auction,
+    # auction_with_buy_it_now) with `buyItNowPrice`, `currentBid`, `bidCount`, `reserveMet` and
+    # `endsAt`, `listingPrice` / `listingCurrency` when the seller lists in another currency,
+    # `condition` (with `conditionCode` and the seller's `conditionNotes`), `availability`,
+    # `quantityAvailable`, `quantitySold`, `watchers`, `seller` (username, store name, feedback
+    # score, positive percentage, business or private), `shippingRates` (cost per destination
+    # country), `shipping`, `itemLocation`, `delivery`, `importFees`, `returns`, `brand`, `mpn`,
+    # `gtin`, `itemSpecifics`, `categories`, `paymentMethods`, `variationOptions` and
+    # `variations` (each with its own price and stock), `images` and the seller's `description`
+    # as text. Labels and texts follow the site's language (ebay.de answers in German).
+    # Shipping, delivery dates and, on EU sites, VAT-inclusive prices are quoted for the country
+    # the request comes from: pass `proxy_country` to fix it. Companion to `/marketplace/ebay-
+    # search`.
+    #
+    # @param item_id [String] eBay item number, e.g. '335761219642' (the number in
+    # ebay.com/itm/335761219642).
+    # @param url [String] Instead of `item_id`: a listing link on any supported eBay site, e.g.
+    # https://www.ebay.de/itm/860089403886. The site is taken from the link.
+    # @param marketplace [String] eBay site to open `item_id` on (prices, currency and language
+    # follow it). One of: ebay.com, ebay.co.uk, ebay.de, ebay.fr, ebay.it, ebay.es, ebay.nl,
+    # ebay.pl, ebay.at, ebay.ch, ebay.be, ebay.ie, ebay.ca, ebay.com.au, ebay.in, ebay.com.sg,
+    # ebay.com.my, ebay.com.hk. Default ebay.com.
+    # @param include_description [Boolean] Also fetch the seller's description text (a second,
+    # light request). Set false for a faster call without `description`. API default: true.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). eBay quotes shipping, delivery dates and, on EU sites, VAT-inclusive prices for the
+    # visitor's country, so set it to get them for one country.
+    # Calls POST /marketplace/ebay-product.
+    def ebay_product(item_id: nil, url: nil, marketplace: nil, include_description: nil, proxy_country: nil)
+      post_json("/marketplace/ebay-product", {
+        item_id: item_id,
+        url: url,
+        marketplace: marketplace,
+        include_description: include_description,
+        proxy_country: proxy_country,
+      })
+    end
+
     # Scrape Vinted product search.
     #
     # Searches Vinted for `query` and returns the listings as JSON: `title`, `price` and
@@ -2615,8 +3532,8 @@ module ScrapeUnblocker
     # `url`, or a raw `feature_id` (0xHEX:0xHEX). Location-neutral - the feature id resolves the
     # place directly; `proxy_country` defaults to a US proxy to clear Google's consent wall.
     #
-    # @param url [String] A Google Maps place URL (share link or /maps/place/... URL). The
-    # feature id or place_id is read out of it.
+    # @param url [String] A Google Maps place URL: a /maps/place/... URL, a maps.app.goo.gl
+    # share link or a maps?cid= link. The place is read out of it.
     # @param place_id [String] A Google place_id, e.g. 'ChIJN1t_tDeuEmsRUsoyG83frY4'.
     # @param feature_id [String] A Maps feature id '0xHEX:0xHEX', e.g.
     # '0x47e66e2964e34e2d:0x8ddca9ee380ef7e0'. Fastest - no resolve step.
@@ -2638,6 +3555,51 @@ module ScrapeUnblocker
       })
     end
 
+    # Scrape Google Maps reviews.
+    #
+    # Returns one Google Maps place's reviews as JSON, sorted the way Google sorts them:
+    # `relevant`, `newest`, `highest` or `lowest`. Each review has `rating` (1-5), `date` (exact
+    # ISO 8601, UTC) + `timestamp`, `relativeDate`, `text` (original) + `language`,
+    # `translatedText` (into `hl`, when the review is in another language), `author`, `photos`,
+    # `details` (guided answers such as 'Rooms: 5'), `ownerResponse` and `reviewUrl`. The answer
+    # also carries a `place` summary and `nextPageToken` for paging. Identify the place with
+    # `feature_id` (0xHEX:0xHEX), `place_id` (ChIJ...) or a Maps `url`. Reviews come in pages of
+    # 20; each page fetched is one billed unit.
+    #
+    # @param url [String] A Google Maps place URL: a /maps/place/... URL, a maps.app.goo.gl
+    # share link or a maps?cid= link. The place is read out of it.
+    # @param place_id [String] A Google place_id, e.g. 'ChIJN1t_tDeuEmsRUsoyG83frY4'.
+    # @param feature_id [String] A Maps feature id '0xHEX:0xHEX', e.g.
+    # '0x4776901a5d4813b3:0x2a497c8b414893c'. Fastest - no resolve step.
+    # @param sort [String] Review order: 'relevant' (Google's default), 'newest', 'highest' or
+    # 'lowest'. SerpApi's 'qualityScore', 'newestFirst', 'ratingHigh' and 'ratingLow' are
+    # accepted too. API default: relevant.
+    # @param max_reviews [Integer] How many reviews to return, 1-200. Reviews come in pages of
+    # 20; each page fetched is one billed unit. API default: 20.
+    # @param next_page_token [String] Continue from a previous answer's `nextPageToken` (same
+    # place and sort). When `max_reviews` is not a multiple of 20 the next page can repeat a few
+    # reviews - dedupe on `reviewId`.
+    # @param hl [String] Language for Google's labels and the review translation
+    # (`translatedText`), e.g. 'en', 'de'. The original text is always returned in `text`. API
+    # default: en.
+    # @param gl [String] Google country, ISO-2 lowercase, e.g. 'us'. API default: us.
+    # @param proxy_country [String] Proxy country the request is sent from (ISO-2, e.g. 'US',
+    # 'DE'). Reviews are the same from any country. API default: us.
+    # Calls POST /maps/reviews.
+    def maps_reviews(url: nil, place_id: nil, feature_id: nil, sort: nil, max_reviews: nil, next_page_token: nil, hl: nil, gl: nil, proxy_country: nil)
+      post_json("/maps/reviews", {
+        url: url,
+        place_id: place_id,
+        feature_id: feature_id,
+        sort: sort,
+        max_reviews: max_reviews,
+        next_page_token: next_page_token,
+        hl: hl,
+        gl: gl,
+        proxy_country: proxy_country,
+      })
+    end
+
     # Scrape Google Hotels search results (prices, ratings, amenities).
     #
     # Runs a Google Hotels search for `q` and returns the properties as JSON: `name`, `type`
@@ -2928,6 +3890,31 @@ module ScrapeUnblocker
       })
     end
 
+    # Ask ChatGPT and get its answer and cited sites.
+    #
+    # Asks ChatGPT (chatgpt.com, signed out) one question and returns its finished answer:
+    # `answer` (plain text) and `answerMarkdown`, `citations` (the source pills ChatGPT attaches
+    # to claims: `position`, `siteName`, `domain`, `moreSources` - how many further sources the
+    # pill groups - and `citedText`, the answer text it backs), `links` (links written into the
+    # answer: `position`, `title`, `url`, `domain`), `sources` (every site cited or linked,
+    # once), `webSearch` (whether ChatGPT searched the web), `model` (null: signed-out ChatGPT
+    # does not show it) and `conversationId`. Signed-out ChatGPT shows the full URL of a cited
+    # page only on hover, so citations carry the site and domain, not the page URL. `country`
+    # asks from that country. Answers take 15-60 s and vary between identical calls, as they do
+    # for people. One unit per call; a 503 when ChatGPT capacity is busy is not billed.
+    #
+    # @param prompt [String] The question to ask ChatGPT, as a user would type it, e.g. 'best
+    # CRM for small business' (max 2000 characters). Each call starts a new conversation.
+    # @param country [String] Two-letter country code to ask from, e.g. US, GB, DE. ChatGPT
+    # tailors local results to where the visitor is. Leave blank for any location.
+    # Calls POST /ai/chatgpt.
+    def chatgpt(prompt, country: nil)
+      post_json("/ai/chatgpt", {
+        prompt: prompt,
+        country: country,
+      })
+    end
+
     # Search Bing.
     #
     # Searches Bing for `keyword` in a real browser and returns the results page as JSON:

data/lib/scrapeunblocker/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scrapeunblocker
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.17.0
 platform: ruby
 authors:
 - ScrapeUnblocker