淘宝开放平台 - 文档中心

请求地址：

环境	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。

名称	类型	是否必须	示例值	更多限制	描述
bid_request	BidRequest	必须			竞价请求
app_info AppInfo 可选应用信息 └ app_name String 可选今日头条 ssp的app名称 └ pkg String 可选 com.ss.android.article.news ssp的app包名 └ version_code Number 可选 13 app版本号 └ version_name String 可选 1.0.0 app版本名 sdk_info SdkInfo 可选 sdk信息 └ version_name String 可选 1.0.1 sdk版本名 └ version_code Number 可选 1 sdk版本号 device_info DeviceInfo 必须设备信息 └ model String 可选 X80 机型 └ os_version String 可选 1.0.1 操作系统版本 └ screen_width Number 可选 1024 屏幕分辨率宽度 └ device_type String 必须 OFFLINE_MACHINE 设备类型(OFFLINE_MACHINE/PHONE等) └ vendor String 可选华为厂商名称 └ os_type String 必须 ANDROID 操作系统类型(ANDROID/ALIOS/WINDOWS/IOS) └ client_type String 必须 PHONE_SDK 客户端类型(MULTIPORT_SDK/PHONE_SDK) └ screen_height Number 可选 12 分辨率高 └ screen_type String 可选 VENDING_MACHINE 屏幕类型(VENDING_MACHINE) udid Udid 必须设备id └ imei String 可选 123123123123 imei └ mac String 可选 123123123123 mac └ android_id String 可选 12312321 andorid设备id └ umid_token String 可选 12312 umidToken └ uuid String 可选 123123 uuid └ serial_num String 可选 213 设备序列号 └ sim_sn String 可选 123123 sim序列号 └ imsi String 可选 123123 设备序列号 └ utdid String 可选 123123 utdid └ device_id String 可选 123123123 设备id user_info UserInfo 可选用户信息 └ id String 可选 123123123 用户id └ info 可选 {} 补充信息 └ channel String 必须 123 渠道id network Network 可选网络信息 └ cellular_id String 可选 123123 基站id └ operator_type String 可选 CHINA_MOBILE 运营商(UNKNOWN_OPERATOR/CHINA_MOBILE/CHINA_TELECOM/CHINA_UNICOM/OTHER_OPERATOR) └ connection_type String 可选 WIFI 网络类型(CONNECTION_UNKNOWN/CELL_UNKNOWN/CELL_2G/CELL_3G/CELL_4G/CELL_5G/WIFI/ETHERNET/NEW_TYPE) └ ip String 必须 121.12.12.12 ip地址 └ version String 必须 1 版本号 location Location 可选定位信息 └ coordinate_type String 可选 WGS84 定位类型(WGS84/GCJ02/BD09) └ longitude String 可选 12.12 经度 └ latitude String 可选 123.123 纬度 ad_slots AdSlot [] 必须广告位列表 └ ad_slot_id String 可选 INVENO_ADZONE_252 广告位id └ query 可选 {} 查询条件 └ count Number 可选 10 个数 └ batch_id String 可选 123123 批次id

