Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

Store Product Analysis API Endpoint

API Information

  • API Name: Store Product Analysis API Endpoint
  • Request Method: GET
  • API Address: /open-api/v1/data
  • API Path: /v3/api/open/store/product-analysis
  • API Description:
    • Query product statistics and analysis data for a specified store
    • Statistics on the number of products promoted on different platforms, category distribution, and price range distribution
    • Support filtering product data by time range
    • Help analyze store product strategy and pricing strategy
    • Pricing: Free

Request Headers:

  • Content-Type: application/json
  • Accept: application/json

Request Parameters

Request Structure

Parameter Type Description Example Required Default
key string External API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/store/product-analysis" Yes
params object API input parameters object See parameter list Yes

Request Body Parameters (params object)

Parameter 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 rank list API response
start_time long false Start time, timestamp (seconds), filters products by latest found time, if not provided, no start time limit
end_time long false End time, timestamp (seconds), filters products by latest found time, if not provided, no end time limit

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/store/product-analysis",
    "params": {
      "id": "9407a696eb444",
      "start_time": 1761408000,
      "end_time": 1763999999
    }
  }'

Response Parameters

Response Body Structure

{
    "code": 200,
    "message": "success",
    "data": {
        "total": {
            "all": 0,
            "total": 25,
            "tiktok": 25,
            "facebook": 0
        },
        "price": {
            "100": 4,
            "10-20": 0,
            "50-100": 16,
            "1-10": 0,
            "20-50": 5
        },
        "type": [
            {
                "ai_type_name_zh": "女装",
                "count": 12,
                "ai_type_name_en": "Women's Clothing",
                "ai_type": "62739c0138365b2f72048ed7"
            },
            {
                "ai_type_name_zh": "其他",
                "count": 2,
                "ai_type_name_en": "Other",
                "ai_type": "62739c2138365b2f72048edb"
            },
            {
                "ai_type_name_zh": "男装",
                "count": 2,
                "ai_type_name_en": "Men's Clothing",
                "ai_type": "62739c0d38365b2f72048ed8"
            }
        ]
    },
    "version": "v1",
    "timestamp": null,
    "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
    "success": true,
    "fail": false
}

Response Field Descriptions

Field 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 Type Description
data Object Product analysis data

data Object Structure

Field Type Description
total Object Platform distribution statistics
type Array[Object] Product category statistics list
price Object Price range distribution statistics

total Object Structure (Platform Distribution Statistics)

Field Type Description
total Long Total number of products
tiktok Long Number of products promoted on TikTok platform
facebook Long Number of products promoted on Facebook platform
all Long Number of products promoted on both TikTok and Facebook

type Array Element Structure (Product Category)

Field Type Description
ai_type String AI category type code
ai_type_name_zh String AI category Chinese name
ai_type_name_en String AI category English name
count Long Number of products in this category

price Object Structure (Price Range Distribution, Unit: USD)

Field Type Description
1-10 Long Number of products in $1-$10 price range
10-20 Long Number of products in $10-$20 price range
20-50 Long Number of products in $20-$50 price range
50-100 Long Number of products in $50-$100 price range
100 Long Number of products with price ≥ $100

Response Examples

Complete Data Example

{
    "code": 200,
    "message": "success",
    "data": {
        "total": {
            "all": 0,
            "total": 25,
            "tiktok": 25,
            "facebook": 0
        },
        "price": {
            "100": 4,
            "10-20": 0,
            "50-100": 16,
            "1-10": 0,
            "20-50": 5
        },
        "type": [
            {
                "ai_type_name_zh": "女装",
                "count": 12,
                "ai_type_name_en": "Women's Clothing",
                "ai_type": "62739c0138365b2f72048ed7"
            },
            {
                "ai_type_name_zh": "其他",
                "count": 2,
                "ai_type_name_en": "Other",
                "ai_type": "62739c2138365b2f72048edb"
            },
            {
                "ai_type_name_zh": "男装",
                "count": 2,
                "ai_type_name_en": "Men's Clothing",
                "ai_type": "62739c0d38365b2f72048ed8"
            }
        ]
    },
    "version": "v1",
    "timestamp": null,
    "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
    "success": true,
    "fail": false
}

Time Range Filter Example

Request parameters:

{
  "id": "12345",
  "start_time": 1704067200,
  "end_time": 1706745599
}

Response data (only returns products found within the specified time range):

{
  "code": 200,
  "message": "success",
  "data": {
    "total": {
      "total": 125,
      "tiktok": 95,
      "facebook": 68,
      "all": 38
    },
    "type": [
      {
        "ai_type": "fashion",
        "ai_type_name_zh": "时尚服饰",
        "ai_type_name_en": "Fashion & Apparel",
        "count": 52
      },
      {
        "ai_type": "electronics",
        "ai_type_name_zh": "电子产品",
        "ai_type_name_en": "Electronics",
        "count": 38
      },
      {
        "ai_type": "beauty",
        "ai_type_name_zh": "美妆护肤",
        "ai_type_name_en": "Beauty & Personal Care",
        "count": 35
      }
    ],
    "price": {
      "100": 2,
      "1-10": 45,
      "10-20": 52,
      "20-50": 20,
      "50-100": 6
    }
  },
  "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. Time Range Filtering

The API supports filtering products through start_time and end_time parameters:

  • Filter Dimension: Product's latest found time (all_latest_found_time)
  • No time parameters: Returns statistics for all products in the store
  • Only start_time: Returns products found from that time point to now
  • Only end_time: Returns products found from earliest to that time point
  • Both provided: Returns products found within that time range

2. Platform Distribution Statistics Explanation

total Field Interpretation:

{
  "total": 850,      // Store has promoted 850 products in total
  "tiktok": 620,     // Of which 620 products have ads on TikTok platform
  "facebook": 480,   // Of which 480 products have ads on Facebook platform
  "all": 250         // Of which 250 products have ads on both platforms
}

Relationship Explanation:

  • tiktok + facebook - all = Number of products promoted on single platform only
  • TikTok only: tiktok - all = 370 products
  • Facebook only: facebook - all = 230 products
  • Both platforms: all = 250 products
  • Total: 370 + 230 + 250 = 850 products

3. Product Category Statistics Explanation

AI Smart Classification:

  • System uses AI algorithms to automatically identify product categories
  • Each product has corresponding category code and Chinese/English names
  • Category statistics help understand store product structure

Common Categories:

  • fashion: Fashion & Apparel
  • electronics: Electronics
  • home_garden: Home & Garden
  • beauty: Beauty & Personal Care
  • sports: Sports & Outdoors
  • toys: Toys & Games
  • food: Food & Beverages
  • pet: Pet Supplies
  • etc.

4. Price Range Distribution Explanation

Price Statistics Rules:

  • Priority uses product's USD price (usd_price)
  • If no USD price but currency is USD, uses original price (price)
  • Other currencies are temporarily not counted

Price Range Division:

Range Code Price Range Applicable Scenarios
1-10 $1 - $10 Low-price items, small items
10-20 $10 - $20 Medium-low price items
20-50 $20 - $50 Medium price items
50-100 $50 - $100 Medium-high price items
100 ≥ $100 High-price items, luxury goods