# 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 | ### ### 请求体 注灰色背景为高级特性，默认不不填写，根据需要进行开发。 ```json { "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） ```objective-c ``` ### 请求（Response） --- ## 转机行程搜索 ### 请求（Request） ```json { "journeyType": "OW", "origin": "BOM", "destination": "CNX", "departureDate": "20251118", "adults": 1, "children": 0, "infants": 0 } ``` ### 响应（Response） 在线查看：https://jsonhero.io/j/J0LMhczR0bJM/editor