nn200433/12306-rest-api

12306接口协议分析，构建Rest火车票购票服务

1.项目简介

本项目旨在分析12306接口协议，构建一个简单易用的Rest API风格的火车票订票服务。 为火车票抢购软件提供强有力的后台支撑。

详细原理分析和代码讲解

注：maven项目请使用gradle转换出来的pom.xml 注：swagger地址：http://localhost:8080/doc.html

2.接口公共协议

协议说明

• 接口采用HTTP的POST方式请求。
• 输入和输出参数都采用UTF-8编码。
• 出入参数均为json格式

参数描述

公共请求参数

节点	名称	类型	可为空	说明
---	---	---	---	---

公共响应参数

节点	名称	类型	可为空	说明
Code	结果代码	String	N	0表示请求成功返回；非0表示存在业务异常。业务异常详见错误码
Message	错误描述	String	Y	Code非零时有值，表示错误描述
Result	结果数据	Object	Y	不同的请求返回的不同结果。

3.火车票业务协议

`### 3.1 获取所有/热点车站信息

方法名称

• train/getAllCity
• train/getHotCity

使用说明

• train/getAllCity获取所有的火车站信息，建议每天拉取一次保存到本地，以免影响性能。
• train/getHotCity获取热点火车站信息，建议每天拉取一次保存到本地，以免影响性能。

请求参数

无

响应参数

节点	名称	类型	可为空	说明
Stations	火车站列表	Station[]	N

Station

节点	名称	类型	可为空	说明
Name	站点名	String	N
StationCode	车站代码	String	N
pingYin	车站拼音	String	N
PingYinShort	车站简拼	String	N

3.2 关键字搜索车站

使用说明

方法名称

• train/searchCity

使用说明

• 使用关键字搜索匹配到的车站

请求参数

节点	名称	类型	可为空	说明
Keyword	关键字	String	N

响应参数

节点	名称	类型	可为空	说明
Stations	火车站列表	Station[]	N

Station

节点	名称	类型	可为空	说明
Name	站点名	String	N
StationCode	车站代码	String	N
pingYin	车站拼音	String	N
PingYinShort	车站简拼	String	N

3.3 火车票查询

使用说明

方法名称

• train/getTicketList

使用说明

• 查询火车票列表

请求参数

节点	名称	类型	可为空	说明
FromStationCode	出发站点代码	String	N
ToStationCode	到达站点代码	String	N
FromDate	出发日期（格式：yyyy-mm-dd）	String	N
IsStudent	是否是学生票(默认成人票)	Boolean	N

响应参数

节点	名称	类型	可为空	说明
Tickets	车票信息列表	Ticket[]	N

Ticket

节点	名称	类型	可为空	说明
TrainNo	列车号	String	N
TrainCode	车次代码	String	N
TrainType	车次类型	String	N
FromStation	出发站点名字	String	N
ToStation	到达站点名字	String	N
FromStationType	出发站点类型名 "始-终-过"类型	String	N
ToStationType	到达站点类型名 "始-终-过"类型	String	N
FromTime	出发时间	String	N
ToTime	到达时间	String	N
RunTime	运行时间	String	N
CanBook	该车次是否有余票可以预定，所有席别无票则为false	Boolean	N
SwzNum	商务座/特等座剩余票数	String	N	（有）表示充足 （--）表示无此类型的座位 数字表示剩余座位数 下同
SwzPrice	商务座/特等座价格	BigDecimal	N
YdzNum	一等座剩余票数	String	N
YdzPrice	一等座价格	BigDecimal	N
EdzNum	二等座剩余票数	String	N
EdzPrice	二等座价格	BigDecimal	N
GjrwNum	高级软卧剩余票数	String	N
GjrwPrice	高级软卧价格	BigDecimal	N
RwNum	软卧/一等卧价格	String	N
RwPrice	软卧/一等卧剩余票数	BigDecimal	N
DwNum	动卧剩余票数	String	N
DwPrice	动卧价格	BigDecimal	N
YwNum	硬卧剩余票数	String	N
YwPrice	硬卧价格	BigDecimal	N
RzNum	软座剩余票数	String	N
RzPrice	软座价格	BigDecimal	N
YzNum	硬座剩余票数	String	N
YzPrice	硬座价格	BigDecimal	N
WzNum	无座剩余票数	String	N
WzPrice	无座价格	BigDecimal	N
QtNum	其他剩余票数	String	N
QtPrice	其他价格	BigDecimal	N

3.4 查询车次经停信息

使用说明

方法名称

• train/getTrainLine

使用说明

• 查询车次经停信息

请求参数

节点	名称	类型	可为空	说明
TrainCode	车次代码	String	N
FromStationCode	出发站点代码	String	N
ToStationCode	到达站点代码	String	N
FromDate	出发日期（格式：yyyy-mm-dd）	String	N

响应参数

节点	名称	类型	可为空	说明
Stops	经停信息列表	Stop[]	N
StartStationName	始发站名	String	N
EndStationName	终点站名	String	N
TrainCode	车次代码	String	N
TrainClassName	车次类型 例如：快速	String	N
ServiceName	服务类型	String	N	例如："无空调" ， "有空调"

Stop

节点	名称	类型	可为空	说明
StartTime	出发时间（格式 HH:mm）	String	N
ArriveTime	到达时间（格式 HH:mm 或者----）	String	N
StationName	到达站名	String	N
StationCode	到达站站点代码	String	N
StopoverTime	停留时间（分钟） 可能为----	String	N
StationNo	站序（01开始）	String	N
IsSearchStation	是否是我们搜索的出行站和到达站	String	N	false不是 true是

3.5 查询某个站点的途经列车时

使用说明

方法名称

• train/getTrainStationTimeTable

使用说明

• 查询某个站点的途经列车时

请求参数

节点	名称	类型	可为空	说明
TrainStationName	站点名称	String	N
TrainStationCode	站点代码	String	N
TrainStartDate	出发日期（格式：yyyy-mm-dd）	String	N

响应参数

节点	名称	类型	可为空	说明
trainInfos	动车信息列表	TrainInfo[]	N
sameStations	同处站点中文名	String[]	N	["南靖","龙山镇"]

trainInfos

节点	名称	类型	可为空	说明
startTrainDate	发车时间（猜测意思）		N	例如：20190309
trainNo	列车号	String	N	例如：5l000D323501
startStationTelecode	始发站 站点代码	String	N	例如：NKH
startStationName	始发站	String	N	例如：南京南
startStartTime	始发站发车时间	String	N	例如：15:08
endStationTelecode	终到站 站点代码	String	N	例如：FYS
endStationName	终到站	String	N	例如：福州南
endArriveTime	终到站到达时间	String	N	例如：22:26
trainTypeCode		String	N	例如：2
trainTypeName		String	N	例如：直通
trainClassCode	车次类型代码	String	N	例如：D
trainClassName	车次类型	String	N	例如：动车
seatTypes	座位类型	String	N	例如：12582912
serviceType	服务类型	String	N	例如：2
serviceTypeStr	服务类型中文，对上一属性的解释（猜测）	String	N	例如：有空调
stationNo	查询站点在次列车中的位置	String	N	例如：01
stationName	查询站点名称	String	N	例如：南京南
stationTelecode	查询站点代码	String	N	例如：NKH
stationTrainCode	途经车次号	String	N	例如：D3235
arriveDayDiff	到达日差异天数（猜测）	String	N	例如：0
arriveTime	到达查询站点时间	String	N	例如：16:27
startTime	查询站点发车时间	String	N	例如：16:34
startDayDiff	发车日差异天数（猜测）	String	N	例如：0
stopoverTime	查询站点停靠时间	String	N	例如：7
runningTime	到达查询站点时，列车运行时间	String	N	例如：52分

3.6 获取所有 车次 - 列车号 对应关系表

方法名称

• train/getTrainCode

使用说明

• train/getTrainCode获取所有 车次 - 列车号 对应关系信息，拉取完信息存入redis，redis有效期为一天。

请求参数

无

响应示例

{
    "C6628" : "76000C662801",
    ......
}