淘宝开放平台 - 文档中心

请求地址：

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

名称	类型	是否必须	示例值	更多限制	描述
dep_city_code	String	必须	BJS	最大长度：3	出发城市三字码
arr_city_code	String	必须	CTU	最大长度：3	到达城市三字码
dep_date	String	必须	2010-11-16	最大长度：10	航班日期：格式要求 "yyyy-MM-dd"
search_type	String	可选	outbound	默认值：outbound 最大长度：10	搜索类型：支持三个类型，1. outbound，表示搜索航段最低价，每个航班一个最低价；2. lowprice，表示搜索指定航班topN最低价；3. gaoduan，表示搜索指定航班下高端大气上档次价格列表
flight_no	String	可选	CZ1234	最大长度：7	指定航班号：获取指定航班低价舱位列表或者获取指定航班高大上舱位折扣使用
cabin_class	Number	可选	0	最小值：0 最大值：6	舱位等级，0，默认-全部；1，经济舱；2，商务舱；3，头等舱；4，头等和商务舱；5，经济和商务舱；6，经济和头等舱
passenger_num	Number	可选	1	默认值：-1 最小值：-1 最大值：9	1-9分别表示乘机人数为1-9；乘机人数小于0即相当无限制，默认值-1
supply_itinerary	Number	可选	0	默认值：0 最小值：0	是否提供报销凭证(行程单),0.不提供和提供报销凭证的都查询出来,1.只查询提供报销凭证的
pid	String	可选	mm_28481856_5432317_16246646		淘宝推广者pid

