# Store Ad Copy Analysis API Endpoint This document contains two API endpoints: TikTok Platform Ad Copy Analysis API Endpoint and Facebook Platform Ad Copy Analysis API Endpoint. --- ## Part 1: TikTok Platform Ad Copy Analysis API Endpoint ### API Information - **API Name**: TikTok Platform Ad Copy Analysis API Endpoint - **Request Method**: POST - **API Address**: `/open-api/v1/data` - **API Path**: `/v3/api/open/store/tiktok/ad-copy-analysis` - **API Description**: - Query ad copy statistics and analysis data for a specified store on the TikTok platform - Aggregates by ad name and copy content, counts usage frequency and play count for each copy combination - Supports sorting by play count and ad count - Helps analyze effective copy combinations used by the store on the TikTok platform - Pricing: `Free` **Request Headers:** - Content-Type: application/json - Accept: application/json ### Request Parameters #### Request Structure | Parameter Name | Type | Description | Example | Required | Default Value | | -------------- | ------ | ---------------------------------- | -------------------------------------------- | -------- | ------------- | | key | string | User's external API request key | "your_api_key_here" | Yes | | | uri | string | API path | "/v3/api/open/store/tiktok/ad-copy-analysis" | Yes | | | params | object | API input parameter object | See parameter list | Yes | | #### Request Body Parameters (params object) | Parameter Name | Type | Required | Description | | -------------- | ------- | -------- | ------------------------------------------------------------------- | | id | string | true | Store ID is a 13-character string (e.g., `c2d5b2547218a`), corresponding to the `store_id` field in the store ranking list API response | | current_page | integer | false | Current page number, default is 1 | | page_size | integer | false | Number per page, default is 10 | | sort_key | string | false | Sort field: play_count - play count, ad_count - ad count, default is play_count | | sort_type | string | false | Sort direction: desc - descending, asc - ascending, default is desc | #### Request Example ```bash curl -X POST "https://www.pipispy.com/open-api/v1/data" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "key": "your_api_key_here", "uri": "/v3/api/open/store/tiktok/ad-copy-analysis", "params": { "id": "c2d5b2547218a", "current_page": 1, "page_size": 10, "sort_key": "play_count", "sort_type": "desc" } }' ``` ### Response Parameters #### Response Body Structure ```json { "code": 200, "message": "success", "data": { "tikTok_copy_analysis": [ { "ad_name": "Summer Fashion Collection", "copywriter": "Get 50% OFF on all summer items! Limited time offer 🔥", "ad_count": 25, "play_count": 5280000 }, { "ad_name": "Fitness Tracker Pro", "copywriter": "Track your health goals with our smart fitness tracker ⭐", "ad_count": 18, "play_count": 3850000 } ], "current_page": 1, "page_size": 10, "total": 156, "page_count": 16 }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 0, "fail": false, "success": true } ``` #### Response Field Descriptions | Field Name | Type | Description | | ------------- | ------- | --------------------------------------- | | code | Integer | Response status code, 200 means success | | message | String | Response message | | data | Object | Response data | | version | String | API version | | timestamp | String | Response timestamp | | sign | String | Response signature | | remaining_credits | Long | Current remaining available credits after this request | | consumed_credits | Long | Credits consumed by this request | | success | Boolean | Whether the request was successful | | fail | Boolean | Whether the request failed | #### Response Result Information Fields | Field Name | Type | Description | | -------------------- | ------------- | ------------------------------- | | tikTok_copy_analysis | Array[Object] | TikTok copy analysis data list | | current_page | Integer | Current page number | | page_size | Integer | Number per page | | total | Long | Total number of records | | page_count | Integer | Total number of pages | #### tikTok_copy_analysis Array Element Structure | Field Name | Type | Description | | ----------- | ------ | ------------------------------------------------------- | | ad_name | String | Ad name | | copywriter | String | Ad copy content | | ad_count | Long | Number of ads using this ad name and copy combination | | play_count | Long | Total play count for this ad name and copy combination | #### Response Example ```json { "code": 200, "message": "success", "data": { "tikTok_copy_analysis": [ { "ad_name": "Summer Fashion Collection", "copywriter": "🔥 Get 50% OFF on all summer items! Limited time offer. Shop now and save big on trendy outfits!", "ad_count": 25, "play_count": 5280000 }, { "ad_name": "Fitness Tracker Pro", "copywriter": "⭐ Track your health goals with our smart fitness tracker. Monitor steps, calories, heart rate & more!", "ad_count": 18, "play_count": 3850000 }, { "ad_name": "Smart Home Camera", "copywriter": "🏠 Protect your home 24/7 with HD camera. Motion detection, night vision, easy setup!", "ad_count": 15, "play_count": 2920000 }, { "ad_name": "Wireless Earbuds", "copywriter": "🎵 Premium sound quality meets comfort. Noise cancellation, 30hr battery life. Order today!", "ad_count": 12, "play_count": 2450000 } ], "current_page": 1, "page_size": 10, "total": 156, "page_count": 16 }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 0, "fail": false, "success": true } ``` ### Error Code Descriptions | Error Code | Description | | ---------- | --------------------- | | 200 | Success | | 400 | Request parameter error | | 500 | Internal server error | ### Usage Instructions 1. **Data Aggregation Dimension**: - Aggregates statistics by "ad name + copy content" combination - Ads with the same ad name and copy content are merged for statistics 2. **Sort Fields**: - `play_count`: Sort by total play count, suitable for finding high-exposure copy combinations - `ad_count`: Sort by ad count, suitable for finding highly reused copy combinations 3. **Application Scenarios**: - Analyze which ad name and copy combinations get more plays - Identify the store's commonly used copy strategies on the TikTok platform - Optimize ad copy to improve campaign effectiveness --- ## Part 2: Facebook Platform Ad Copy Analysis API Endpoint ### API Information - **API Name**: Facebook Platform Ad Copy Analysis API Endpoint - **Request Method**: POST - **API Address**: `open-api/v1/data` - **API Path**: `/v3/api/open/store/facebook/ad-copy-analysis` - **API Description**: - Query ad copy statistics and analysis data for a specified store on the Facebook platform - Aggregates by ad name and copy content, counts usage frequency and like count for each copy combination - Supports sorting by like count and ad count - Helps analyze high-engagement copy combinations used by the store on the Facebook platform - Pricing: `Free` **Request Headers:** - Content-Type: application/json - Accept: application/json ### Request Parameters #### Request Structure | Parameter Name | Type | Description | Example | Required | Default Value | | -------------- | ------ | ---------------------------------- | ---------------------------------------------- | -------- | ------------- | | key | string | User's external API request key | "your_api_key_here" | Yes | | | uri | string | API path | "/v3/api/open/store/facebook/ad-copy-analysis" | Yes | | | params | object | API input parameter object | See parameter list | Yes | | #### Request Body Parameters (params object) | Parameter Name | Type | Required | Description | | -------------- | ------- | -------- | ------------------------------------------------------------------- | | id | string | true | Store ID is a 13-character string (e.g., `c2d5b2547218a`), corresponding to the `store_id` field in the store ranking list API response | | current_page | integer | false | Current page number, default is 1 | | page_size | integer | false | Number per page, default is 10 | | sort_key | string | false | Sort field: digg_count - like count, ad_count - ad count, default is ad_count | | sort_type | string | false | Sort direction: desc - descending, asc - ascending, default is desc | #### Request Example ```bash curl -X POST "https://www.pipispy.com/open-api/v1/data" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "key": "your_api_key_here", "uri": "/v3/api/open/store/facebook/ad-copy-analysis", "params": { "id": "12345", "current_page": 1, "page_size": 10, "sort_key": "digg_count", "sort_type": "desc" } }' ``` ### Response Parameters #### Response Body Structure ```json { "code": 200, "message": "success", "data": { "facebook_copy_analysis": [ { "ad_name": "Summer Fashion Collection", "copywriter": "Get 50% OFF on all summer items! Limited time offer 🔥", "ad_count": 20, "digg_count": 125000 }, { "ad_name": "Fitness Tracker Pro", "copywriter": "Track your health goals with our smart fitness tracker ⭐", "ad_count": 16, "digg_count": 98000 } ], "current_page": 1, "page_size": 10, "total": 89, "page_count": 9 }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 0, "fail": false, "success": true } ``` #### Response Field Descriptions | Field Name | Type | Description | | ------------- | ------- | --------------------------------------- | | code | Integer | Response status code, 200 means success | | message | String | Response message | | data | Object | Response data | | version | String | API version | | timestamp | String | Response timestamp | | sign | String | Response signature | | success | Boolean | Whether the request was successful | | fail | Boolean | Whether the request failed | #### Response Result Information Fields | Field Name | Type | Description | | ---------------------- | ------------- | --------------------------------- | | facebook_copy_analysis | Array[Object] | Facebook copy analysis data list | | current_page | Integer | Current page number | | page_size | Integer | Number per page | | total | Long | Total number of records | | page_count | Integer | Total number of pages | #### facebook_copy_analysis Array Element Structure | Field Name | Type | Description | | ----------- | ------ | ------------------------------------------------------- | | ad_name | String | Ad name | | copywriter | String | Ad copy content | | ad_count | Long | Number of ads using this ad name and copy combination | | digg_count | Long | Total like count for this ad name and copy combination | #### Response Example ```json { "code": 200, "message": "success", "data": { "facebook_copy_analysis": [ { "ad_name": "Summer Fashion Collection", "copywriter": "🎁 Special Promotion! Get 50% OFF on all summer fashion items. Limited time only. Shop before it's gone!", "ad_count": 20, "digg_count": 125000 }, { "ad_name": "Fitness Tracker Pro", "copywriter": "🌟 Track your health goals with our smart fitness tracker. Monitor steps, calories, heart rate and sleep quality!", "ad_count": 16, "digg_count": 98000 }, { "ad_name": "Smart Home Camera", "copywriter": "💯 Protect your home 24/7 with HD security camera. Motion detection, night vision, two-way audio. Easy setup!", "ad_count": 14, "digg_count": 87500 }, { "ad_name": "Wireless Earbuds", "copywriter": "🚀 Premium sound quality with active noise cancellation. 30-hour battery life. Free shipping worldwide!", "ad_count": 11, "digg_count": 76000 } ], "current_page": 1, "page_size": 10, "total": 89, "page_count": 9 }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 0, "fail": false, "success": true } ``` ### Error Code Descriptions | Error Code | Description | | ---------- | --------------------- | | 200 | Success | | 400 | Request parameter error | | 500 | Internal server error | ### Usage Instructions 1. **Data Aggregation Dimension**: - Aggregates statistics by "ad name + copy content" combination - Ads with the same ad name and copy content are merged for statistics 2. **Sort Fields**: - `digg_count`: Sort by total like count, suitable for finding high-engagement copy combinations - `ad_count`: Sort by ad count, suitable for finding highly reused copy combinations 3. **Application Scenarios**: - Analyze which ad name and copy combinations get more user engagement - Identify the store's commonly used copy strategies on the Facebook platform - Optimize ad copy to improve user participation