scrapeunblocker 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d921e3453928431b4e1715efd3f8ae53fa1175f5b4fdbf4a67db12c0409cab18
-  data.tar.gz: 59bcc76323226693b74aa96d8a3f969118f6df95328a6e3424bed1ec8dfa78e0
+  metadata.gz: 4542500ec21bf7ce42e644394bf9302b74399a5447f6f5717e3f6abeaf8e7cb4
+  data.tar.gz: 92470e75374896eb308d3f7f939f39dcecb210aeaff4fa151aa8b0df8c516a95
 SHA512:
-  metadata.gz: 4d0791186d046ebe36897a987c7fd08fdfa98c1c78754fc7a32bc9552ac782a903ec1e10bde22fa7d1b442972586ab8a85d6777a00dc5d310e1c9cfe40f9e372
-  data.tar.gz: b132825a15081702a1e76ab431ae9835f88ffa7a589241775688f1820ee58c14d438e0a9150afa995e70fee3ee97df63de6f0dd6b9ba78c17adbacd0ba00510b
+  metadata.gz: 672b0d182dc35e5650102171465dadf60f6bd22890a3d000b6e0a82a5e9b137b8857d1fac1231013af24eefd4b782e883db83423fca436b47aec1183af4c6b45
+  data.tar.gz: 75f9249d01b7d1b6aa6e2ef0c373ec386cee41d5cd7e42fefceff65aa74d4992aaa036067e67f24be0e11e2ee89f705942975a863c8f0dba707cc5bf4f01b1a3

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0 (2026-09-08)
+
+- Added `tiktok_profile`, `tiktok_video`, `tiktok_hashtag`, `tiktok_search` and `tiktok_comments` for the new TikTok plugin: a creator's exact follower / like / video counts with their newest videos (up to 200), any video or photo post with exact plays, likes, comments, shares, saves and reposts, hashtags, music, play / download URLs, subtitle tracks and an optional transcript, a hashtag's total views and videos with its videos, keyword search in TikTok's own ranking, and the comments of any post. No login.
+
+## 0.2.1 (2026-09-02)
+
+- Added `meta_ad_library(advertiser, ...)` for the new Meta Ad Library plugin (`POST /ads/meta-ad-library`) - returns an advertiser's Meta (Facebook) Ad Library ads as a Hash. `advertiser` is required; optional filters `country`, `active_status`, `media_type` and `max_ads` are dropped when unset so the API applies its own defaults.
+
+No breaking changes.
+
 ## 0.2.0 (2026-08-29)
 
 - `get_page_source` now accepts `steps:` - an ordered Array of browser-action Hashes the API runs in the real browser after the page loads (`wait_for`, `wait_for_text`, `wait`, `click`, `type`, `select`, `press_key`, `scroll`). The array is JSON-encoded into the `steps` query parameter. Steps run once and are not idempotent; a failed step returns HTTP 422 and raises `ScrapeUnblocker::ValidationError`, whose `body` names the failed step (`step_index`, `action`, `reason`, `selector`, `html`).

data/README.md

