# Product List Interface ## API Information - **API Name**: Get Product List - **Request Method**: POST - **API Address**: `/open-api/v1/data` - **Interface Path**: `/v3/api/open/ad-product/list` - **Interface Description**: Query product list data - **Pricing**: Retrieving one data result consumes 1 credit **Request Headers:** - Content-Type: application/json - Accept: application/json ### Request Parameters #### Request Structure | Parameter Name | Type | Description | Example | Required | Default | | -------------- | ------ | ------------------------------- | ---------------------------------- | -------- | ------- | | key | string | User's external API request key | "your_api_key_here" | Yes | | | uri | string | Interface URI path | "/v3/api/open/ad-product/list" | Yes | | | params | object | Interface parameter object | See parameter list below | Yes | | #### Parameter List (params object) | Parameter Name | Type | Description | Example | Required | Default | | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -------- | ------- | | plat_type | number | Platform type (0:all, 1:tiktok, 2:facebook) | 1 | No | | | keyword | string | Search keyword | "garden" | No | | | search_type | number | Search type (1:product title, 2:product description, 3:advertiser URL, 4:advertiser name, 5:product keyword) | 1 | No | | | category | string | Category, multiple separated by commas | "cat1,cat2" | No | | | region | string | Country/region, multiple separated by commas | "US,HK" | No | | | play_count_min | number | Minimum ad play count | 100 | No | | | play_count_max | number | Maximum ad play count | 10000 | No | | | digg_count_min | number | Minimum like count | 10 | No | | | digg_count_max | number | Maximum like count | 1000 | No | | | digg_play_rate_min | number | Minimum like rate | 0.01 | No | | | digg_play_rate_max | number | Maximum like rate | 0.1 | No | | | comment_count_min | number | Minimum comment count | 5 | No | | | comment_count_max | number | Maximum comment count | 500 | No | | | cpm_max | number | only plat_type=1, Ad Spend | 5 | No | | | cpm_min | number | only plat_type=1, Ad Spend | 500 | No | | | share_count_min | number | Minimum share count | 5 | No | | | share_count_max | number | Maximum share count | 500 | No | | | video_count_min | number | Minimum ad count | 1 | No | | | video_count_max | number | Maximum ad count | 100 | No | | | put_day_min | number | Minimum delivery days | 1 | No | | | put_day_max | number | Maximum delivery days | 30 | No | | | create_time_start | number | Product creation time start (timestamp) | 1709654400 | No | | | create_time_end | number | Product creation time end (timestamp) | 1709827199 | No | | | tiktok_time_start | number | Ad start date, first found time start (timestamp) | 1709654400 | No | | | tiktok_time_end | number | Ad start date, first found time end (timestamp) | 1709827199 | No | | | latest_found_time_start | number | Ad end date, latest found time start (timestamp) | 1710864000 | No | | | latest_found_time_end | number | Ad end date, latest found time end (timestamp) | 1711036799 | No | | | price_min | number | Product price (USD), minimum price | 100 | No | | | price_max | number | Product price (USD), maximum price | 10000 | No | | | currency | string | Currency, multiple separated by commas | "USD,JPY" | No | | | platform | string | Platform identifier, multiple separated by commas, shopify, woocommerce, shoplazza, magento, wix, shopline, squarespace, shopyy | "squarespace,shopyy" | No | | | popular_person_count_min | number | only plat_type=1, Minimum influencer count | 1 | No | | | popular_person_count_max | number | only plat_type=1, Maximum influencer count | 100 | No | | | root_path | string | Advertiser name | "example.com" | No | | | id | string | Product ID, multiple separated by commas | "id1,id2" | No | | | after_id | string | Pagination cursor ID (for deep pagination) | "cursor_id" | No | | | after_key | string | Pagination cursor key (for deep pagination) | "cursor_key" | No | | | sort | string | Sort field: 0-Start Date, 1-End Date, 2-Product Creation Date, 3-Price(USD), 4-Number of ads, 5-Impressions, 6-Likes, 7-Durations | "create_time" | No | | | sort_type | string | Sort type (asc:ascending, desc:descending) | "desc" | No | | | store_id | string | Store unique identifier ID, a 13-character string (e.g.: `c2d5b2547218a`), corresponds to the `store_id` field in the store ranking list interface response | "664c85ef6947b" | No | | | time | number | Time range (1:yesterday, 7:last 7 days, 30:last 30 days, 90:last 90 days) | 7 | No | | | current_page | number | Current page number | 1 | Yes | 1 | | page_size | number | Page size | 10 | Yes | 10 | #### 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/ad-product/list", "params": { "plat_type": 1, "keyword": "garden", "search_type": 1, "region": "US", "current_page": 1, "page_size": 12, "sort": "create_time", "sort_type": "desc", "play_count_min": 500, "play_count_max": 3000000, "digg_count_min": 50, "digg_count_max": 75000, "put_day_min": 2, "put_day_max": 50, "tiktok_time_start": 1709654400, "tiktok_time_end": 1709827199, "latest_found_time_start": 1710864000, "latest_found_time_end": 1711036799, "price_min": 1000, "price_max": 50000, "currency": "USD" } }' ``` ### Response #### Response Body Structure ```json { "code": 200, "message": "success", "data": { "data": [ // Product data list ], "page": { // Pagination information } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` #### Response Field Description ##### Main Response Fields | Field Name | Type | Description | | ------------- | ------------- | ---------------------------------- | | **data** | array[object] | Product data list | | **page** | object | Pagination information | | **version** | string | API version | | **timestamp** | number/null | Response timestamp | | **sign** | string/null | Response signature | | **remaining_credits** | number | Current remaining available credits after this request | | **consumed_credits** | number | Credits consumed by this request | | **success** | boolean | Whether the request was successful | | **fail** | boolean | Whether the request failed | ##### Product Data Fields (data) | Field Name | Type | Description | | -------------------------- | ------- | -------------------------------------------- | | id | string | Product unique identifier ID | | title | string | Product title | | image | string | Product main image URL | | price | number | Product price | | currency | string | Product price currency type | | tiktok_time | number | TikTok platform first discovery timestamp | | found_time | number | TikTok platform first discovery timestamp | | latest_found_time | number | TikTok platform latest discovery timestamp | | play_count | number | TikTok platform play count | | digg_count | number | TikTok platform like count | | digg_play_rate | number | TikTok platform like play ratio | | comment_count | number | TikTok platform comment count | | share_count | number | TikTok platform share count | | video_count | number | TikTok platform video count | | is_collection | boolean | Whether already collected | | platform | string | Product platform identifier | | usd_price | number | Product USD price | | put_days | number | TikTok platform delivery days | | ad_platform_list | array | Ad platform list (e.g., tiktok, facebook) | | facebook_data_count | number | Facebook platform data count | | facebook_digg_count | number | Facebook platform like count | | facebook_found_time | number | Facebook platform first discovery timestamp | | facebook_latest_found_time | number | Facebook platform latest discovery timestamp | | facebook_put_days | number | Facebook platform delivery days | | all_data_count | number | All platform data count | | all_digg_count | number | All platform like count | | all_found_time | number | All platform first discovery timestamp | | all_latest_found_time | number | All platform latest discovery timestamp | | all_put_days | number | All platform delivery days | | all_share_count | number | All platform share count | | facebook_share_count | number | Facebook platform share count | | all_comment_count | number | All platform comment count | | facebook_comment_count | number | Facebook platform comment count | | popular_person_count | number | Influencer count | | create_time | number | Product creation timestamp | | sort_id | string | Sort ID (for pagination sorting) | ##### Page Object Fields (page) | Field Name | Type | Description | | ------------ | ------- | -------------------------- | | total_count | number | Total number of records | | page_count | number | Total number of pages | | current_page | number | Current page number | | page_size | number | Page size | | is_next | boolean | Whether there is next page | #### Response Example ```json { "code": 200, "message": "success", "data": { "data": [ { "id": "686d15677f259f583406b6dd", "title": "Advanced Hair Growth Roll-On Serum", "image": "https://cdn-product.pipispy.com/pimg_9665c6afa75fcb8787ef.png", "price": 30.0, "currency": "USD", "tiktok_time": 1751979367, "found_time": 0, "latest_found_time": 1752200748, "play_count": 0, "digg_count": 5, "digg_play_rate": 0.0, "comment_count": 0, "share_count": 0, "video_count": 1, "is_collection": false, "platform": "shopify", "usd_price": 30.0, "put_days": 3, "ad_platform_list": ["facebook"], "facebook_data_count": 1, "facebook_digg_count": 5, "facebook_found_time": 1751979367, "facebook_latest_found_time": 1752200748, "facebook_put_days": 3, "all_data_count": 1, "all_digg_count": 5, "all_found_time": 1751979367, "all_latest_found_time": 1752200748, "all_put_days": 3, "all_share_count": 1, "facebook_share_count": 1, "all_comment_count": 0, "facebook_comment_count": 0, "popular_person_count": 0, "create_time": 1751551334, "sort_id": "14748630090094" } ], "page": { "total_count": 10000, "page_count": 500, "current_page": 1, "page_size": 20, "is_next": true } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ### Error Codes | Error Code | Description | | ---------- | -------------------------------- | | 400 | Bad Request - Invalid parameters | | 401 | Unauthorized - Invalid API key | | 500 | Internal Server Error |