名称	类型	示例值	描述
id	String	12313132123123	请求id
result_msg	String	操作成功	返回结果描述
result	BidResponse	{}	返回结果
ad_slots AdSlots [] [] 广告位列表 └ ad_slot_id String INVENO_ADZONE_252 广告位id ads Ad [] [] 广告集合 └ template_id String 252 广告模板id └ price Number 0 价格 └ adm String "{}" 物料 target Target {} 广告目标对象 └ target_type String BROWSER 广告目标类型 └ target_value String http://www.baidu.com 广告目标值 monitor Monitor {} 监控对象 └ view_url_list String [] [""] 曝光地址 └ end_play_url_list String [] [""] 结束播放地址 └ start_play_url_list String [] [""] 开始播放地址 └ click_url_list String [] [""] 点击地址 └ event_url_list String [] [""] 事件上报地址
result_code	String	200	响应码
is_success	Boolean	true	是否操作成功

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
YunosAdmarketAdBidRequest req = new YunosAdmarketAdBidRequest();
YunosAdmarketAdBidRequest.BidRequest obj1 = new YunosAdmarketAdBidRequest.BidRequest();
YunosAdmarketAdBidRequest.AppInfo obj2 = new YunosAdmarketAdBidRequest.AppInfo();
obj2.setAppName("今日头条");
obj2.setPkg("com.ss.android.article.news");
obj2.setVersionCode(13L);
obj2.setVersionName("1.0.0");
obj1.setAppInfo(obj2);
YunosAdmarketAdBidRequest.SdkInfo obj3 = new YunosAdmarketAdBidRequest.SdkInfo();
obj3.setVersionName("1.0.1");
obj3.setVersionCode(1L);
obj1.setSdkInfo(obj3);
YunosAdmarketAdBidRequest.DeviceInfo obj4 = new YunosAdmarketAdBidRequest.DeviceInfo();
obj4.setModel("X80");
obj4.setOsVersion("1.0.1");
obj4.setScreenWidth(1024L);
obj4.setDeviceType("OFFLINE_MACHINE");
obj4.setVendor("华为");
obj4.setOsType("ANDROID");
obj4.setClientType("PHONE_SDK");
obj4.setScreenHeight(12L);
obj4.setScreenType("VENDING_MACHINE");
obj1.setDeviceInfo(obj4);
YunosAdmarketAdBidRequest.Udid obj5 = new YunosAdmarketAdBidRequest.Udid();
obj5.setImei("123123123123");
obj5.setMac("123123123123");
obj5.setAndroidId("12312321");
obj5.setUmidToken("12312");
obj5.setUuid("123123");
obj5.setSerialNum("213");
obj5.setSimSn("123123");
obj5.setImsi("123123");
obj5.setUtdid("123123");
obj5.setDeviceId("123123123");
obj1.setUdid(obj5);
YunosAdmarketAdBidRequest.UserInfo obj6 = new YunosAdmarketAdBidRequest.UserInfo();
obj6.setId("123123123");
obj1.setUserInfo(obj6);
obj1.setChannel("123");
YunosAdmarketAdBidRequest.Network obj7 = new YunosAdmarketAdBidRequest.Network();
obj7.setCellularId("123123");
obj7.setOperatorType("CHINA_MOBILE");
obj7.setConnectionType("WIFI");
obj7.setIp("121.12.12.12");
obj1.setNetwork(obj7);
obj1.setVersion("1");
YunosAdmarketAdBidRequest.Location obj8 = new YunosAdmarketAdBidRequest.Location();
obj8.setCoordinateType("WGS84");
obj8.setLongitude("12.12");
obj8.setLatitude("123.123");
obj1.setLocation(obj8);
List<YunosAdmarketAdBidRequest.AdSlot> list10 = new ArrayList<YunosAdmarketAdBidRequest.AdSlot>();
YunosAdmarketAdBidRequest.AdSlot obj11 = new YunosAdmarketAdBidRequest.AdSlot();
list10.add(obj11);
obj11.setAdSlotId("INVENO_ADZONE_252");
obj11.setCount(10L);
obj1.setAdSlots(list10);
obj1.setBatchId("123123");
req.setBidRequest(obj1);
YunosAdmarketAdBidResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
YunosAdmarketAdBidRequest req = new YunosAdmarketAdBidRequest();
YunosAdmarketAdBidRequest.BidRequestDomain obj1 = new YunosAdmarketAdBidRequest.BidRequestDomain();
YunosAdmarketAdBidRequest.AppInfoDomain obj2 = new YunosAdmarketAdBidRequest.AppInfoDomain();
obj2.AppName = "今日头条";
obj2.Pkg = "com.ss.android.article.news";
obj2.VersionCode = 13L;
obj2.VersionName = "1.0.0";
obj1.AppInfo= obj2;
YunosAdmarketAdBidRequest.SdkInfoDomain obj3 = new YunosAdmarketAdBidRequest.SdkInfoDomain();
obj3.VersionName = "1.0.1";
obj3.VersionCode = 1L;
obj1.SdkInfo= obj3;
YunosAdmarketAdBidRequest.DeviceInfoDomain obj4 = new YunosAdmarketAdBidRequest.DeviceInfoDomain();
obj4.Model = "X80";
obj4.OsVersion = "1.0.1";
obj4.ScreenWidth = 1024L;
obj4.DeviceType = "OFFLINE_MACHINE";
obj4.Vendor = "华为";
obj4.OsType = "ANDROID";
obj4.ClientType = "PHONE_SDK";
obj4.ScreenHeight = 12L;
obj4.ScreenType = "VENDING_MACHINE";
obj1.DeviceInfo= obj4;
YunosAdmarketAdBidRequest.UdidDomain obj5 = new YunosAdmarketAdBidRequest.UdidDomain();
obj5.Imei = "123123123123";
obj5.Mac = "123123123123";
obj5.AndroidId = "12312321";
obj5.UmidToken = "12312";
obj5.Uuid = "123123";
obj5.SerialNum = "213";
obj5.SimSn = "123123";
obj5.Imsi = "123123";
obj5.Utdid = "123123";
obj5.DeviceId = "123123123";
obj1.Udid= obj5;
YunosAdmarketAdBidRequest.UserInfoDomain obj6 = new YunosAdmarketAdBidRequest.UserInfoDomain();
obj6.Id = "123123123";
obj1.UserInfo= obj6;
obj1.Channel = "123";
YunosAdmarketAdBidRequest.NetworkDomain obj7 = new YunosAdmarketAdBidRequest.NetworkDomain();
obj7.CellularId = "123123";
obj7.OperatorType = "CHINA_MOBILE";
obj7.ConnectionType = "WIFI";
obj7.Ip = "121.12.12.12";
obj1.Network= obj7;
obj1.Version = "1";
YunosAdmarketAdBidRequest.LocationDomain obj8 = new YunosAdmarketAdBidRequest.LocationDomain();
obj8.CoordinateType = "WGS84";
obj8.Longitude = "12.12";
obj8.Latitude = "123.123";
obj1.Location= obj8;
List<YunosAdmarketAdBidRequest.AdSlotDomain> list10 = new List<YunosAdmarketAdBidRequest.AdSlotDomain>();
YunosAdmarketAdBidRequest.AdSlotDomain obj11 = new YunosAdmarketAdBidRequest.AdSlotDomain();
list10.Add(obj11);
obj11.AdSlotId = "INVENO_ADZONE_252";
obj11.Count = 10L;
obj1.AdSlots= list10;
obj1.BatchId = "123123";
req.BidRequest_ = obj1;
YunosAdmarketAdBidResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new YunosAdmarketAdBidRequest;
$bid_request = new BidRequest;
$app_info = new AppInfo;
$app_info->app_name="今日头条";
$app_info->pkg="com.ss.android.article.news";
$app_info->version_code="13";
$app_info->version_name="1.0.0";
$bid_request->app_info = $app_info;
$sdk_info = new SdkInfo;
$sdk_info->version_name="1.0.1";
$sdk_info->version_code="1";
$bid_request->sdk_info = $sdk_info;
$device_info = new DeviceInfo;
$device_info->model="X80";
$device_info->os_version="1.0.1";
$device_info->screen_width="1024";
$device_info->device_type="OFFLINE_MACHINE";
$device_info->vendor="华为";
$device_info->os_type="ANDROID";
$device_info->client_type="PHONE_SDK";
$device_info->screen_height="12";
$device_info->screen_type="VENDING_MACHINE";
$bid_request->device_info = $device_info;
$udid = new Udid;
$udid->imei="123123123123";
$udid->mac="123123123123";
$udid->android_id="12312321";
$udid->umid_token="12312";
$udid->uuid="123123";
$udid->serial_num="213";
$udid->sim_sn="123123";
$udid->imsi="123123";
$udid->utdid="123123";
$udid->device_id="123123123";
$bid_request->udid = $udid;
$user_info = new UserInfo;
$user_info->id="123123123";
$bid_request->user_info = $user_info;
$bid_request->channel="123";
$network = new Network;
$network->cellular_id="123123";
$network->operator_type="CHINA_MOBILE";
$network->connection_type="WIFI";
$network->ip="121.12.12.12";
$bid_request->network = $network;
$bid_request->version="1";
$location = new Location;
$location->coordinate_type="WGS84";
$location->longitude="12.12";
$location->latitude="123.123";
$bid_request->location = $location;
$ad_slots = new AdSlot;
$ad_slots->ad_slot_id="INVENO_ADZONE_252";
$ad_slots->count="10";
$bid_request->ad_slots = $ad_slots;
$bid_request->batch_id="123123";
$req->setBidRequest(json_encode($bid_request));
$resp = $c->execute($req);

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=yunos.admarket.ad.bid' \
-d 'partner_id=apidoc' \
-d 'sign=1E5D1EEA614F0A2DDCE259A4597E5D16' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-04-28+13%3A22%3A28' \
-d 'v=2.0' \
-d 'bid_request=null'

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

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

