淘宝开放平台 - 文档中心

请求地址：

环境	HTTP请求地址	HTTPS请求地址
正式环境	http://gw.api.taobao.com/router/rest	https://eco.taobao.com/router/rest

公共请求参数：

名称	类型	是否必须	描述
method	String	是	API接口名称。
app_key	String	是	TOP分配给应用的AppKey。
target_app_key	String	否	被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。
sign_method	String	是	签名的摘要算法，可选值为：hmac，md5。
sign	String	是	API输入参数签名结果，签名算法介绍请点击这里。
session	String	否	用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。
format	String	否	响应格式。默认为xml格式，可选值：xml，json。
v	String	是	API协议版本，可选值：2.0。
partner_id	String	否	合作伙伴身份标识。
simplify	Boolean	否	是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。

名称	类型	是否必须	示例值	更多限制	描述
report_top_query_dto	ReportTopQueryDTO	必须			查询参数，小时报表只支持查询当天数据
└ order_by_field String 可选 click 排序字段 └ page_no Number 可选 1 第几页 └ order_by_type String 可选 ASC 排序方式，ASC：正序、DESC：倒序 └ page_size Number 可选 10 每页多少条 └ group_by String [] 必须 STAT_GROUP_BY_CAMPAIGN_ID,STAT_GROUP_BY_TIME_HOUR 分组条件，素材分组仅头条2.0支持，STAT_GROUP_BY_ADVERTISER_ID：按照广告主分组，STAT_GROUP_BY_CAMPAIGN_ID：按照计划组分组(腾讯3.0无计划组报表)，STAT_GROUP_BY_ADGROUP_ID：按照计划分组，STAT_GROUP_BY_CREATIVE_ID：按照创意分组，STAT_GROUP_BY_TIME_HOUR：按照小时分组，STAT_GROUP_BY_MATERIAL_ID：按照素材分组，STAT_GROUP_BY_MATERIAL_X_ADGROUP_ID：按照素材X计划分组，STAT_GROUP_BY_COMBINATION_MATERIAL_ID：按照素材组合分组，STAT_GROUP_BY_COMBINATION_MATERIALX_CAMPAIGN_ID：按照素材组合X项目分组 └ fields String [] 可选 cost,adPv,ecpm,click,adCtr,ecpc 需要返回的指标，不指定则返回默认指标 filtering ReportFilterTopQueryDTO 可选 1 过滤条件 └ adgroup_ids Number [] 可选 1 按照计划过滤 └ effect Number 可选 7 转化效果周期，7：7天，15：15天 └ campaign_ids Number [] 可选 1 按照计划组过滤 └ creative_ids Number [] 可选 1 按照创意过滤 └ effect_type Number 可选 1 归因逻辑，1：点击效果，0：展示效果 └ material_id Number 可选 1 按照素材过滤，素材id从adgroup查询接口获取，素材组合报表只支持根据标题素材id筛选 └ advertiser_id Number 必须 1 广告主id └ version Number 可选 9999 平台版本，9999：升级版API（仅巨量2.0API需传入）3:腾讯3.0需要传入 └ the_date String 可选 2020-01-01 查询时间,只支持今天和昨天,格式:yyyy-MM-dd

