@scrapecreators/cli 1.0.24 → 1.0.25

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.24",
+  "version": "1.0.25",
   "description": "CLI for the ScrapeCreators API — scrape 27+ social media platforms from the terminal",
   "type": "module",
   "bin": {