req.bid_request=""
try:
	resp= req.getResponse()
	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,"yunos.admarket.ad.bid");
add_param(pRequest,"bid_request","数据结构JSON示例");
pResponse = top_execute(pClient,pRequest,NULL);
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('yunos.admarket.ad.bid', {
	'bid_request':'数据结构JSON示例'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<yunos_admarket_ad_bid_response>
    <id>12313132123123</id>
    <result_msg>操作成功</result_msg>
    <result>
        <ad_slots>
            <ad_slots>
                <ad_slot_id>INVENO_ADZONE_252</ad_slot_id>
                <ads>
                    <ad>
                        <template_id>252</template_id>
                        <price>0</price>
                        <adm>&quot;{}&quot;</adm>
                        <target>
                            <target_type>BROWSER</target_type>
                            <target_value>http://www.baidu.com</target_value>
                        </target>
                        <monitor>
                            <view_url_list>
                                <string>[&quot;&quot;]</string>
                            </view_url_list>
                            <end_play_url_list>
                                <string>[&quot;&quot;]</string>
                            </end_play_url_list>
                            <start_play_url_list>
                                <string>[&quot;&quot;]</string>
                            </start_play_url_list>
                            <click_url_list>
                                <string>[&quot;&quot;]</string>
                            </click_url_list>
                            <event_url_list>
                                <string>[&quot;&quot;]</string>
                            </event_url_list>
                        </monitor>
                    </ad>
                </ads>
            </ad_slots>
        </ad_slots>
    </result>
    <result_code>200</result_code>
    <is_success>true</is_success>
</yunos_admarket_ad_bid_response>

{
    "yunos_admarket_ad_bid_response":{
        "id":"12313132123123",
        "result_msg":"操作成功",
        "result":{
            "ad_slots":{
                "ad_slots":[
                    {
                        "ad_slot_id":"INVENO_ADZONE_252",
                        "ads":{
                            "ad":[
                                {
                                    "template_id":"252",
                                    "price":0,
                                    "adm":"\"{}\"",
                                    "target":{
                                        "target_type":"BROWSER",
                                        "target_value":"http:\/\/www.baidu.com"
                                    },
                                    "monitor":{
                                        "view_url_list":{
                                            "string":[
                                                "[\"\"]"
                                            ]
                                        },
                                        "end_play_url_list":{
                                            "string":[
                                                "[\"\"]"
                                            ]
                                        },
                                        "start_play_url_list":{
                                            "string":[
                                                "[\"\"]"
                                            ]
                                        },
                                        "click_url_list":{
                                            "string":[
                                                "[\"\"]"
                                            ]
                                        },
                                        "event_url_list":{
                                            "string":[
                                                "[\"\"]"
                                            ]
                                        }
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "result_code":"200",
        "is_success":true
    }
}

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下载

开放平台

ALIOS广告平台

yunos.admarket.ad.bid (广告竞价服务)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