淘宝开放平台 - 文档中心

请求地址：

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

名称	类型	是否必须	示例值	描述
user_id	Number	可选	1753244513	用户淘宝id
city_code	Number	必须	330100	城市编码
show_id	Number	可选	10001	影片id
activity_id	Number	可选	10001	活动id，仅预售码兑换需要传这个参数
longitude	String	可选	116.43	用户所在位置经度
latitude	String	可选	23.34	用户所在位置纬度
platform	Number	必须	2	渠道所分配平台码，各渠道根据自己分配的填写
page_index	Number	可选	1	传筛选参数时必传,从1开始。
page_size	Number	可选	10	传筛选参数时必传。需要>0
field_exclude_or_include	String	可选	无	不需要传
params	Json	必须	无	扩展参数，key可以传"regionName","showDate","showTime","support"

名称	类型	示例值	描述
result	MtopCinemaListResult	无	返回结果
return_value MtopCinemaList 无返回值 mtop_cinemas MtopCinema [] 无影院列表 └ id Number 123 影院淘宝id └ address String 杭州市西湖区影院地址 └ cinema_name String 翠苑电影大世界影院名称 └ region_name String 西湖区区域名称 └ longitude String 126.56 经度 └ latitude String 26.56 纬度 └ distance String 1.6 影院和用户距离 └ schedule_close_time Number 40 影院排期开始前多久停止售票 activities MtopActivity [] 无影院活动信息 └ id Number 1234 活动id └ ori_activity_id Number 123 活动原始id └ activity_type String REDUCE 活动类型 └ activity_price Number 500 活动优惠价格, 单位分 └ promotion_price Number 3500 影院排期的活动最优价格, 单位分 └ activity_ext_type Number 4 活动外部类型: FCODE(1, "预售"), HUIJIN(2, "实时扣减"), COUPON(3, "代金券"), SALES(4, "卖品"), TUAN(5, "团购") └ activity_tag String 优惠购票活动标 └ support_dates Number [] 1460563200 支持的日期，精确到秒 └ is_activity_visible Boolean true 活动是否可见 └ available_schedule_count Number 123 影院排期数 └ available_today_schedule_count Number 12 影院今天排期数 └ special_flag Number 12 支持特色 └ support_f_lag Number 3 影院特殊表,如支持在线选座等。 shows Show [] 无影片列表 schedules Schedule [] 无排期列表 └ id Number 123 排期id └ show_time Date 2016-04-06 12:00:00 排期开始时间 └ show_version String 国语 3D 影片版本 └ hall_name String 9号厅厅名称 └ service_fee Number 100 服务费，单位为分 └ partner_code String wanda 合作商名称 partners Partner [] 无排期信息 activities Activity [] 无活动信息 └ id Number 123 活动id └ ori_activity_id Number 123 活动原始id └ activity_tag String 优惠购票活动标 └ activity_price Number 800 活动优惠价格，单位分 └ activity_type String REDUCE 活动类型，如立减 └ display_price Number 5100 活动展示价格, 单位分 └ max_can_buy Number 4 最多可购票数 └ partner_max_can_buy Number 4 系统商最多可购票数 └ ext_id String 2382783722 外部排期id └ price Number 1230 价格，单位分 └ trade_price String 1230 交易价格，单位分 └ flag Number 4 排期特性 └ date_show_time_map String 无影片在各个日期展示的排期时间 special_schedules SpecialSchedule [] 无特殊场次 └ title String 明星见面会特殊场次标题 └ long_tile String 明星见面会特殊场次长标题 └ tag String 明星见面会特殊场次标 └ description String 明星见面会特殊场次描述 └ support_dates Number [] 1460563200 支持的日期，精确到秒 └ always_g_o Boolean false 是否是常去影院 └ no_show_display_price Number 4500 没有showId入参时展示的价格，单位分 └ support_dates Number [] 1460563200 支持的日期,精确到秒 └ display_prices String 无有showId入参时每天展示的价格 └ show_mark String 巨幕厅影院厅类型 └ cinema_photo String https://gw.alicdn.com/tfscom/i3/TB1hGUBjiMnBKNjSZFCXXX0KFXa_.jpg 影院图片 └ total_count Number 123 影院总数, 分页时使用 cinema_filter CinemaFilter 无影院筛选参数 └ region_names String [] 西湖区该次请求返回的影院区域集合 └ time_maps String [] key:00:00-09:00value:9点之前该次请求返回的排期时间集合 └ supports String [] key:1 value:停车该次请求返回的影院特色信息集合 └ support_dates Number [] 14678900000 该次请求返回的支持日期集合 └ region_name String 西湖区该次请求筛选区域名称 └ time String 12:00-13:00 该次请求筛选时间 └ choose_date Number 14678900000 该次请求筛选日期 └ support Number 123 该次请求筛选特色 └ pre_schedule_dates String [] 1456789032 点映时间 └ return_code String 0 结果码,0为成功 └ return_message String 系统异常错误信息

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
FilmCinemalistGetRequest req = new FilmCinemalistGetRequest();
req.setUserId(1753244513L);
req.setCityCode(330100L);
req.setShowId(10001L);
req.setActivityId(10001L);
req.setLongitude("116.43");
req.setLatitude("23.34");
req.setPlatform(2L);
req.setPageIndex(1L);
req.setPageSize(10L);
req.setFieldExcludeOrInclude("无");
req.setParamsString("无");
FilmCinemalistGetResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
FilmCinemalistGetRequest req = new FilmCinemalistGetRequest();
req.UserId = 1753244513L;
req.CityCode = 330100L;
req.ShowId = 10001L;
req.ActivityId = 10001L;
req.Longitude = "116.43";
req.Latitude = "23.34";
req.Platform = 2L;
req.PageIndex = 1L;
req.PageSize = 10L;
req.FieldExcludeOrInclude = "无";
req.Params = "无";
FilmCinemalistGetResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new FilmCinemalistGetRequest;
$req->setUserId("1753244513");
$req->setCityCode("330100");
$req->setShowId("10001");
$req->setActivityId("10001");
$req->setLongitude("116.43");
$req->setLatitude("23.34");
$req->setPlatform("2");
$req->setPageIndex("1");
$req->setPageSize("10");
$req->setFieldExcludeOrInclude("无");
$req->setParams("无");
$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.film.cinemalist.get' \
-d 'partner_id=apidoc' \
-d 'sign=3CA9B6A92AAB2DAF339EE9BBDD3F8FFD' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-05-08+05%3A17%3A06' \
-d 'v=2.0' \
-d 'activity_id=10001' \
-d 'city_code=330100' \
-d 'field_exclude_or_include=%E6%97%A0' \
-d 'latitude=23.34' \
-d 'longitude=116.43' \
-d 'page_index=1' \
-d 'page_size=10' \
-d 'params=%E6%97%A0' \
-d 'platform=2' \
-d 'show_id=10001' \
-d 'user_id=1753244513'

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

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

