# Ad Product New Rank List API ## API Information - **API Name**: Get Ad Product New Rank List - **Request Method**: POST - **API URL**: `/open-api/v1/data` - **Interface URI path**: `/v3/api/open/rank/ad-product-new/list` - **Description**: Get ad product new 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-new/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 | | found_time | Double | Yes | Discovery time range: 0-default, 1-Last 3 days , 2-Last 7 days, 3-Last 1 month, 4-Last 3 months, 5-Last 6 months, 6-all | | page_size | Integer | Yes | Page size, number of records per page for pagination query | | sort_key | String | Yes | Sort field: count_growth-Likes, growth_rate-Growth Rate, video_count-Ads | | sort_type | String | Yes | Sort type: desc-descending, asc-ascending | | type | Integer | Yes | Time type: 0-default, 1-Last 24 hours, 2-Last 3 days, 3-Last 7 days | | 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-new/list", "params": { "current_page": 1, "found_time": 1, "page_size": 20, "sort_key": "count_growth", "sort_type": "desc", "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 number | | timestamp | String/Null | Timestamp | | sign | String/Null | Signature information | | 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 | Example | | ------------- | ------- | --------------------------------------------------------- | --------------------------------------------------------------- | | id | String | Product unique identifier ID | "6868c8124423dd56cf7ea285" | | image | String | Product main image URL | "https://cdn-product.pipispy.com/pimg_5207a34434df898bdaca.png" | | title | String | Product title | "Baby Hands & Feet Casting Kit" | | currency | String | Product price currency type, may be empty | "USD", "BRL", "AUD", "EUR", "GBP", "JPY", "" | | price | Double | Product price | 120.0, 137.9, 119.0 | | usd_price | Double | Product USD price, may be empty | 120.0, 25.26, 77.78 | | min_cpm | Double | Minimum CPM (cost per thousand impressions), may be empty | 4712.15, 14031.55, 8670.1 | | max_cpm | Double | Maximum CPM (cost per thousand impressions), may be empty | 18890.6, 56126.19, 34680.38 | | count_growth | Long | Data growth amount (play count growth) | 183674, 114088, 110683 | | video_count | Long | Video count | 34, 8, 15 | | growth_rate | Double | Growth rate (percentage value) | 16.9425, 1.8143, 611.5083 | | is_collection | Boolean | Whether already collected | false | | platform | String | Platform identifier | "shopify" | ### 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": "6868c8124423dd56cf7ea285", "image": "https://cdn-product.pipispy.com/pimg_5207a34434df898bdaca.png", "title": "Baby Hands & Feet Casting Kit", "currency": "USD", "price": 120.0, "platform": "shopify", "usd_price": 120.0, "min_cpm": 4712.15, "max_cpm": 18890.6, "count_growth": 183674, "video_count": 34, "growth_rate": 16.9425, "is_collection": false }, { "id": "68656c2a9a22ed62395b6d9f", "image": "https://cdn-product.pipispy.com/pimg_8a1a4534450f949cd18c.png", "title": "Kit Caterpillar - Bota Masculina em Couro Legítimo e Palmilha Ortopédica + Brindes Exclusivos", "currency": "BRL", "price": 137.9, "platform": "shopify", "usd_price": 25.26, "min_cpm": 14031.55, "max_cpm": 56126.19, "count_growth": 114088, "video_count": 8, "growth_rate": 1.8143, "is_collection": false } ], "page": { "total_count": 37834, "page_count": 1892, "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 percentage values 7. Some fields may be empty (such as currency, usd_price, min_cpm, max_cpm) 8. Platform identifier currently mainly returns "shopify" 9. Image URLs use CDN domain cdn-product.pipispy.com 10. Product IDs are in 24-bit MongoDB ObjectId format