# EchoTik API - Complete Reference

## Base URL
```
https://open.echotik.live/api/v2
```

## Authentication
- **Method**: Basic Auth (HTTP Basic Authentication)
- **Format**: `-u <username>:<password>` in curl, or `Authorization: Basic <base64(username:password)>` header
- **How to get credentials**: Contact EchoTik customer service (huangshan@echosell.com) to apply for API activation
- **Cost**: Starting at $0.001 per request (free trial: 100 API requests)

## Response Format
All endpoints return JSON with this structure:
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

## Supported Regions
The `region` parameter accepts these country codes:
- **US** - United States
- **GB** - United Kingdom
- **ID** - Indonesia
- **TH** - Thailand
- **PH** - Philippines
- **MY** - Malaysia
- **VN** - Vietnam
- **MX** - Mexico
- **SG** - Singapore
- **SA** - Saudi Arabia
- **BR** - Brazil
- **ES** - Spain

---

## PRODUCT ENDPOINTS

### 1. Product List
```
GET /product/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes (max 100000) | Page number, default 1 |
| page_size | integer | Yes (max 10) | Results per page, default 10 |
| region | string | Yes | Country code (US/BR/GB/etc.) |
| category_id | string | No | Category ID (e.g., 600001) |
| category_l2_id | string | No | Level 2 category (e.g., 851848) |
| category_l3_id | string | No | Level 3 category (e.g., 600621) |
| keyword | string | No | Fuzzy matching keywords |
| free_shipping | integer | No | Filter free shipping products |
| from_flag | integer | No | Cross border: 1=local, 2=overseas |
| sales_flag | integer | No | Sales method: 1=video, 2=live |
| sort_type | integer | No | 0=ascending, 1=descending |
| product_sort_field | integer | No | Sort by: 1=total_sale_cnt, 2=total_sale_gmv_amt, 3=spu_avg_price, 4=total_sale_7d_cnt, 5=total_sale_30d_cnt, 6=total_sale_gmv_7d_amt, 7=total_sale_gmv_30d_amt |

**curl example:**
```bash
curl -i -X GET \
  -u <username>:<password> \
  'https://open.echotik.live/api/v2/product/list?category_id=600001&category_l2_id=851848&category_l3_id=600621&free_shipping=0&from_flag=0&keyword=string&page_num=1&page_size=10&region=BR&sales_flag=0&sort_type=0&product_sort_field=1'
```

### 2. Product Detail
```
GET /product/detail
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| product_id | string | Yes | Product ID |

### 3. Real-Time Product Detail
```
GET /rt/product/detail
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| product_id | string | Yes | Product ID |
| region | string | Yes | Country code |

### 4. Product Trend
```
GET /product/trend
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| product_id | string | Yes | Product ID |
| start_date | string | No | Start date (YYYY-MM-DD) |
| end_date | string | No | End date (YYYY-MM-DD) |

### 5. Product Rank List
```
GET /product/ranklist
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code (US/BR/GB/etc.) |
| date | string | Yes | Date (e.g., 2024-12-15) |
| category_id | string | No | Category ID |
| rank_type | integer | No | Ranking type (0=default) |
| product_rank_field | integer | No | Sort field: 0=default (total_sale_gmv_1d_amt), 1=total_sale_cnt, 2=total_sale_gmv_amt, 3=spu_avg_price, 4=total_sale_7d_cnt, 5=total_sale_30d_cnt, 6=total_sale_gmv_7d_amt, 7=total_sale_gmv_30d_amt |

**curl example:**
```bash
curl -i -X GET \
  -u <username>:<password> \
  'https://open.echotik.live/api/v2/product/ranklist?category_id=600001&date=2024-12-15&page_num=1&page_size=10&product_rank_field=0&rank_type=0&region=BR'
```

**Response fields include:**
- product_id (string)
- product_name (string)
- category_id (string)
- region (string)
- spu_avg_price (number)
- min_price (number)
- max_price (number)
- product_commission_rate (number)
- total_sale_cnt (integer)
- total_sale_gmv_1d_amt (number)

### 6. New Product Rank List
```
GET /product/ranklist/new
```
(Same parameters as product/ranklist - returns new product rankings)

### 7. Product Influencer List
```
GET /product/influencer/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| product_id | string | Yes | Product ID |
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| product_influencer_sort_field | integer | No | Sort: 1=total_views_cnt, 2=total_digg_cnt, 3=total_shares_cnt, 4=total_video_sale_cnt, 5=total_video_sale_gmv_amt, 6=create_time |
| sort_type | integer | No | 0=asc, 1=desc |

### 8. Product Video List
```
GET /product/video/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| product_id | string | Yes | Product ID |
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |

### 9. Product Live List
```
GET /product/live/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| product_id | string | Yes | Product ID |
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |

---

## SHOP/SELLER ENDPOINTS

### 10. Seller List
```
GET /seller/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |
| category_id | string | No | Category ID |
| category_l2_id | string | No | Level 2 category |
| category_l3_id | string | No | Level 3 category |
| keyword | string | No | Search keyword |
| from_flag | integer | No | Cross border filter |
| sales_flag | integer | No | Sales method filter |
| sales_trend_flag | integer | No | Sales trend filter |
| sort_type | integer | No | 0=asc, 1=desc |

**curl example:**
```bash
curl -i -X GET \
  -u <username>:<password> \
  'https://open.echotik.live/api/v2/seller/list?category_id=600001&category_l2_id=851848&category_l3_id=600621&from_flag=0&keyword=string&page_num=1&page_size=10&region=BR&sales_flag=0&sales_trend_flag=0&sort_type=0'