名称	类型	示例值	描述
result	AtNSearchResult		AtNSearchResult
└ city_info_map String {"SHA":"上海","BJS":"北京"} json格式字符串：描述出发/到达城市基本信息 └ airport_info_map String {"SHA":"虹桥机场","PEK":"首都机场","PVG":"浦东机场","NAY":"南苑机场"} JSON串，描述机场三字码和中文名称的对应关系 └ airline_info_map String {"MU":"东方航空"} JSON串，描述航空公司二字码与中文名称的关系 └ flight_type_info_map String {"small":[],"middle":["738"],"large":["321","330","332","333","340"]} json格式字符串：描述当前搜索结果中航班机型信息， small表示小型机；middle表示中型机；large表示大型机 └ agent_info_map String {"6309":{"id":6309,"wangwang":"tworkb20039","rate":{"flight":77853874,"sellerId":2049514023,"score":0,"feed":16},"nick":"tworkb20039","normalProdcutScore":5.3,"name":"t39兰铃专用","supplyType":2} json格式字符串：描述代理商的基本信息结构；注意：仅在指定航班号查询的时候有输出。得分项可能有三个Key（不一定全部输出）: normalProdcutScore,specialProductScore,speedIssueProductScore，分别表示普通产品得分，特殊产品（申请票）得分，极速出票产品得分。 supplyType: 1 ：航空公司代理商， 2：普通机票代理商 └ flight_info_map String 示例值请看描述 JSON串，表示航班具体信息,key为出发+达到+航班号，如："BJSSHAMU5162"。示例值：{“BJSSHAMU5102":{"depTime":1403178600000,"flightType":"333","depAirportCode":"PEK","fees":5000,"depTerm":"T2","flight":"MU5102","stops":0,"airlineCode":"MU","meals":1,"arrTerm":"T2","arrTime":1403178600000,"carrier":"","arrAirportCode":"SHA","taxes":14000}} └ cabin_info_map String {"MU-R":{"cabinClass":2,"cabin":"R","name":"经济舱","airline":"MU"},"MU-Y":{"cabinClass":2,"cabin":"Y","name":"经济舱","airline":"MU"}} JSON串，描述舱位信息，key：航司+舱位代码，如“CA-Y” items AtNSearchItemVO [] 机票商品列表 └ agent_id Number 1426 代理人编号 └ price Price 1333 销售价格，单位分 └ support_insure_promotion Boolean true 是否支持保险分润 └ trip_type Number 1 航程类型，0单程，1往返 └ item_type Number 1 商品结果类型，0普通单程，1组合往返；2打包往返；3往返直减 segments AtNSearchSegmentVO [] 商品航段数据信息 └ dep_city String BJS 出发城市三字码 └ arr_city String SHA 到达城市三字码 └ fare_type Number 0 运价类型。0-公布运价；1-折扣运价；2-B2B/卖家接口政策；3-航司外部产品 └ price Price 333 销售价格，单位分。 └ stock_type Number 1 库存类型，0-共有库存；1-私有库存；2-可申请库存 └ segment_number String 00 航段标识。00-去程第一段；01-去程第二段；10-回程第一段；11-回程第二段。 └ cabin String Y 舱位代码 └ cabin_class Number 0 舱位等级。0-头等舱；1-商务舱；2-经济舱 └ cabin_num String A 舱位座位数，123456789AQSCL等。 └ invoice_type Number 1 发票提供类型。1-提供（等额行程单）；2-不提供；5-提供（等额行程单+发票）；6-提供（等额发票） └ basic_cabin_price Price 100 基准舱位（FCY）价格，单位分 └ ticket_price Price 1200 产品票面价，单位分 └ auto_book Boolean true 是否自动出票。 └ flag Number 0 产品打标，2的N次方标记。 └ flight_no String CA1710 航班号 └ activity_id Number 1001 活动编号 └ activity_bonus Price 20 活动优惠金额,单位分。 └ force_insure_price Price 2000 强制保险金额，单位分。 └ force_insure Boolean true 是否为强制保险 └ basic_cabin_price Price 113000 基准舱位价格，单位分，往返是来回程各段的基准价格之和。 └ ticket_price Price 10000 产品票面价，单位分。往返是来回程各段票面价之和 └ is_qijian Boolean true 是否是旗舰店商品。 └ attributes String {"sit":true} JSON串，保存商品扩展信息，相关Key:site(描述是否是极速出票)，I_A_K_P_T_L_U（PC淘客搜索URL），I_A_K_H_T_L_U（H5淘客搜索URL），I_A_K_P_T_D_U（PC淘客下单页URL），I_A_K_H_T_D_U（H5淘客下单页URL）,I_A_K_T_G_Q_01（去程退改签），I_A_K_T_G_Q_10（回程退改签） └ activity_bonus Price 100 活动优惠金额 └ insure_price Price 1100 获取保险分润后的价格，不包含活动。不支持分润时返回0 └ force_insure Boolean true 是否强制保险 └ force_insure_price Price 2000 强制保险金额，单位分。(值为每一Segment强制保险金额的总和) └ activity_map_json String {"1200": {"id": 1200,"type": 0,"activityDesc":"\u5c71\u822a612\u5927\u4fc3\u75af\u72c2\u62a2","actIcon":"http://img01.taobaocdn.com/tfscom/T16da1XsxeXXXXXXXX.png"}} json串，描述活动信息。type：1普通直减、2后返、3多人同行 └ insure_promotion_info_map_json String {"insurePrice":20,"insureAdultPrice":15,"insureChildPrice":0,"insure9cPrice":20} 保险分润扣钱规则说明（单位元）。{"insurePrice":20,//保险总价格 "insureAdultPrice":15,//保险成人分润价格 "insureChildPrice":0,//保险儿童分润价格 "insure9cPrice":20//春秋航空保险分润金额 }

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
TripJipiaoNsearchOwSearchRequest req = new TripJipiaoNsearchOwSearchRequest();
req.setDepCityCode("BJS");
req.setArrCityCode("CTU");
req.setDepDate("2010-11-16");
req.setSearchType("outbound");
req.setFlightNo("CZ1234");
req.setCabinClass(0L);
req.setPassengerNum(1L);
req.setSupplyItinerary(0L);
req.setPid("mm_28481856_5432317_16246646");
TripJipiaoNsearchOwSearchResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
TripJipiaoNsearchOwSearchRequest req = new TripJipiaoNsearchOwSearchRequest();
req.DepCityCode = "BJS";
req.ArrCityCode = "CTU";
req.DepDate = "2010-11-16";
req.SearchType = "outbound";
req.FlightNo = "CZ1234";
req.CabinClass = 0L;
req.PassengerNum = 1L;
req.SupplyItinerary = 0L;
req.Pid = "mm_28481856_5432317_16246646";
TripJipiaoNsearchOwSearchResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new TripJipiaoNsearchOwSearchRequest;
$req->setDepCityCode("BJS");
$req->setArrCityCode("CTU");
$req->setDepDate("2010-11-16");
$req->setSearchType("outbound");
$req->setFlightNo("CZ1234");
$req->setCabinClass("0");
$req->setPassengerNum("1");
$req->setSupplyItinerary("0");
$req->setPid("mm_28481856_5432317_16246646");
$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=taobao.trip.jipiao.nsearch.ow.search' \
-d 'partner_id=apidoc' \
-d 'sign=29346DB5D5D0683A76F99195E558459A' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-04-26+09%3A04%3A18' \
-d 'v=2.0' \
-d 'arr_city_code=CTU' \
-d 'cabin_class=0' \
-d 'dep_city_code=BJS' \
-d 'dep_date=2010-11-16' \
-d 'flight_no=CZ1234' \
-d 'passenger_num=1' \
-d 'pid=mm_28481856_5432317_16246646' \
-d 'search_type=outbound' \
-d 'supply_itinerary=0'

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

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

req.dep_city_code="BJS"
req.arr_city_code="CTU"
req.dep_date="2010-11-16"
req.search_type="outbound"
req.flight_no="CZ1234"
req.cabin_class=0
req.passenger_num=1
req.supply_itinerary=0
req.pid="mm_28481856_5432317_16246646"
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,"taobao.trip.jipiao.nsearch.ow.search");
add_param(pRequest,"dep_city_code","BJS");
add_param(pRequest,"arr_city_code","CTU");
add_param(pRequest,"dep_date","2010-11-16");
add_param(pRequest,"search_type","outbound");
add_param(pRequest,"flight_no","CZ1234");
add_param(pRequest,"cabin_class","0");
add_param(pRequest,"passenger_num","1");
add_param(pRequest,"supply_itinerary","0");
add_param(pRequest,"pid","mm_28481856_5432317_16246646");
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('taobao.trip.jipiao.nsearch.ow.search', {
	'dep_city_code':'BJS',
	'arr_city_code':'CTU',
	'dep_date':'2010-11-16',
	'search_type':'outbound',
	'flight_no':'CZ1234',
	'cabin_class':'0',
	'passenger_num':'1',
	'supply_itinerary':'0',
	'pid':'mm_28481856_5432317_16246646'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<trip_jipiao_nsearch_ow_search_response>
    <result>
        <city_info_map>{&quot;SHA&quot;:&quot;上海&quot;,&quot;BJS&quot;:&quot;北京&quot;}</city_info_map>
        <airport_info_map>{&quot;SHA&quot;:&quot;虹桥机场&quot;,&quot;PEK&quot;:&quot;首都机场&quot;,&quot;PVG&quot;:&quot;浦东机场&quot;,&quot;NAY&quot;:&quot;南苑机场&quot;}</airport_info_map>
        <airline_info_map>{&quot;MU&quot;:&quot;东方航空&quot;}</airline_info_map>
        <flight_type_info_map>{&quot;small&quot;:[],&quot;middle&quot;:[&quot;738&quot;],&quot;large&quot;:[&quot;321&quot;,&quot;330&quot;,&quot;332&quot;,&quot;333&quot;,&quot;340&quot;]}</flight_type_info_map>
        <agent_info_map>{&quot;6309&quot;:{&quot;id&quot;:6309,&quot;wangwang&quot;:&quot;tworkb20039&quot;,&quot;rate&quot;:{&quot;flight&quot;:77853874,&quot;sellerId&quot;:2049514023,&quot;score&quot;:0,&quot;feed&quot;:16},&quot;nick&quot;:&quot;tworkb20039&quot;,&quot;normalProdcutScore&quot;:5.3,&quot;name&quot;:&quot;t39兰铃专用&quot;,&quot;supplyType&quot;:2}</agent_info_map>
        <flight_info_map>示例值请看描述</flight_info_map>
        <cabin_info_map>{&quot;MU-R&quot;:{&quot;cabinClass&quot;:2,&quot;cabin&quot;:&quot;R&quot;,&quot;name&quot;:&quot;经济舱&quot;,&quot;airline&quot;:&quot;MU&quot;},&quot;MU-Y&quot;:{&quot;cabinClass&quot;:2,&quot;cabin&quot;:&quot;Y&quot;,&quot;name&quot;:&quot;经济舱&quot;,&quot;airline&quot;:&quot;MU&quot;}}</cabin_info_map>
        <items>
            <at_n_search_item_v_o>
                <agent_id>1426</agent_id>
                <price>1333</price>
                <support_insure_promotion>true</support_insure_promotion>
                <trip_type>1</trip_type>
                <item_type>1</item_type>
                <segments>
                    <at_n_search_segment_v_o>
                        <dep_city>BJS</dep_city>
                        <arr_city>SHA</arr_city>
                        <fare_type>0</fare_type>
                        <price>333</price>
                        <stock_type>1</stock_type>
                        <segment_number>00</segment_number>
                        <cabin>Y</cabin>
                        <cabin_class>0</cabin_class>
                        <cabin_num>A</cabin_num>
                        <invoice_type>1</invoice_type>
                        <basic_cabin_price>100</basic_cabin_price>
                        <ticket_price>1200</ticket_price>
                        <auto_book>true</auto_book>
                        <flag>0</flag>
                        <flight_no>CA1710</flight_no>
                        <activity_id>1001</activity_id>
                        <activity_bonus>20</activity_bonus>
                        <force_insure_price>2000</force_insure_price>
                        <force_insure>true</force_insure>
                    </at_n_search_segment_v_o>
                </segments>
                <basic_cabin_price>113000</basic_cabin_price>
                <ticket_price>10000</ticket_price>
                <is_qijian>true</is_qijian>
                <attributes>{&quot;sit&quot;:true}</attributes>
                <activity_bonus>100</activity_bonus>
                <insure_price>1100</insure_price>
                <force_insure>true</force_insure>
                <force_insure_price>2000</force_insure_price>
            </at_n_search_item_v_o>
        </items>
        <activity_map_json>{&quot;1200&quot;: {&quot;id&quot;: 1200,&quot;type&quot;: 0,&quot;activityDesc&quot;:&quot;\u5c71\u822a612\u5927\u4fc3\u75af\u72c2\u62a2&quot;,&quot;actIcon&quot;:&quot;http://img01.taobaocdn.com/tfscom/T16da1XsxeXXXXXXXX.png&quot;}}</activity_map_json>
        <insure_promotion_info_map_json>{&quot;insurePrice&quot;:20,&quot;insureAdultPrice&quot;:15,&quot;insureChildPrice&quot;:0,&quot;insure9cPrice&quot;:20}</insure_promotion_info_map_json>
    </result>
</trip_jipiao_nsearch_ow_search_response>

{
    "trip_jipiao_nsearch_ow_search_response":{
        "result":{
            "city_info_map":"{\"SHA\":\"上海\",\"BJS\":\"北京\"}",
            "airport_info_map":"{\"SHA\":\"虹桥机场\",\"PEK\":\"首都机场\",\"PVG\":\"浦东机场\",\"NAY\":\"南苑机场\"}",
            "airline_info_map":"{\"MU\":\"东方航空\"}",
            "flight_type_info_map":"{\"small\":[],\"middle\":[\"738\"],\"large\":[\"321\",\"330\",\"332\",\"333\",\"340\"]}",
            "agent_info_map":"{\"6309\":{\"id\":6309,\"wangwang\":\"tworkb20039\",\"rate\":{\"flight\":77853874,\"sellerId\":2049514023,\"score\":0,\"feed\":16},\"nick\":\"tworkb20039\",\"normalProdcutScore\":5.3,\"name\":\"t39兰铃专用\",\"supplyType\":2}",
            "flight_info_map":"示例值请看描述",
            "cabin_info_map":"{\"MU-R\":{\"cabinClass\":2,\"cabin\":\"R\",\"name\":\"经济舱\",\"airline\":\"MU\"},\"MU-Y\":{\"cabinClass\":2,\"cabin\":\"Y\",\"name\":\"经济舱\",\"airline\":\"MU\"}}",
            "items":{
                "at_n_search_item_v_o":[
                    {
                        "agent_id":1426,
                        "price":"1333",
                        "support_insure_promotion":true,
                        "trip_type":1,
                        "item_type":1,
                        "segments":{
                            "at_n_search_segment_v_o":[
                                {
                                    "dep_city":"BJS",
                                    "arr_city":"SHA",
                                    "fare_type":0,
                                    "price":"333",
                                    "stock_type":1,
                                    "segment_number":"00",
                                    "cabin":"Y",
                                    "cabin_class":0,
                                    "cabin_num":"A",
                                    "invoice_type":1,
                                    "basic_cabin_price":"100",
                                    "ticket_price":"1200",
                                    "auto_book":true,
                                    "flag":0,
                                    "flight_no":"CA1710",
                                    "activity_id":1001,
                                    "activity_bonus":"20",
                                    "force_insure_price":"2000",
                                    "force_insure":true
                                }
                            ]
                        },
                        "basic_cabin_price":"113000",
                        "ticket_price":"10000",
                        "is_qijian":true,
                        "attributes":"{\"sit\":true}",
                        "activity_bonus":"100",
                        "insure_price":"1100",
                        "force_insure":true,
                        "force_insure_price":"2000"
                    }
                ]
            },
            "activity_map_json":"{\"1200\": {\"id\": 1200,\"type\": 0,\"activityDesc\":\"\\u5c71\\u822a612\\u5927\\u4fc3\\u75af\\u72c2\\u62a2\",\"actIcon\":\"http:\/\/img01.taobaocdn.com\/tfscom\/T16da1XsxeXXXXXXXX.png\"}}",
            "insure_promotion_info_map_json":"{\"insurePrice\":20,\"insureAdultPrice\":15,\"insureChildPrice\":0,\"insure9cPrice\":20}"
        }
    }
}

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"
	}
}

错误码	错误描述	解决方案
isv.remote-service-error	参数不正确+错误参数信息	向运营咨询
isv.remote-service-error:USER_AUTH_FAIL	error:USER_AUTH_FAIL 访问权限不够，Appkey未授权	向运营咨询处理方案

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

开放平台

国内机票导购搜索API

taobao.trip.jipiao.nsearch.ow.search (国内机票搜索)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