店铺播放成本明细查询接口
接口信息
- 接口名称: 店铺播放成本明细查询接口
- 请求方法: GET
- 接口地址:
/open-api/v1/data
- 接口路径:
/v3/api/open/store/play-cost/detail
- 接口描述:
- 查询指定店铺在不同平台(TikTok/Facebook)的每日播放成本明细数据
- 支持按时间范围筛选,获取店铺每日的广告投放表现数据
- 包含广告数量、播放次数、CPM成本、互动数据(点赞、评论、分享)等指标
- 价格说明:
免费
请求头:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 api 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口路径 |
"/v3/api/open/store/play-cost/detail" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| id |
string |
true |
店铺 ID 为 13 位字符串(例如:c2d5b2547218a),对应店铺榜单列表接口返回结果中的 store_id 字段 |
| type |
integer |
false |
平台类型:1-TikTok平台,2-Facebook平台,默认为1 |
| time_start |
long |
false |
开始时间,时间戳(秒),不传则不限制开始时间 |
| time_end |
long |
false |
结束时间,时间戳(秒),不传则不限制结束时间 |
| current_page |
integer |
false |
当前页码,默认为1 |
| page_size |
integer |
false |
每页数量,默认为10 |
请求示例
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/play-cost/detail",
"params": {
"id": "c2d5b2547218a",
"type": 1,
"time_start": 1704067200,
"time_end": 1706745599,
"current_page": 1,
"page_size": 10
}
}'
响应参数
响应体结构
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"max_cpm": 12.6,
"digg_count": 8,
"ad_count": 1,
"comment": 0,
"share": 0,
"play_count": 2271,
"day": 1706716800,
"min_cpm": 3.14
},
{
"max_cpm": 17.56,
"digg_count": 2,
"ad_count": 2,
"comment": 0,
"share": 0,
"play_count": 3165,
"day": 1706630400,
"min_cpm": 4.38
},
{
"max_cpm": 21.28,
"digg_count": 6,
"ad_count": 2,
"comment": 0,
"share": 0,
"play_count": 3836,
"day": 1706544000,
"min_cpm": 5.31
},
{
"max_cpm": 7.93,
"digg_count": 4,
"ad_count": 1,
"comment": 0,
"share": 0,
"play_count": 1429,
"day": 1706284800,
"min_cpm": 1.98
},
{
"max_cpm": 30.8,
"digg_count": 21,
"ad_count": 3,
"comment": 0,
"share": 1,
"play_count": 5552,
"day": 1706198400,
"min_cpm": 7.69
},
{
"max_cpm": 54.11,
"digg_count": 20,
"ad_count": 3,
"comment": 1,
"share": 0,
"play_count": 9754,
"day": 1706112000,
"min_cpm": 13.5
},
{
"max_cpm": 27.51,
"digg_count": 4,
"ad_count": 3,
"comment": 0,
"share": 0,
"play_count": 4959,
"day": 1706025600,
"min_cpm": 6.86
},
{
"max_cpm": 46.78,
"digg_count": 24,
"ad_count": 3,
"comment": 0,
"share": 2,
"play_count": 8434,
"day": 1705939200,
"min_cpm": 11.68
},
{
"max_cpm": 85.55,
"digg_count": 54,
"ad_count": 3,
"comment": 4,
"share": 0,
"play_count": 15423,
"day": 1705852800,
"min_cpm": 21.35
},
{
"max_cpm": 48.53,
"digg_count": 31,
"ad_count": 3,
"comment": 0,
"share": 2,
"play_count": 8748,
"day": 1705766400,
"min_cpm": 12.11
}
],
"page": {
"total_count": 23,
"current_page": 1,
"page_count": 3,
"page_size": 10
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
响应字段说明
| 字段名 |
类型 |
描述 |
| code |
Integer |
响应状态码,200 表示成功 |
| message |
String |
响应消息 |
| data |
Object |
响应数据 |
| version |
String |
API 版本 |
| timestamp |
String |
响应时间戳 |
| sign |
String |
响应签名 |
| remaining_credits |
Long |
当前请求后的剩余可用积分 |
| consumed_credits |
Long |
本次请求消耗的积分 |
| success |
Boolean |
请求是否成功 |
| fail |
Boolean |
请求是否失败 |
响应结果信息字段
| 字段名 |
类型 |
描述 |
| data |
Array[Object] |
每日数据列表 |
| page |
Object |
分页信息 |
data 数组元素结构(每日数据)
| 字段名 |
类型 |
描述 |
| day |
Long |
统计日期,时间戳(秒) |
| ad_count |
Long |
该日广告数量 |
| play_count |
Long |
该日播放次数(仅TikTok平台有此字段,type=1时返回) |
| min_cpm |
Double |
该日最小CPM成本(仅TikTok平台有此字段,type=1时返回) |
| max_cpm |
Double |
该日最大CPM成本(仅TikTok平台有此字段,type=1时返回) |
| digg_count |
Long |
该日点赞数 |
| comment |
Long |
该日评论数 |
| share |
Long |
该日分享数 |
说明:
- 当 type=1(TikTok平台)时,返回所有字段
- 当 type=2(Facebook平台)时,play_count、min_cpm、max_cpm 字段为 null 或不返回
page 对象结构
| 字段名 |
类型 |
描述 |
| current_page |
Integer |
当前页码 |
| page_size |
Integer |
每页数量 |
| total |
Long |
总记录数 |
响应示例
TikTok 平台数据示例(type=1)
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1706745600,
"ad_count": 150,
"play_count": 1250000,
"min_cpm": 2.5,
"max_cpm": 15.8,
"digg_count": 35000,
"comment": 2500,
"share": 1800
},
{
"day": 1706659200,
"ad_count": 145,
"play_count": 1180000,
"min_cpm": 2.3,
"max_cpm": 14.5,
"digg_count": 32000,
"comment": 2300,
"share": 1650
},
{
"day": 1706572800,
"ad_count": 138,
"play_count": 1050000,
"min_cpm": 2.1,
"max_cpm": 13.2,
"digg_count": 28000,
"comment": 2100,
"share": 1500
}
],
"page": {
"current_page": 1,
"page_size": 10,
"total": 60
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
Facebook 平台数据示例(type=2)
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"day": 1706745600,
"ad_count": 85,
"play_count": 0,
"min_cpm": null,
"max_cpm": null,
"digg_count": 12000,
"comment": 850,
"share": 620
},
{
"day": 1706659200,
"ad_count": 80,
"play_count": 0,
"min_cpm": null,
"max_cpm": null,
"digg_count": 11500,
"comment": 800,
"share": 580
}
],
"page": {
"current_page": 1,
"page_size": 10,
"total": 45
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"fail": false,
"success": true
}
错误码说明
| 错误码 |
描述 |
| 200 |
成功 |
| 400 |
请求参数错误 |
| 500 |
服务器内部错误 |
使用说明
-
平台类型说明:
- type=1 查询 TikTok 平台数据,返回包含播放次数和CPM成本的完整数据
- type=2 查询 Facebook 平台数据,返回互动数据但不包含播放次数和CPM成本
-
时间范围:
- time_start 和 time_end 均为可选参数
- 如果不传时间参数,则返回店铺所有历史数据
- 时间戳单位为秒
-
数据排序:
- 数据按统计日期(day字段)倒序排列,最新的日期排在前面
-
分页:
- 支持分页查询,通过 current_page 和 page_size 控制
- 默认每页10条记录