mipu-open/docs/02-01_cache-search.md

cache/search - 查询航司缓存数据

缓存票价搜索（cache/search）API 说明文档

用户使用场景

用户希望以低成本，高性能的模式获取航司的价格数据，该数据源为我司缓存库内容，非实时提取航司数据。

错误场景(不应该使用本接口的场景)

本接口不会与航司产生任何交互，无法保障在响应时刻价格/库存与航司完全一致。

性能指标

• 航司路线&旅行日期覆盖率：按航司提供，平均值为180天内>90%。
• 价格准确率（验价变价率）：<85%

请求说明

请求地址	https://${endpoint}/cache/search
请求方法	POST
注意事项	Header必须带压缩请求。

请求参数

Header

参数名称	类型	是否必选	示例值	说明
Content-Type	String	是	application/json	固定值，指定请求体格式为 JSON
Accept-Encoding	String	是	gzip, deflate, br	必须要填写，否则服务器会拒绝。
client-key	String	是	xxxxx	联系我们获取生产环境key
client-secret	String	是	xxxxx	联系我们获取生产环境secret

请求体

注灰色背景为高级特性，默认不不填写，根据需要进行开发。

{
  "journeyType": "OW",
  "origin": "MIL",
  "destination": "CAG",
  "departureDate": "20251118",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "agent": "u2web"
}

参数名称	类型	是否必选	示例值(默认值)	说明
journeyType	String	是	"OW"	行程为单程还是往返程OW：单程OneWayRT：往返RoundTrip
origin	String	是	"CJJ"	出发地，为IATA 3字码兼容城市或者机场3字码
originAirport	String	否
destination	String	是	"SHA"	到达地，为IATA3字码兼容城市或者机场3字码
destinationAirport	String	否
departureDate	String	是	20240326	出发日期，格式为 YYYYMMDD（如 2024 年 5 月 1 日为 20240501）
returnDate	String	否	20240423（仅 RT 必填）	返程日期，格式同 departureDate，仅当 journeyType=RT 时必传，OW 时可传空
adults	Integer	是	2	成人，乘机人数量
children	Integer	是	1	儿童，乘机人数量
infants	Integer	是	0	婴儿，乘机人数量
agent	String	是	"F9-web"	你自行定义的F9执行器编码（Agent Code）
proxy	String	是		本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如myproxy-USUS代表美国
acceptCacheMinutes	Integer	否	5	默认值：5**如无特殊情况，本参数不建议设置或调整。**为了避免频繁请求航司设置的缓存，用户可以指定缓存时长，不填写为5。

返回参数

探索一个返回参数json，https://jsonhero.io/j/XmTLWK94Ae5X

参数名称	类型	示例值	说明
itineraries	Array	-	航线组合列表，包含不同航班拼接的行程方案
code	Integer	0	系统状态码：0 = 成功，非 0 为失败
msg	String	null	系统消息：成功时为 null，失败时返回具体系统提示信息
sessionId	String	66d807b0-abbc-4b57-aeff-bbf4fc29fb75	UUID: 与航司通信的session值，可以用于加速后续动作，如继续获取包裹，选座，下单。

常见问题

origin/originAirport的区别是什么？

origin：出发地，建议传入IATA规定的城市码，必填

originAirport：出发机场，非必填

由于各个数据源对于城市码/机场码的需求场景不一致，服务端做了兼容处理。

一般情况只需要传入Origin(城市码)，我们会自动将Origin翻译为机场码，并对航司进行轮询获取所有数据。

部分特殊情况，如只需要搜索单个机场码，或者直接搜索城市码，不希望服务端转换为机场码，请将需要搜索的三字码直接放入OriginAirport。

举例：

入参：origin: LON。

不传入originAirport， 服务端发送给航司originAirport: LCY, LGW, LHR, LTN, SEN, STN

传入originAirport: LCY, 服务端实际发送给航司originAirport: LCY

传入originAirport: LON, 服务端实际发送给航司 originAirport: LON

destination/destinationAirport逻辑同origin/originAirport

业务案例

单人单程搜索

请求（Request）

请求（Response）

---

转机行程搜索

请求（Request）

{
  "journeyType": "OW",
  "origin": "BOM",
  "destination": "CNX",
  "departureDate": "20251118",
  "adults": 1,
  "children": 0,
  "infants": 0
}

响应（Response）

在线查看：https://jsonhero.io/j/J0LMhczR0bJM/editor