名称	类型	示例值	描述
result	ReportTopDTO []		报表数据
└ favorite_stores Number 1 收藏店铺量 └ play_nums99 Number 1 99%进度播放数（头条） └ wifi_play_percent String 0.3 wifi播放占比（头条） └ pre_alipay_volume Number 1 预售订单量 └ collection_cost String 2.1 收藏成本 └ search_cost String 2.1 回搜成本 └ convert Number 1 转化数 └ effect_play_rate String 0.3 有效播放率（头条） └ direct_pre_alipay_amount String 2.1 单品预售订单金额 └ adgroup_id Number 1 计划id └ direct_transaction_amount String 1.2 单品成交订单金额 └ live_recharge_nums Number 1 直播间购物金充值笔数 └ share_nums Number 1 分享数（头条） └ direct_return_on_investment String 0.3 单品投资回报率 └ alipay_cost String 2.1 订单成本 └ page_arrive_uv Number 1 页面到达uv └ page_arrive Number 1 页面到达量 └ ad_pv Number 1 展现量 └ direct_pre_alipay_volume Number 1 单品预售订单量 └ campaign_id Number 1 计划组id └ direct_alipay_cost String 2.1 单品订单成本 └ return_on_investment String 0.3 投资回报率 └ live_watch_nums Number 1 直播间观看次数 └ click Number 1 点击量 └ direct_take_order_amount String 2.1 单品拍下订单金额 └ visit_time String 2.1 深度访问时长 └ play_over_nums Number 1 播完数（头条） └ ecpm String 2.1 千次展现成本 └ finish_play_rate String 0.3 播完率（头条） └ visit_cost String 2.1 回访成本 └ effect_play_cost String 2.1 有效播放成本（头条） └ play_nums50 Number 1 50%进度播放数（头条） └ take_order_volume Number 1 拍下订单量 └ ecpc String 2.1 点击单价 └ visit_volume Number 1 回访量 └ favorite_baby_volume Number 1 收藏宝贝量 └ effect_play_nums Number 1 有效播放数（头条） └ live_interaction_nums Number 1 直播间互动量 └ direct_transaction_volume Number 1 单品成交订单量 └ creative_id Number 1 创意id └ direct_add_cart_volume Number 1 单品添加购物车量 └ convert_rate String 0.3 转化率 └ hour Number 0 小时，0-23 └ transaction_amount Number 1 成交订单金额，单位分 └ pre_alipay_amount Number 1 预售订单金额，单位分 └ live_like_nums Number 1 直播间点赞量 └ live_recharge_amount Number 1 直播间购物金充值金额，单位分 └ like_nums Number 1 点赞数（头条） └ live_average_watch_time String 2.2 直播间平均观看时长 └ visit_page_volume String 2.1 深度访问页面数 └ buy_cost String 2.1 加购成本 └ live_follow_nums Number 1 直播间粉丝关注量 └ search_volume Number 1 回搜量 └ cost Number 2 消耗，单位分 └ direct_favorite_baby_volume Number 1 单品收藏量 └ play_nums25 Number 1 25%进度播放数（头条） └ transaction_volume Number 1 成交订单量 └ average_play_time String 2.1 平均单次播放时长（头条） └ live_comment_nums Number 1 直播间评论量 └ advertiser_id Number 1 广告主id └ direct_take_order_volume Number 1 单品拍下订单量 └ take_order_amount Number 1 拍下订单金额，单位分 └ add_cart_volume Number 1 添加购物车量 └ play_nums Number 1 播放数（头条） └ depth_store_volume Number 1 深度进店量 └ ad_ctr String 0.3 点击率 └ convert_cost String 2.1 转化成本 └ play_nums75 Number 1 75%进度播放数（头条） └ play3s_count Number 1 3s播放量（腾讯） └ play5s_count Number 1 5s播放量（腾讯） └ play7s_count Number 1 7s播放量（腾讯） └ platform_page_view_count Number 1 落地页浏览量（腾讯） └ lan_button_click_count Number 1 落地页内按钮点击次数（腾讯） └ lan_jump_button_clickers Number 1 落地页内按钮点击人数（腾讯） └ lan_jump_button_click_rate String 0.1 落地页内按钮点击率（腾讯） └ material_id Number 1 素材id，基础素材报表返回 └ title_material_id Number 1 标题素材id，素材组合报表返回 └ image_material_id Number 1 图片素材id，素材组合报表返回 └ video_material_id Number 1 视频素材id，素材组合报表返回 └ adgroup_name String 计划名称计划名称 └ campaign_name String 计划组名称计划组名称
total	Number	1	总条数