@@ -128,6 +128,15 @@ local = su.google_local("coffee shops in chicago", proxy_country: "US", gl: "us"
 local["results"].each { |biz| puts "#{biz['name']} #{biz['rating']} #{biz['address']}" }
 ```
 
+## Meta Ad Library
+
+```ruby
+ads = su.meta_ad_library("Nike", country: "US")
+ads["results"].each { |ad| puts "#{ad['id']} #{ad['media_type']}" }
+```
+
+`advertiser` is required. Optional filters: `country`, `active_status`, `media_type` and `max_ads`. Unset filters are dropped and the API applies its own defaults.
+
 ## Oopbuy goods search
 
 ```ruby
@@ -169,6 +178,19 @@ end
 
 `marketplace` is any of the 19 regional eBay hosts (`ebay.com` default). `condition` is one of `"new"`, `"open_box"`, `"refurbished"`, `"used"` or `"for_parts"`; `sort` is one of `"best_match"` (default), `"newly_listed"`, `"ending_soon"`, `"price_asc"` or `"price_desc"`; `page_size` is 60, 120 or 240. `exactMatches` is `false` when eBay found nothing for the keyword and answered with its own loosely-related suggestions instead, so check it before using the listings.
 
+### TikTok
+
+```ruby
+profile = su.tiktok_profile("nasa", max_videos: 5)      # exact stats + newest videos
+video = su.tiktok_video("https://www.tiktok.com/@nasa/video/7665075736742530317", include_transcript: true)
+tag = su.tiktok_hashtag("nasa", max_videos: 10)
+results = su.tiktok_search("space telescope", max_results: 25)   # TikTok's own ranking
+comments = su.tiktok_comments("https://www.tiktok.com/@nasa/video/7665075736742530317", max_comments: 40)
+puts profile["stats"]["followers"], video["stats"]["plays"], tag["stats"]["views"], comments["totalComments"]
+```
+
+Profiles and hashtags list up to 10 videos in a couple of seconds from TikTok's server-rendered widget; ask for more (up to 200) and the real grid is scrolled in a browser session.
+
 ## Cookies and the serving proxy
 
 ```ruby
@@ -259,7 +281,7 @@ end
 
 When more than one applies, the most serious wins: failed payment outranks credit limit, which outranks quota. All three lift by themselves once the billing state changes - access returns within about a minute, and the API key stays the same. One catch worth knowing: subscribing to a new plan does **not** clear `PaymentFailedError`, because the old unpaid invoice stays open until it is paid.
 
-Full details for every status code: [developers.scrapeunblocker.com/errors](https://developers.scrapeunblocker.com/errors).
+Full details for every status code: [docs.scrapeunblocker.com/errors](https://docs.scrapeunblocker.com/errors).
 
 ## Configuration
 
@@ -274,7 +296,7 @@ ScrapeUnblocker::Client.new(
 
 ## Links
 
-- Documentation: [developers.scrapeunblocker.com](https://developers.scrapeunblocker.com?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk)
+- Documentation: [docs.scrapeunblocker.com](https://docs.scrapeunblocker.com?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk)
 - Website: [scrapeunblocker.com](https://scrapeunblocker.com?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk)
 - Dashboard: [app.scrapeunblocker.com](https://app.scrapeunblocker.com?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk)
 

data/lib/scrapeunblocker/client.rb

@@ -101,6 +101,19 @@ module ScrapeUnblocker
                 keyword: keyword, proxy_country: proxy_country, hl: hl, gl: gl)
     end
 
+    # Fetch an advertiser's Meta (Facebook) Ad Library ads and return them as a Hash.
+    #
+    # +advertiser+ is the advertiser name or page to look up. Optional filters:
+    # +country+ (the Ad Library region), +active_status+ (active or inactive
+    # ads), +media_type+ (image, video, etc.) and +max_ads+ (a cap on how many
+    # ads to return). Unset filters are dropped from the request and the API
+    # applies its own defaults.
+    def meta_ad_library(advertiser, country: nil, active_status: nil, media_type: nil, max_ads: nil)
+      post_json("/ads/meta-ad-library",
+                advertiser: advertiser, country: country, active_status: active_status,
+                media_type: media_type, max_ads: max_ads)
+    end
+
     # Search Oopbuy (1688, Taobao or official channel) and return the goods as a Hash.
     #
     # Returns matched products, each with spu, channel, title, titleCn, price,
@@ -177,6 +190,53 @@ module ScrapeUnblocker
     end
 
     # @api private
+    # Scrape a public TikTok creator profile and its newest videos.
+    #
+    # Returns the exact follower, following, like and video counts, bio, bio
+    # link, verified / private / organization / seller flags, avatar and a
+    # +videos+ array of the creator's newest posts (up to 200), each in the
+    # full #tiktok_video shape. No login.
+    def tiktok_profile(username, max_videos: 10, video_details: true, proxy_country: nil)
+      post_json("/social/tiktok-profile",
+                username: username, max_videos: max_videos,
+                video_details: video_details ? nil : false,
+                proxy_country: proxy_country)
+    end
+
+    # Scrape one TikTok video or photo post: exact plays, likes, comments,
+    # shares, saves and reposts, hashtags, mentions, author, music, play /
+    # download URLs, subtitle tracks and, with +include_transcript+, the
+    # transcript as text.
+    def tiktok_video(url, include_transcript: false, transcript_language: nil, proxy_country: nil)
+      post_json("/social/tiktok-video",
+                url: url, include_transcript: include_transcript ? true : nil,
+                transcript_language: transcript_language, proxy_country: proxy_country)
+    end
+
+    # Scrape a TikTok hashtag: total views and videos plus its videos (up to 200).
+    def tiktok_hashtag(hashtag, max_videos: 10, video_details: true, proxy_country: nil)
+      post_json("/social/tiktok-hashtag",
+                hashtag: hashtag, max_videos: max_videos,
+                video_details: video_details ? nil : false,
+                proxy_country: proxy_country)
+    end
+
+    # Search TikTok videos by keyword. Runs in a browser session that clears
+    # TikTok's captcha, so +results+ carry TikTok's own ranking (region via
+    # +proxy_country+), each in the full #tiktok_video shape. 20-45 s.
+    def tiktok_search(query, max_results: 20, proxy_country: nil)
+      post_json("/social/tiktok-search",
+                query: query, max_results: max_results, proxy_country: proxy_country)
+    end
+
+    # Scrape the comments of a TikTok post (text, date, likes, reply count,
+    # author, creator flags, preloaded replies) plus +totalComments+ and
+    # +hasMore+. Runs in a browser session that clears TikTok's captcha. 20-45 s.
+    def tiktok_comments(url, max_comments: 50, proxy_country: nil)
+      post_json("/social/tiktok-comments",
+                url: url, max_comments: max_comments, proxy_country: proxy_country)
+    end
+
     def post_json(path, params)
       JSON.parse(request(path, params)[:body])
     end

data/lib/scrapeunblocker/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scrapeunblocker
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ScrapeUnblocker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-29 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies: []
 description: JS-rendered pages that bypass Cloudflare, DataDome, PerimeterX and Akamai,
   plus Google SERP and Skyscanner flights/hotels/car-hire scraping as JSON.
@@ -33,7 +33,7 @@ licenses:
 metadata:
   homepage_uri: https://scrapeunblocker.com?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk
   source_code_uri: https://github.com/ScrapeUnblocker/scrapeunblocker-ruby
-  documentation_uri: https://developers.scrapeunblocker.com?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk
+  documentation_uri: https://docs.scrapeunblocker.com?utm_source=rubygems&utm_medium=integration&utm_campaign=ruby-sdk
   changelog_uri: https://github.com/ScrapeUnblocker/scrapeunblocker-ruby/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/ScrapeUnblocker/scrapeunblocker-ruby/issues
   rubygems_mfa_required: 'true'