scrapeunblocker 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 506dfab9e7e8c63f8b2808a9f7cdf8b113a509fe94b1841c2e8970a33e2bc451
-  data.tar.gz: b1bc717e7851b88651cf6960cabfb8d9298589d0494040be702a1c9ce5d953e4
+  metadata.gz: 9349609e20a6b8949d1cc3d77b919cf6c916b4b1917d181bb2d18ec441f46777
+  data.tar.gz: 55bf0f292146e6e166a502ecb43a33d15b2629261f808ed8754f4ca7a33d96fe
 SHA512:
-  metadata.gz: 5f1901a2940ae350e8603fe8cb4776ecdb433173340010ec8c320ef063c6f4d906ebd135ca36359a3d708b2722826f1db77d56d785724ff7c5a7bbddef01db4b
-  data.tar.gz: 0dce31734e4c853bae21c43581880ff84251990ba1ea8a8023002b4705d669206141b10ec8dea45db4fe825a384334a3d7cbe5b07d3feeba0bb5ef50c7b49f94
+  metadata.gz: 22da248af5842639758605b333930c888534405b796cd199f9c8a2c8bced4104e6dace474c62fbaa2aa878d321878aef3118121fb0563efc4f25a1d2c00451b6
+  data.tar.gz: 3fea75e8eb0602eb156978c019fea92fe7cfca41aab0714f9049412d26207e707899750ad8547b0caf57d3da368d347d2f2ead34e82d74ee2d4764de5f90afb9

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.12.0 (2026-10-15)
+
+- `google_images` takes `time_range:` (`"hour"`, `"day"`, `"week"`, `"month"` or `"year"`) to return only the images Google found in that recent period, so a query scanned on a schedule returns only what is new. For a fixed window pass `date_from:` and/or `date_to:` (`"YYYY-MM-DD"`) instead; the API answers 400 when `time_range` is combined with either.
+
+No breaking changes.
+
+## 0.11.1 (2026-10-15)
+
+- `get_image` docs: the API now returns the image's original bytes and format (JPEG, PNG, WebP, AVIF, GIF, SVG, ...) instead of a PNG re-encode. The method still returns a binary `String`.
+- A missing image (the host's own 404/410) raises `TargetNotFoundError`; a URL that is not an image raises `UnsupportedContentError`. The 415 message no longer says "does not serve HTML", which was wrong for `get_image`.
+
 ## 0.11.0 (2026-10-13)
 
 - Removed four plugin methods added in 0.10.0: `youtube_comments`, `telegram_channel`, `quora_question` and `quora_profile`. Those plugins are no longer offered through the SDKs; `plugin(path, params)` still reaches any endpoint your account can use.

data/README.md

@@ -174,8 +174,15 @@ local["results"].each { |biz| puts "#{biz['name']} #{biz['rating']} #{biz['addre
 ```ruby
 images = su.google_images("golden retriever puppy", proxy_country: "US", pages: 3)
 images["results"].each { |img| puts "#{img['imageUrl']} #{img['sourceDomain']} #{img['title']}" }
+
+# Only images Google found in the last day (for a daily scan of the same query)
+new_images = su.google_images("eiffel tower", proxy_country: "US", time_range: "day")
+# Or a fixed window: date_from / date_to (YYYY-MM-DD), each one optional
+october = su.google_images("eiffel tower", date_from: "2026-10-01", date_to: "2026-10-07")
 ```
 
+`time_range` takes `hour`, `day`, `week`, `month` or `year` and cannot be combined with `date_from` / `date_to`.
+
 ## Meta Ad Library
 
 ```ruby
@@ -242,6 +249,8 @@ bytes = su.get_image("https://example.com/photo.jpg")
 File.binwrite("photo.jpg", bytes)
 ```
 
+The bytes come back exactly as the image host serves them, in the original format (JPEG, PNG, WebP, AVIF, GIF, SVG, ...); nothing is re-encoded. Pass the image URL itself, not the page it sits on.
+
 ## Skyscanner plugins
 
 Flights, hotels and car hire as JSON:
@@ -287,10 +296,10 @@ end
 | `BudgetExceededError` | 402 | This billing period's spend reached the monthly budget limit you set |
 | `PaymentFailedError` | 402 | A card payment was declined three times |
 | `BlockedError` | 403 | Blocked by bot protection on every path |
-| `NotFoundError` | 404 | What you asked for does not exist - no image on the page (`get_image`), or a plugin lookup found nothing |
+| `NotFoundError` | 404 | What you asked for does not exist - a plugin lookup found nothing |
 | `TargetNotFoundError` | 404 / 410 | The target page itself does not exist; carries `origin_status`, `html`, `destination_url` (subclass of `NotFoundError`, billed) |
 | `BrowserTimeoutError` | 408 | Our browser run timed out before the page was ready |
-| `UnsupportedContentError` | 415 | The URL serves something other than HTML |
+| `UnsupportedContentError` | 415 | The URL serves something other than HTML (`get_page_source`) or other than an image (`get_image`) |
 | `ValidationError` | 422 | Missing or wrong-typed parameter; `body` holds the `detail` array |
 | `RateLimitError` | 429 | Too many requests |
 | `UpstreamOutageError` | 503 | The target origin is down |

data/lib/scrapeunblocker/client.rb

@@ -126,10 +126,16 @@ module ScrapeUnblocker
     # +proxy_country+ to target a market (the Google market follows it; +gl+
     # is an optional override), +pages+ (1-5, ~100 results each; each page
     # fetched is billed as one request, see +pagesFetched+) and +max_results+
-    # (1-500) to cap the count.
-    def google_images(q, proxy_country: nil, pages: nil, gl: nil, max_results: nil)
+    # (1-500) to cap the count. +time_range+ ("hour", "day", "week", "month",
+    # "year") keeps only the images Google found in that recent period, e.g.
+    # the new ones since the last scheduled scan; +date_from+ / +date_to+
+    # ("YYYY-MM-DD", each optional) set a fixed window instead. The two forms
+    # cannot be combined.
+    def google_images(q, proxy_country: nil, pages: nil, gl: nil, max_results: nil,
+                      time_range: nil, date_from: nil, date_to: nil)
       post_json("/images/google-search",
-                q: q, pages: pages, gl: gl, max_results: max_results, proxy_country: proxy_country)
+                q: q, pages: pages, gl: gl, max_results: max_results, proxy_country: proxy_country,
+                time_range: time_range, date_from: date_from, date_to: date_to)
     end
 
     # Fetch an advertiser's Meta (Facebook) Ad Library ads and return them as a Hash.
@@ -215,7 +221,11 @@ module ScrapeUnblocker
                 proxy_country: proxy_country)
     end
 