JAVA
.NET
PHP
CURL
Python
C/C++
NodeJS

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
UnideskRtaReportHourlyGetRequest req = new UnideskRtaReportHourlyGetRequest();
UnideskRtaReportHourlyGetRequest.ReportTopQueryDTO obj1 = new UnideskRtaReportHourlyGetRequest.ReportTopQueryDTO();
obj1.setOrderByField("click");
obj1.setPageNo(1L);
obj1.setOrderByType("ASC");
obj1.setPageSize(10L);
obj1.setGroupBy("STAT_GROUP_BY_CAMPAIGN_ID,STAT_GROUP_BY_TIME_HOUR");
obj1.setFields("cost,adPv,ecpm,click,adCtr,ecpc");
UnideskRtaReportHourlyGetRequest.ReportFilterTopQueryDTO obj2 = new UnideskRtaReportHourlyGetRequest.ReportFilterTopQueryDTO();
obj2.setAdgroupIds(new Long[] { 1 };
);
obj2.setEffect(7L);
obj2.setCampaignIds(new Long[] { 1 };
);
obj2.setCreativeIds(new Long[] { 1 };
);
obj2.setEffectType(1L);
obj2.setMaterialId(1L);
obj1.setFiltering(obj2);
obj1.setAdvertiserId(1L);
obj1.setVersion(9999L);
obj1.setTheDate("2020-01-01");
req.setReportTopQueryDto(obj1);
UnideskRtaReportHourlyGetResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
UnideskRtaReportHourlyGetRequest req = new UnideskRtaReportHourlyGetRequest();
UnideskRtaReportHourlyGetRequest.ReportTopQueryDTODomain obj1 = new UnideskRtaReportHourlyGetRequest.ReportTopQueryDTODomain();
obj1.OrderByField = "click";
obj1.PageNo = 1L;
obj1.OrderByType = "ASC";
obj1.PageSize = 10L;
obj1.GroupBy = "STAT_GROUP_BY_CAMPAIGN_ID,STAT_GROUP_BY_TIME_HOUR";
obj1.Fields = "cost,adPv,ecpm,click,adCtr,ecpc";
UnideskRtaReportHourlyGetRequest.ReportFilterTopQueryDTODomain obj2 = new UnideskRtaReportHourlyGetRequest.ReportFilterTopQueryDTODomain();
obj2.AdgroupIds = new long[] { 1 };
;
obj2.Effect = 7L;
obj2.CampaignIds = new long[] { 1 };
;
obj2.CreativeIds = new long[] { 1 };
;
obj2.EffectType = 1L;
obj2.MaterialId = 1L;
obj1.Filtering= obj2;
obj1.AdvertiserId = 1L;
obj1.Version = 9999L;
obj1.TheDate = "2020-01-01";
req.ReportTopQueryDto_ = obj1;
UnideskRtaReportHourlyGetResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new UnideskRtaReportHourlyGetRequest;
$report_top_query_dto = new ReportTopQueryDTO;
$report_top_query_dto->order_by_field="click";
$report_top_query_dto->page_no="1";
$report_top_query_dto->order_by_type="ASC";
$report_top_query_dto->page_size="10";
$report_top_query_dto->group_by="STAT_GROUP_BY_CAMPAIGN_ID,STAT_GROUP_BY_TIME_HOUR";
$report_top_query_dto->fields="cost,adPv,ecpm,click,adCtr,ecpc";
$filtering = new ReportFilterTopQueryDTO;
$filtering->adgroup_ids="1";
$filtering->effect="7";
$filtering->campaign_ids="1";
$filtering->creative_ids="1";
$filtering->effect_type="1";
$filtering->material_id="1";
$report_top_query_dto->filtering = $filtering;
$report_top_query_dto->advertiser_id="1";
$report_top_query_dto->version="9999";
$report_top_query_dto->the_date="2020-01-01";
$req->setReportTopQueryDto(json_encode($report_top_query_dto));
$resp = $c->execute($req, $sessionKey);

curl -X POST 'http://gw.api.taobao.com/router/rest' \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'app_key=12129701' \
-d 'format=json' \
-d 'method=taobao.unidesk.rta.report.hourly.get' \
-d 'partner_id=apidoc' \
-d 'session=61112013-6a3e-4443-8952-1ae44aed120a' \
-d 'sign=549E448F8FDB29BD30DE506189E21E95' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-11-06+00%3A06%3A05' \
-d 'v=2.0' \
-d 'report_top_query_dto=null'

# -*- coding: utf-8 -*-
import top.api

req=top.api.UnideskRtaReportHourlyGetRequest(url,port)
req.set_app_info(top.appinfo(appkey,secret))

req.report_top_query_dto="数据结构示例JSON格式"
try:
	resp= req.getResponse(sessionkey)
	print(resp)
except Exception,e:
	print(e)

pTopRequest pRequest = alloc_top_request();
pTopResponse pResponse = NULL;
pTaobaoClient pClient = alloc_taobao_client(url, appkey, appsecret);
set_api_name(pRequest,"taobao.unidesk.rta.report.hourly.get");
add_param(pRequest,"report_top_query_dto","数据结构JSON示例");
pResponse = top_execute(pClient,pRequest,sessionKey);
printf("ret code:%d\n",pResponse->code);
if(pResponse->code == 0){
	pTopResponseIterator ite = init_response_iterator(pResponse);
	pResultItem pResultItem = alloc_result_item();
	while(parseNext(ite, pResultItem) == 0){
		printf("%s:%s\n",pResultItem->key,pResultItem->value);
	}
	destroy_response_iterator(ite);
	destroy_result_item(pResultItem);
}
destroy_top_request(pRequest);
destroy_top_response(pResponse);
destroy_taobao_client(pClient);

