@scrapecreators/cli 1.0.23 → 1.0.25

package/api-config/apis.js

@@ -164,6 +164,14 @@ export const apis = [
               "Continuation token to get more videos. Get 'continuationToken' from previous response.",
             placeholder: "4qmFsgKrCBIYVUNkRkpXVWE0M3NtUm00SXBIQnB",
           },
+          {
+            name: "is_paid_promotions",
+            type: "string",
+            required: false,
+            description:
+              "Set to 'true' to search YouTube's public paid product placement / sponsorship / endorsement search surface. This returns normal YouTube videos where the creator declared paid promotion. Cannot be combined with filter, uploadDate, sortBy, type, duration, or includeExtras.",
+            placeholder: "false",
+          },
           {
             name: "includeExtras",
             type: "string",
@@ -729,13 +737,70 @@ export const apis = [
           language: "English",
         },
       },
+      {
+        name: "Video Sponsors",
+        method: "GET",
+        description: "Experimental: Find suspected sponsors/promoted brands for a YouTube video. This is inferred from public evidence, not an official YouTube sponsor field. Feedback welcome: support@scrapecreators.com",
+        fullDescription:
+          "Experimental endpoint. Checks a YouTube video for the paid-promotion disclosure and infers likely sponsors/promoted brands from the public description, description links, promo-code text, and transcript. YouTube tells us that a video contains paid promotion, but it does not always tell us the sponsor directly, so this endpoint returns suspected sponsors with confidence and evidence. This is inferred, not an official YouTube sponsor field. Feedback welcome: support@scrapecreators.com",
+        path: "/v1/youtube/video/sponsors",
+        params: [
+          {
+            name: "url",
+            type: "string",
+            required: true,
+            description: "YouTube video or short URL",
+            placeholder: "https://www.youtube.com/watch?v=AVO0ifle-OU",
+          },
+          {
+            name: "language",
+            type: "string",
+            required: false,
+            description: "2 letter language code used for transcript lookup, ie 'en', 'es', 'fr' etc.",
+            placeholder: "en",
+          },
+        ],
+        sampleResponse: {
+          video: {
+            id: "AVO0ifle-OU",
+            url: "https://www.youtube.com/watch?v=AVO0ifle-OU",
+            title: "Why You Should Meal Prep Like A Restaurant",
+            channel: {
+              id: "UC3vQEjRhwgH2HAOBKwLjxNA",
+              url: "https://www.youtube.com/@letsKWOOWK",
+              handle: "letsKWOOWK",
+              title: "KWOOWK",
+            },
+            isPaidPromotion: true,
+          },
+          suspectedSponsors: [
+            {
+              name: "Betterhelp",
+              website: "betterhelp.com",
+              confidence: "medium",
+              evidence: [
+                {
+                  source: "description_link",
+                  text: "If you're struggling, consider therapy with our sponsor BetterHelp. Click https://betterhelp.com/KWOOWK for a 10% discount...",
+                },
+              ],
+            },
+          ],
+          sponsorDetection: {
+            status: "found",
+            methods: ["paid promotion badge", "description", "description links", "transcript"],
+            transcriptAvailable: true,
+            note: "Sponsors are inferred from public description, links, promo-code text, and transcript evidence.",
+          },
+        },
+      },
       {
         name: "Search",
         method: "GET",
         description:
           "Search YouTube and get matching videos, channels, playlists, shorts, lives, etc. Video explaining the response format: https://www.tella.tv/video/explaining-youtube-search-results-payload-353a",
         fullDescription:
-          "Searches YouTube by keyword query and returns matching videos, channels, playlists, shorts, shelves, and live streams. Each video result includes title, URL, thumbnail, view count (views), publish date, duration, channel info, and badges. Supports filtering by upload date, sorting by relevance or popularity, and paginating with continuationToken.",
+          "Searches YouTube by keyword query and returns matching videos, channels, playlists, shorts, shelves, and live streams. Each video result includes title, URL, thumbnail, view count (views), publish date, duration, channel info, and badges. Supports filtering by upload date, sorting by relevance or popularity, and paginating with continuationToken. Set is_paid_promotions=true to search YouTube videos with the paid product placement / sponsorship disclosure.",
         path: "/v1/youtube/search",
         paginationField: "continuationToken",
         sampleResponse: {

package/api-config/tiktok-apis.js

@@ -115,6 +115,231 @@ export const tiktokBaseApis = {
         region: "US",
       },
     },
+    {
+      name: "Ad Library Search",
+      method: "GET",
+      description: "Search TikTok Creative Center Top Ads by region, period, and keyword.",
+      fullDescription:
+        "Searches TikTok Creative Center Top Ads, the ad library page at ads.tiktok.com/business/creativecenter/inspiration/topads. Supports US and other 2-letter regions, period filters, sorting, keyword search, and cursor pagination. Returns TikTok's public top ad material objects, including ad title, metrics, video info, landing page, and pagination.",
+      path: "/v1/tiktok/ad-library/search",
+      params: [
+        {
+          name: "region",
+          type: "select",
+          required: false,
+          description: "Country code. Defaults to US.",
+          options: ["DZ", "AR", "AU", "AT", "AZ", "BH", "BD", "BY", "BE", "BO", "BR", "BG", "KH", "CA", "CL", "CO", "CR", "HR", "CY", "CZ", "DK", "DO", "EC", "EG", "EE", "FI", "FR", "DE", "GR", "GT", "JO", "HU", "ID", "IQ", "IE", "IL", "IT", "JP", "KZ", "KE", "KW", "LV", "LB", "MY", "MX", "MA", "NL", "NZ", "NG", "NO", "OM", "PK", "PA", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "LT", "RO", "SA", "RS", "SG", "SK", "SI", "ZA", "KR", "ES", "LK", "SE", "CH", "TW", "TH", "TR", "AE", "GB", "US", "UY", "VN"],
+          placeholder: "US",
+        },
+        {
+          name: "period",
+          type: "select",
+          required: false,
+          description: "Time window for Top Ads.",
+          options: ["7", "30", "180"],
+          placeholder: "30",
+        },
+        {
+          name: "query",
+          type: "string",
+          required: false,
+          description: "Optional keyword to search ad titles/content.",
+          placeholder: "spotify",
+        },
+        {
+          name: "order_by",
+          type: "select",
+          required: false,
+          description: "Sort metric. Defaults to for_you.",
+          options: ["for_you", "impression", "play_2s_rate", "play_6s_rate", "cvr", "ctr", "like"],
+          placeholder: "for_you",
+        },
+        {
+          name: "industry",
+          type: "select",
+          required: false,
+          description: "Industry filter.",
+          options: ["apparel_accessories", "appliances", "apps", "baby_kids_maternity", "beauty_personal_care", "business_services", "ecommerce_non_app", "education", "financial_services", "food_beverage", "games", "health", "home_improvement", "household_products", "life_services", "news_entertainment", "pets", "sports_outdoor", "tech_electronics", "travel", "vehicle_transportation"],
+          placeholder: "beauty_personal_care",
+        },
+        {
+          name: "objective",
+          type: "select",
+          required: false,
+          description: "Campaign objective filter.",
+          options: ["app_installs", "conversions", "lead_generation", "product_sales", "reach", "traffic", "video_views"],
+          placeholder: "traffic",
+        },
+        {
+          name: "duration",
+          type: "select",
+          required: false,
+          description: "Video duration filter.",
+          options: ["under_10s", "10_20s", "20_30s", "30_40s", "40_50s", "over_50s"],
+          placeholder: "under_10s",
+        },
+        {
+          name: "likes",
+          type: "select",
+          required: false,
+          description: "Likes percentile filter.",
+          options: ["top_1_20", "top_21_40", "top_41_60", "top_61_80", "top_81_100"],
+          placeholder: "top_1_20",
+        },
+        {
+          name: "ad_format",
+          type: "select",
+          required: false,
+          description: "Ad format filter.",
+          options: ["spark_ads", "non_spark_ads"],
+          placeholder: "spark_ads",
+        },
+        {
+          name: "ad_language",
+          type: "select",
+          required: false,
+          description: "Ad language filter.",
+          options: ["en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko"],
+          placeholder: "en",
+        },
+        {
+          name: "cursor",
+          type: "number",
+          required: false,
+          description: "Page number to fetch. Use the cursor returned from the previous response, like 3 for page 3.",
+          placeholder: "3",
+        },
+        {
+          name: "limit",
+          type: "number",
+          required: false,
+          description: "Number of ads to return, max 50. Defaults to 20.",
+          placeholder: "20",
+        },
+      ],
+      sampleResponse: {
+        success: true,
+        credits_remaining: 100,
+        data: {
+          query: "spotify",
+          region: "US",
+          period: 30,
+          ads: [
+            {
+              id: "7642386438915309575",
+              ad_title: "Example TikTok top ad title",
+              brand_name: "Example Brand",
+              ctr: 0.24,
+              like: 80546,
+              video_info: {
+                duration: 20.054,
+                cover: "https://p16-common-sign.tiktokcdn.com/...",
+                video_url: {
+                  "720p": "https://v16m-default.tiktokcdn.com/...",
+                },
+              },
+            },
+          ],
+          pagination: {
+            page: 1,
+            limit: 20,
+            total_count: 326,
+          },
+          total: 326,
+          has_more: true,
+          cursor: "eyJwYWdlIjoyfQ",
+        },
+      },
+    },
+    {
+      name: "Ad Library Ad",
+      method: "GET",
+      description: "Gets details for a TikTok Creative Center Top Ad.",
+      fullDescription:
+        "Fetches one TikTok Creative Center Top Ad by material/ad ID or URL. Uses the same Creative Center data behind pages like ads.tiktok.com/business/creativecenter/topads/{id}/pc/en, including title, metrics, video info, landing page, country codes, objective, industry, source, the Creative Center URL, summary/analysis, interactive time analysis graph data, and recommended-for-you ads when TikTok provides them.",
+      path: "/v1/tiktok/ad-library/ad",
+      params: [
+        {
+          name: "ad_id",
+          type: "string",
+          required: true,
+          description: "TikTok Top Ads material/ad ID, or a Top Ads detail URL.",
+          placeholder: "7642386438915309575",
+        },
+      ],
+      sampleResponse: {
+        success: true,
+        credits_remaining: 100,
+        data: {
+          id: "7642386438915309575",
+          ad_title: "Example TikTok top ad title",
+          brand_name: "Example Brand",
+          ctr: 0.24,
+          like: 80546,
+          country_code: ["US"],
+          landing_page: "https://example.com",
+          creative_center_url:
+            "https://ads.tiktok.com/business/creativecenter/topads/7642386438915309575/pc/en",
+          video_info: {
+            duration: 20.054,
+            cover: "https://p16-common-sign.tiktokcdn.com/...",
+            video_url: {
+              "720p": "https://v16m-default.tiktokcdn.com/...",
+            },
+          },
+          detail_analysis: {
+            hints: [],
+            paragraphs: [],
+          },
+          interactive_time_analysis: {
+            ctr: {
+              metric: "retain_ctr",
+              analysis: [{ second: 0, value: 0.0174 }],
+              duration: 14,
+              highlight: [1, 9],
+              percentile: 0.99,
+            },
+            cvr: {
+              metric: "retain_cvr",
+              analysis: [],
+              duration: 14,
+              highlight: [],
+              percentile: 0.99,
+            },
+            clicks: {
+              metric: "click_cnt",
+              analysis: [],
+              duration: 14,
+              highlight: [],
+              percentile: 0.99,
+            },
+            conversion: {
+              metric: "convert_cnt",
+              analysis: [],
+              duration: 14,
+              highlight: [],
+              percentile: 0.99,
+            },
+            remain: {
+              metric: "play_retain_cnt",
+              analysis: [],
+              duration: 14,
+              highlight: [],
+              percentile: 0.99,
+            },
+          },
+          recommended_for_you: [
+            {
+              id: "7639864582744702996",
+              ad_title: "Example recommended ad",
+              video_info: {
+                cover: "https://p16-common-sign.tiktokcdn.com/...",
+              },
+            },
+          ],
+        },
+      },
+    },
     {
       name: "User's Audience Demographics",
       method: "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrapecreators/cli",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "CLI for the ScrapeCreators API — scrape 27+ social media platforms from the terminal",
   "type": "module",
   "bin": {