# Ad Product Rank List API ## API Information - **API Name**: Get Ad Product Rank List - **Request Method**: POST - **API URL**: `/open-api/v1/data` - **Interface URI path**: `/v3/api/open/rank/ad-product/list` - **Description**: Get ad product rank list information based on filter conditions with pagination support - **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/rank/ad-product/list" | Yes | | | params | object | Interface parameter object | See parameter list below | Yes | | ### Request Body Parameters (params object) | Parameter Name | Type | Required | Description | | ---------------- | ------- | -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | current_page | Integer | Yes | Current page number, pagination query current page, starting from 1 | | page_size | Integer | Yes | Page size, number of records per page for pagination query | | sort_key | String | Yes | Sort field: count_growth-play count growth, growth_rate-growth rate, video_count-ad count | | sort_type | String | Yes | Sort type: desc-descending, asc-ascending | | time | Integer | Yes | The midnight time starting from the date. If it is a day, it is reported as midnight of the current day. If it is a week, it is reported as midnight of the current week. If it is a month, it is reported as midnight of the current month | | type | Integer | Yes | Ranking type: 1-Daily Ranking, 2-Weekly Ranking, 3-Monthly Ranking | | count_growth_max | Double | No | Likes, Data growth maximum value (play count growth), used to filter products with growth not exceeding specified value | | count_growth_min | Double | No | Likes, Data growth minimum value (play count growth), used to filter products with growth not below specified value | | growth_rate_max | Double | No | Growth Rate, Data growth rate maximum value, used to filter products with growth rate not exceeding specified value | | growth_rate_min | Double | No | Growth Rate, Data growth rate minimum value, used to filter products with growth rate not below specified value | | plat_type | Integer | No | Platform type: 0-all platforms, 1-TikTok, 2-Facebook | | region | String | No | Country/Region, Target regions, multiple separated by commas | | shop_type | String | No | Ecom Platform, e.g "magento", "shopify", "shoplazza", "shopline", "shopyy", "squarespace", "wix", "woocommerce" | ### 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/rank/ad-product/list", "params": { "current_page": 1, "page_size": 20, "sort_key": "count_growth", "sort_type": "desc", "time": 1, "type": 1, "count_growth_min": 1000, "count_growth_max": 1000000, "growth_rate_min": 0.1, "growth_rate_max": 1.0, "plat_type": 1, "region": "US,CA,GB" } }' ``` ## Response Parameters ### Response Body Structure ```json { "code": 200, "message": "success", "data": { "data": [], "page": {} }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ### Response Field Description | Field Name | Type | Description | | ---------- | ------- | ------------------------------------------- | | code | Integer | Response status code, 200 indicates success | | message | String | Response message | | data | Object | Response data | | data.data | Array | Product rank list | | data.page | Object | Pagination information | | version | String | API version | | timestamp | String | Response timestamp (nullable) | | sign | String | Response signature (nullable) | | 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 | ### Product Rank Information Fields | Field Name | Type | Description | | ------------- | ------- | ----------------------------------------------------- | | id | String | Product unique identifier ID | | image | String | Product main image URL | | title | String | Product title | | currency | String | Product price currency type | | price | Double | Product price | | usd_price | Double | Product USD price | | min_cpm | Double | Minimum CPM (cost per thousand impressions), nullable | | max_cpm | Double | Maximum CPM (cost per thousand impressions), nullable | | count_growth | Long | Data growth amount (play count growth) | | video_count | Long | Video count | | growth_rate | Double | Growth rate | | is_collection | Boolean | Whether already collected | | platform | String | Platform identifier (e.g., "shopify", "shopline") | ### Pagination Information Fields | Field Name | Type | Description | | ------------ | ------- | ----------------------- | | total_count | Long | Total number of records | | page_count | Long | Total number of pages | | current_page | Long | Current page number | | page_size | Long | Records per page | | is_next | Boolean | Whether has next page | ## Response Example ```json { "code": 200, "message": "success", "data": { "data": [ { "id": "67a2d72695f8665640581129", "image": "https://cdn-product.pipispy.com/pimg_7560a46afc0d626f9f70.png", "title": "Hermès Avalon Throw Blanket", "currency": "USD", "price": 149.99, "platform": "shopify", "usd_price": 149.99, "count_growth": 175621, "video_count": 14, "growth_rate": 0.2957, "is_collection": false }, { "id": "674bf2ec6b331c3c04ad0a9a", "image": "https://cdn-product.pipispy.com/pimg_a15c12f7d699c40dc6d5.jpg", "title": "Compression Backpack", "currency": "INR", "price": 9499.0, "platform": "shopify", "usd_price": 110.8, "count_growth": 44047, "video_count": 6, "growth_rate": 3.0072, "is_collection": false }, { "id": "65c024af7ffbbd340830304e", "image": "https://cdn-product.pipispy.com/pimg_603e433b11adfc4d1107.jpg", "title": "Furry Dino Bear | Handmade Jointed Teddy Bear Gift-Getahug", "currency": "USD", "price": 12.98, "platform": "shopline", "usd_price": 12.98, "min_cpm": 864.23, "max_cpm": 3467.1, "count_growth": 33316, "video_count": 5, "growth_rate": 0.011, "is_collection": false } ], "page": { "total_count": 101654, "page_count": 5083, "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 Code Description | Error Code | Description | | ---------- | ----------------------- | | 200 | Success | | 400 | Request parameter error | | 500 | Server internal error | ## Notes 1. Page number parameters start from 1 2. Sort fields support multiple options: count_growth, growth_rate, video_count 3. Time range filtering supports multiple predefined time periods 4. Platform filtering supports TikTok and Facebook platforms 5. Region parameters support multiple regions separated by commas 6. Growth rate is calculated as a percentage value 7. min_cpm and max_cpm fields may be null, indicating no CPM data available for the product 8. platform field shows specific e-commerce platform names such as "shopify", "shopline", etc. 9. The version field in the response indicates the API version, timestamp and sign fields are currently null 10. success and fail fields are used to indicate request processing status