req.user_id=1753244513
req.city_code=330100
req.show_id=10001
req.activity_id=10001
req.longitude="116.43"
req.latitude="23.34"
req.platform=2
req.page_index=1
req.page_size=10
req.field_exclude_or_include="无"
req.params="无"
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.film.cinemalist.get");
add_param(pRequest,"user_id","1753244513");
add_param(pRequest,"city_code","330100");
add_param(pRequest,"show_id","10001");
add_param(pRequest,"activity_id","10001");
add_param(pRequest,"longitude","116.43");
add_param(pRequest,"latitude","23.34");
add_param(pRequest,"platform","2");
add_param(pRequest,"page_index","1");
add_param(pRequest,"page_size","10");
add_param(pRequest,"field_exclude_or_include","无");
add_param(pRequest,"params","无");
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.film.cinemalist.get', {
	'user_id':'1753244513',
	'city_code':'330100',
	'show_id':'10001',
	'activity_id':'10001',
	'longitude':'116.43',
	'latitude':'23.34',
	'platform':'2',
	'page_index':'1',
	'page_size':'10',
	'field_exclude_or_include':'无',
	'params':'无'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<film_cinemalist_get_response>
    <result>
        <return_value>
            <mtop_cinemas>
                <mtop_cinema>
                    <id>123</id>
                    <address>杭州市西湖区</address>
                    <cinema_name>翠苑电影大世界</cinema_name>
                    <region_name>西湖区</region_name>
                    <longitude>126.56</longitude>
                    <latitude>26.56</latitude>
                    <distance>1.6</distance>
                    <schedule_close_time>40</schedule_close_time>
                    <activities>
                        <mtop_activity>
                            <id>1234</id>
                            <ori_activity_id>123</ori_activity_id>
                            <activity_type>REDUCE</activity_type>
                            <activity_price>500</activity_price>
                            <promotion_price>3500</promotion_price>
                            <activity_ext_type>4</activity_ext_type>
                            <activity_tag>优惠购票</activity_tag>
                            <support_dates>
                                <number>1460563200</number>
                            </support_dates>
                            <is_activity_visible>true</is_activity_visible>
                        </mtop_activity>
                    </activities>
                    <available_schedule_count>123</available_schedule_count>
                    <available_today_schedule_count>12</available_today_schedule_count>
                    <special_flag>12</special_flag>
                    <support_f_lag>3</support_f_lag>
                    <shows>
                        <show>
                            <schedules>
                                <schedule>
                                    <id>123</id>
                                    <show_time>2016-04-06 12:00:00</show_time>
                                    <show_version>国语 3D</show_version>
                                    <hall_name>9号厅</hall_name>
                                    <service_fee>100</service_fee>
                                    <partner_code>wanda</partner_code>
                                    <partners>
                                        <partner>
                                            <activities>
                                                <activity>
                                                    <id>123</id>
                                                    <ori_activity_id>123</ori_activity_id>
                                                    <activity_tag>优惠购票</activity_tag>
                                                    <activity_price>800</activity_price>
                                                    <activity_type>REDUCE</activity_type>
                                                </activity>
                                            </activities>
                                            <display_price>5100</display_price>
                                            <max_can_buy>4</max_can_buy>
                                            <partner_max_can_buy>4</partner_max_can_buy>
                                            <ext_id>2382783722</ext_id>
                                            <price>1230</price>
                                            <trade_price>1230</trade_price>
                                        </partner>
                                    </partners>
                                    <flag>4</flag>
                                </schedule>
                            </schedules>
                            <date_show_time_map>无</date_show_time_map>
                        </show>
                    </shows>
                    <special_schedules>
                        <special_schedule>
                            <title>明星见面会</title>
                            <long_tile>明星见面会</long_tile>
                            <tag>明星见面会</tag>
                            <description>明星见面会</description>
                            <support_dates>
                                <number>1460563200</number>
                            </support_dates>
                        </special_schedule>
                    </special_schedules>
                    <always_g_o>false</always_g_o>
                    <no_show_display_price>4500</no_show_display_price>
                    <support_dates>
                        <number>1460563200</number>
                    </support_dates>
                    <display_prices>无</display_prices>
                    <show_mark>巨幕厅</show_mark>
                    <cinema_photo>https://gw.alicdn.com/tfscom/i3/TB1hGUBjiMnBKNjSZFCXXX0KFXa_.jpg</cinema_photo>
                </mtop_cinema>
            </mtop_cinemas>
            <total_count>123</total_count>
            <cinema_filter>
                <region_names>
                    <string>西湖区</string>
                </region_names>
                <time_maps>
                    <string>key:00:00-09:00value:9点之前</string>
                </time_maps>
                <supports>
                    <string>key:1 value:停车</string>
                </supports>
                <support_dates>
                    <number>14678900000</number>
                </support_dates>
                <region_name>西湖区</region_name>
                <time>12:00-13:00</time>
                <choose_date>14678900000</choose_date>
                <support>123</support>
            </cinema_filter>
            <pre_schedule_dates>
                <string>1456789032</string>
            </pre_schedule_dates>
        </return_value>
        <return_code>0</return_code>
        <return_message>系统异常</return_message>
    </result>