```

### 11. Seller Detail
```
GET /seller/detail
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| seller_id | string | Yes | Seller/Shop ID |

**curl example:**
```bash
curl -i -X GET \
  -u <username>:<password> \
  'https://open.echotik.live/api/v2/seller/detail?seller_id=string'
```

### 12. Seller Trend
```
GET /seller/trend
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| seller_id | string | Yes | Seller ID |
| start_date | string | Yes | Start date (YYYY-MM-DD) |
| end_date | string | Yes | End date (YYYY-MM-DD) |
| page_num | integer | No | Page number |
| page_size | integer | No | Results per page |

### 13. Seller Rank List
```
GET /seller/ranklist
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |
| date | string | Yes | Date (YYYY-MM-DD) |
| category_id | string | No | Category ID |
| rank_type | integer | No | Ranking type |
| seller_rank_field | integer | No | Sort field (0=default) |

**curl example:**
```bash
curl -i -X GET \
  -u <username>:<password> \
  'https://open.echotik.live/api/v2/seller/ranklist?category_id=600001&date=2024-12-15&page_num=1&page_size=10&rank_type=0&region=BR&seller_rank_field=0'
```

### 14. Seller Product List
```
GET /seller/product/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| seller_id | string | Yes | Seller ID |
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |

### 15. Seller Influencer List
```
GET /seller/influencer/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| seller_id | string | Yes | Seller ID |
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| seller_influencer_sort_field | integer | No | Sort field |
| sort_type | integer | No | 0=asc, 1=desc |

### 16. Seller Video List
```
GET /seller/video/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| seller_id | string | Yes | Seller ID |
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| seller_video_sort_field | integer | No | Sort field |
| sort_type | integer | No | 0=asc, 1=desc |

### 17. Seller Live List
```
GET /seller/live/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| seller_id | string | Yes | Seller ID |
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |

---

## CREATOR/INFLUENCER ENDPOINTS

### 18. Influencer List
```
GET /influencer/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |
| keyword | string | No | Search keyword |
| category_id | string | No | Category filter |
| sort_type | integer | No | 0=asc, 1=desc |

### 19. Influencer Detail
```
GET /influencer/detail
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| influencer_id | string | Yes | Influencer/Creator ID |

### 20. Influencer Trend
```
GET /influencer/trend
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| influencer_id | string | Yes | Influencer ID |
| start_date | string | No | Start date |
| end_date | string | No | End date |

### 21. Influencer Rank List
```
GET /influencer/ranklist
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |
| date | string | Yes | Date (YYYY-MM-DD) |
| category_id | string | No | Category filter |
| rank_type | integer | No | Ranking type |

### 22. Influencer Video List
```
GET /influencer/video/list
```

### 23. Influencer Live List
```
GET /influencer/live/list
```

### 24. Influencer Product List
```
GET /influencer/product/list
```

---

## VIDEO ENDPOINTS

### 25. Video List
```
GET /video/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |

### 26. Video Detail
```
GET /video/detail
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| video_id | string | Yes | Video ID |

### 27. Video Trend
```
GET /video/trend
```

### 28. Video Rank List
```
GET /video/ranklist
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |
| date | string | Yes | Date (YYYY-MM-DD) |

### 29. Video Product List
```
GET /video/product/list
```

---

## LIVE BROADCAST ENDPOINTS

### 30. Live List
```
GET /live/list
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |

### 31. Live Detail
```
GET /live/detail
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| live_id | string | Yes | Live broadcast ID |

### 32. Live Product List
```
GET /live/product/list
```

### 33. Live Rank List
```
GET /live/ranklist
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page_num | integer | Yes | Page number |
| page_size | integer | Yes | Results per page |
| region | string | Yes | Country code |
| date | string | Yes | Date (YYYY-MM-DD) |

---

## Sort Field Reference

### Product Sort Fields (product_sort_field / product_rank_field)
| Value | Field | Description |
|-------|-------|-------------|
| 0 | default | Default (total_sale_gmv_1d_amt for ranklist) |
| 1 | total_sale_cnt | Total sales count |
| 2 | total_sale_gmv_amt | Total GMV amount |
| 3 | spu_avg_price | Average price |
| 4 | total_sale_7d_cnt | 7-day sales count |
| 5 | total_sale_30d_cnt | 30-day sales count |
| 6 | total_sale_gmv_7d_amt | 7-day GMV amount |
| 7 | total_sale_gmv_30d_amt | 30-day GMV amount |

### Product Influencer Sort Fields (product_influencer_sort_field)
| Value | Field | Description |
|-------|-------|-------------|
| 1 | total_views_cnt | Total views count |
| 2 | total_digg_cnt | Total likes count |
| 3 | total_shares_cnt | Total shares count |
| 4 | total_video_sale_cnt | Total video sales |
| 5 | total_video_sale_gmv_amt | Total video sales GMV |
| 6 | create_time | Creation time |

---

## Important Notes

1. **Rate Limits**: Not publicly documented. Implement exponential backoff on 429/5xx errors.
2. **Page Size**: Max 10 items per page for product/list endpoint.
3. **Page Num**: Max 100000 for product/list endpoint.
4. **Data**: 2+ years of historical data with daily updates.
5. **Uptime**: 99.9% SLA guaranteed.
6. **Brazil Support**: BR is a supported region code for all endpoints.
7. **40+ endpoints** total across all categories.

## Documentation URLs
- Main docs: https://opendoc.echotik.live/openapi (may be intermittently unavailable)
- Product docs: https://opendoc.echotik.live/openapi/product
- API service info: https://echotik.live/en/api-service
- Contact: huangshan@echosell.com