-    # Fetch an image URL through the bypass chain and return its raw bytes.
+    # Fetch an image and return its bytes exactly as the image host serves them -
+    # the original format (JPEG, PNG, WebP, AVIF, GIF, SVG, ...), nothing
+    # re-encoded. +url+ must point at the image itself: a page URL raises
+    # UnsupportedContentError, and an image the host answers 404 or 410 for
+    # raises TargetNotFoundError.
     def get_image(url, proxy_country: nil)
       request("/getImage", url: url, proxy_country: proxy_country)[:body]
     end

data/lib/scrapeunblocker/errors.rb

@@ -94,16 +94,15 @@ module ScrapeUnblocker
 
   # Something the call asked for does not exist (HTTP 404).
   #
-  # #get_image raises it when the page rendered but held no <img> tag, and
-  # plugin methods raise it when the item they look up does not exist. When the
+  # Plugin methods raise it when the item they look up does not exist. When the
   # target page itself answered 404 or 410, the more specific
   # TargetNotFoundError subclass is raised instead.
   class NotFoundError < APIError; end
 
   # The target page itself does not exist (HTTP 404 or 410).
   #
-  # Raised by #get_page_source, #get_parsed and #get_page_with_cookies when the
-  # site you asked for answered 404 or 410 on its own. The API passes that
+  # Raised by #get_page_source, #get_parsed, #get_page_with_cookies and
+  # #get_image when the site you asked for answered 404 or 410 on its own. The API passes that
   # status through and marks it with the X-Origin-Status header, which is how
   # this is told apart from an API-side 404. It is the target's final answer,
   # not a block, so it is never retried - and the call is billed, because the
@@ -130,8 +129,10 @@ module ScrapeUnblocker
   # the API answered - it just could not render the page in time.
   class BrowserTimeoutError < APIError; end
 
-  # The URL serves something other than HTML (HTTP 415).
-  # The message names the content type found. For images, use #get_image.
+  # The URL serves a content type the call cannot return (HTTP 415): something
+  # other than HTML for #get_page_source (for images, use #get_image), or
+  # something other than an image for #get_image. The message names the content
+  # type found.
   class UnsupportedContentError < APIError; end
 
   # A request parameter is missing or has the wrong type (HTTP 422).
@@ -183,7 +184,7 @@ module ScrapeUnblocker
     403 => "Target blocked by bot protection on every bypass path",
     404 => "Requested element not found on the page",
     408 => "Browser run timed out before the page was ready",
-    415 => "URL does not serve HTML",
+    415 => "URL serves a content type this call cannot return",
     422 => "Validation error - see the detail array in the response body",
     429 => "Rate limited - too many requests",
     503 => "Upstream origin returned a server-side outage page",

data/lib/scrapeunblocker/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scrapeunblocker
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - ScrapeUnblocker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-10-15 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