</film_cinemalist_get_response>

{
    "film_cinemalist_get_response":{
        "result":{
            "return_value":{
                "mtop_cinemas":{
                    "mtop_cinema":[
                        {
                            "id":123,
                            "address":"杭州市西湖区",
                            "cinema_name":"翠苑电影大世界",
                            "region_name":"西湖区",
                            "longitude":"126.56",
                            "latitude":"26.56",
                            "distance":"1.6",
                            "schedule_close_time":40,
                            "activities":{
                                "mtop_activity":[
                                    {
                                        "id":1234,
                                        "ori_activity_id":123,
                                        "activity_type":"REDUCE",
                                        "activity_price":500,
                                        "promotion_price":3500,
                                        "activity_ext_type":4,
                                        "activity_tag":"优惠购票",
                                        "support_dates":{
                                            "number":[
                                                1460563200
                                            ]
                                        },
                                        "is_activity_visible":true
                                    }
                                ]
                            },
                            "available_schedule_count":123,
                            "available_today_schedule_count":12,
                            "special_flag":12,
                            "support_f_lag":3,
                            "shows":{
                                "show":[
                                    {
                                        "schedules":{
                                            "schedule":[
                                                {
                                                    "id":123,
                                                    "show_time":"2016-04-06 12:00:00",
                                                    "show_version":"国语 3D",
                                                    "hall_name":"9号厅",
                                                    "service_fee":100,
                                                    "partner_code":"wanda",
                                                    "partners":{
                                                        "partner":[
                                                            {
                                                                "activities":{
                                                                    "activity":[
                                                                        {
                                                                            "id":123,
                                                                            "ori_activity_id":123,
                                                                            "activity_tag":"优惠购票",
                                                                            "activity_price":800,
                                                                            "activity_type":"REDUCE"
                                                                        }
                                                                    ]
                                                                },
                                                                "display_price":5100,
                                                                "max_can_buy":4,
                                                                "partner_max_can_buy":4,
                                                                "ext_id":"2382783722",
                                                                "price":1230,
                                                                "trade_price":"1230"
                                                            }
                                                        ]
                                                    },
                                                    "flag":4
                                                }
                                            ]
                                        },
                                        "date_show_time_map":"无"
                                    }
                                ]
                            },
                            "special_schedules":{
                                "special_schedule":[
                                    {
                                        "title":"明星见面会",
                                        "long_tile":"明星见面会",
                                        "tag":"明星见面会",
                                        "description":"明星见面会",
                                        "support_dates":{
                                            "number":[
                                                1460563200
                                            ]
                                        }
                                    }
                                ]
                            },
                            "always_g_o":false,
                            "no_show_display_price":4500,
                            "support_dates":{
                                "number":[
                                    1460563200
                                ]
                            },
                            "display_prices":"无",
                            "show_mark":"巨幕厅",
                            "cinema_photo":"https:\/\/gw.alicdn.com\/tfscom\/i3\/TB1hGUBjiMnBKNjSZFCXXX0KFXa_.jpg"
                        }
                    ]
                },
                "total_count":123,
                "cinema_filter":{
                    "region_names":{
                        "string":[
                            "西湖区"
                        ]
                    },
                    "time_maps":{
                        "string":[
                            "key:00:00-09:00value:9点之前"
                        ]
                    },
                    "supports":{
                        "string":[
                            "key:1 value:停车"
                        ]
                    },
                    "support_dates":{
                        "number":[
                            14678900000
                        ]
                    },
                    "region_name":"西湖区",
                    "time":"12:00-13:00",
                    "choose_date":14678900000,
                    "support":123
                },
                "pre_schedule_dates":{
                    "string":[
                        "1456789032"
                    ]
                }
            },
            "return_code":"0",
            "return_message":"系统异常"
        }
    }
}

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

开放平台

电影票API

taobao.film.cinemalist.get (淘宝电影影院列表接口)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