Ad Product New Rank List API
- 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
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
{
"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 |
| 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" |
| 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
{
"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
- Page number parameters start from 1
- Sort fields support multiple options: count_growth, growth_rate, video_count
- Time range filtering supports multiple predefined time periods
- Platform filtering supports TikTok and Facebook platforms
- Region parameters support multiple regions separated by commas
- Growth rate is calculated as percentage values
- Some fields may be empty (such as currency, usd_price, min_cpm, max_cpm)
- Platform identifier currently mainly returns "shopify"
- Image URLs use CDN domain cdn-product.pipispy.com
- Product IDs are in 24-bit MongoDB ObjectId format