TopClient = require('./topClient').TopClient;
var client = new TopClient({
	'appkey': 'appkey',
	'appsecret': 'secret',
	'REST_URL': 'http://gw.api.taobao.com/router/rest'
});

client.execute('taobao.unidesk.rta.report.hourly.get', {
	'report_top_query_dto':'数据结构JSON示例'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<unidesk_rta_report_hourly_get_response>
    <result>
        <report_top_d_t_o>
            <favorite_stores>1</favorite_stores>
            <play_nums99>1</play_nums99>
            <wifi_play_percent>0.3</wifi_play_percent>
            <pre_alipay_volume>1</pre_alipay_volume>
            <collection_cost>2.1</collection_cost>
            <search_cost>2.1</search_cost>
            <convert>1</convert>
            <effect_play_rate>0.3</effect_play_rate>
            <direct_pre_alipay_amount>2.1</direct_pre_alipay_amount>
            <adgroup_id>1</adgroup_id>
            <direct_transaction_amount>1.2</direct_transaction_amount>
            <live_recharge_nums>1</live_recharge_nums>
            <share_nums>1</share_nums>
            <direct_return_on_investment>0.3</direct_return_on_investment>
            <alipay_cost>2.1</alipay_cost>
            <page_arrive_uv>1</page_arrive_uv>
            <page_arrive>1</page_arrive>
            <ad_pv>1</ad_pv>
            <direct_pre_alipay_volume>1</direct_pre_alipay_volume>
            <campaign_id>1</campaign_id>
            <direct_alipay_cost>2.1</direct_alipay_cost>
            <return_on_investment>0.3</return_on_investment>
            <live_watch_nums>1</live_watch_nums>
            <click>1</click>
            <direct_take_order_amount>2.1</direct_take_order_amount>
            <visit_time>2.1</visit_time>
            <play_over_nums>1</play_over_nums>
            <ecpm>2.1</ecpm>
            <finish_play_rate>0.3</finish_play_rate>
            <visit_cost>2.1</visit_cost>
            <effect_play_cost>2.1</effect_play_cost>
            <play_nums50>1</play_nums50>
            <take_order_volume>1</take_order_volume>
            <ecpc>2.1</ecpc>
            <visit_volume>1</visit_volume>
            <favorite_baby_volume>1</favorite_baby_volume>
            <effect_play_nums>1</effect_play_nums>
            <live_interaction_nums>1</live_interaction_nums>
            <direct_transaction_volume>1</direct_transaction_volume>
            <creative_id>1</creative_id>
            <direct_add_cart_volume>1</direct_add_cart_volume>
            <convert_rate>0.3</convert_rate>
            <hour>0</hour>
            <transaction_amount>1</transaction_amount>
            <pre_alipay_amount>1</pre_alipay_amount>
            <live_like_nums>1</live_like_nums>
            <live_recharge_amount>1</live_recharge_amount>
            <like_nums>1</like_nums>
            <live_average_watch_time>2.2</live_average_watch_time>
            <visit_page_volume>2.1</visit_page_volume>
            <buy_cost>2.1</buy_cost>
            <live_follow_nums>1</live_follow_nums>
            <search_volume>1</search_volume>
            <cost>2</cost>
            <direct_favorite_baby_volume>1</direct_favorite_baby_volume>
            <play_nums25>1</play_nums25>
            <transaction_volume>1</transaction_volume>
            <average_play_time>2.1</average_play_time>
            <live_comment_nums>1</live_comment_nums>
            <advertiser_id>1</advertiser_id>
            <direct_take_order_volume>1</direct_take_order_volume>
            <take_order_amount>1</take_order_amount>
            <add_cart_volume>1</add_cart_volume>
            <play_nums>1</play_nums>
            <depth_store_volume>1</depth_store_volume>
            <ad_ctr>0.3</ad_ctr>
            <convert_cost>2.1</convert_cost>
            <play_nums75>1</play_nums75>
            <play3s_count>1</play3s_count>
            <play5s_count>1</play5s_count>
            <play7s_count>1</play7s_count>
            <platform_page_view_count>1</platform_page_view_count>
            <lan_button_click_count>1</lan_button_click_count>
            <lan_jump_button_clickers>1</lan_jump_button_clickers>
            <lan_jump_button_click_rate>0.1</lan_jump_button_click_rate>
            <material_id>1</material_id>
            <title_material_id>1</title_material_id>
            <image_material_id>1</image_material_id>
            <video_material_id>1</video_material_id>
            <adgroup_name>计划名称</adgroup_name>
            <campaign_name>计划组名称</campaign_name>
        </report_top_d_t_o>
    </result>
    <total>1</total>
</unidesk_rta_report_hourly_get_response>

{
    "unidesk_rta_report_hourly_get_response":{
        "result":{
            "report_top_d_t_o":[
                {
                    "favorite_stores":1,
                    "play_nums99":1,
                    "wifi_play_percent":"0.3",
                    "pre_alipay_volume":1,
                    "collection_cost":"2.1",
                    "search_cost":"2.1",
                    "convert":1,
                    "effect_play_rate":"0.3",
                    "direct_pre_alipay_amount":"2.1",
                    "adgroup_id":1,
                    "direct_transaction_amount":"1.2",
                    "live_recharge_nums":1,
                    "share_nums":1,
                    "direct_return_on_investment":"0.3",
                    "alipay_cost":"2.1",
                    "page_arrive_uv":1,
                    "page_arrive":1,
                    "ad_pv":1,
                    "direct_pre_alipay_volume":1,
                    "campaign_id":1,
                    "direct_alipay_cost":"2.1",
                    "return_on_investment":"0.3",
                    "live_watch_nums":1,
                    "click":1,
                    "direct_take_order_amount":"2.1",
                    "visit_time":"2.1",
                    "play_over_nums":1,
                    "ecpm":"2.1",
                    "finish_play_rate":"0.3",
                    "visit_cost":"2.1",
                    "effect_play_cost":"2.1",
                    "play_nums50":1,
                    "take_order_volume":1,
                    "ecpc":"2.1",
                    "visit_volume":1,
                    "favorite_baby_volume":1,
                    "effect_play_nums":1,
                    "live_interaction_nums":1,
                    "direct_transaction_volume":1,
                    "creative_id":1,
                    "direct_add_cart_volume":1,
                    "convert_rate":"0.3",
                    "hour":0,
                    "transaction_amount":1,
                    "pre_alipay_amount":1,
                    "live_like_nums":1,
                    "live_recharge_amount":1,
                    "like_nums":1,
                    "live_average_watch_time":"2.2",
                    "visit_page_volume":"2.1",
                    "buy_cost":"2.1",
                    "live_follow_nums":1,
                    "search_volume":1,
                    "cost":2,
                    "direct_favorite_baby_volume":1,
                    "play_nums25":1,
                    "transaction_volume":1,
                    "average_play_time":"2.1",
                    "live_comment_nums":1,
                    "advertiser_id":1,
                    "direct_take_order_volume":1,
                    "take_order_amount":1,
                    "add_cart_volume":1,
                    "play_nums":1,
                    "depth_store_volume":1,
                    "ad_ctr":"0.3",
                    "convert_cost":"2.1",
                    "play_nums75":1,
                    "play3s_count":1,
                    "play5s_count":1,
                    "play7s_count":1,
                    "platform_page_view_count":1,
                    "lan_button_click_count":1,
                    "lan_jump_button_clickers":1,
                    "lan_jump_button_click_rate":"0.1",
                    "material_id":1,
                    "title_material_id":1,
                    "image_material_id":1,
                    "video_material_id":1,
                    "adgroup_name":"计划名称",
                    "campaign_name":"计划组名称"
                }
            ]
        },
        "total":1
    }
}

XML示例
JSON示例

<error_response>
    <code>50</code>
    <msg>Remote service error</msg>
    <sub_code>isv.invalid-parameter</sub_code>
    <sub_msg>非法参数</sub_msg>
</error_response>

{
	"error_response":{
		"msg":"Remote service error",
		"code":50,
		"sub_msg":"非法参数",
		"sub_code":"isv.invalid-parameter"
	}
}

错误码	错误描述	解决方案

API测试工具错误码查询工具 SDK下载

开放平台

阿里妈妈-UniDesk

taobao.unidesk.rta.report.hourly.get (UD报表-小时数据报表查询接口)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