{"openapi": "3.1.0", "info": {"title": "山行参谋 · 徒步数据 API", "version": "1.0.0", "description": "只读 API；Asia/Shanghai；同路线不同日期独立保留；未来日期不保证可报名。公开展示活动信息，不含报名人员数据。MCP 适配尚未提供。"}, "servers": [{"url": "."}], "paths": {"/api/v1/platforms": {"get": {"operationId": "list_platforms", "summary": "查看平台接入状态、覆盖范围和最后尝试／成功时间", "parameters": [], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"type": "object"}}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}, "/api/v1/meeting-points": {"get": {"operationId": "list_meeting_points", "summary": "列出实际采集的集合地点和活动数，供用户或AI选择", "parameters": [{"name": "source", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "include_past", "in": "query", "required": false, "schema": {"type": "boolean"}}], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"type": "object"}}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}, "/api/v1/departures": {"get": {"operationId": "search_departures", "summary": "查询具体出发活动，默认不含已结束／已出发活动；日期异常仍返回并附警告", "parameters": [{"name": "date_from", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "date_to", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "source", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "meeting", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "q", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "max_price", "in": "query", "required": false, "schema": {"type": "number"}}, {"name": "max_distance", "in": "query", "required": false, "schema": {"type": "number"}}, {"name": "max_ascent", "in": "query", "required": false, "schema": {"type": "number"}}, {"name": "include_past", "in": "query", "required": false, "schema": {"type": "boolean"}}, {"name": "weekend", "in": "query", "required": false, "schema": {"type": "boolean"}}, {"name": "include_archived", "in": "query", "required": false, "schema": {"type": "boolean"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer"}}], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Departure"}}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}, "/api/v1/departures/{id}": {"get": {"operationId": "get_departure", "summary": "读取单场费用、行程、退改原文和来源；列表余位为观察值", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "example": "beitu:9286"}], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"$ref": "#/components/schemas/Departure"}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}, "/api/v1/compare": {"get": {"operationId": "compare_departures", "summary": "比较2至5场活动，保留来源差异、未知字段和异常", "parameters": [{"name": "ids", "in": "query", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Departure"}}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}, "/api/v1/changes": {"get": {"operationId": "get_changes", "summary": "查询新增观察、字段变化和目录未再出现；未再出现不等于取消", "parameters": [{"name": "since", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "source", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}}], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"type": "object"}}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}, "/api/v1/runs": {"get": {"operationId": "list_collection_runs", "summary": "查看采集运行结果；失败不覆盖上次成功记录", "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}}], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {"type": "array", "items": {"type": "object"}}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}, "/api/v1/quality": {"get": {"operationId": "get_data_quality", "summary": "查看日期警告、列表缺详情和过期数据", "parameters": [], "responses": {"200": {"description": "结构化结果；含数据观察时间和异常说明", "content": {"application/json": {"schema": {"type": "object", "required": ["data", "meta"], "properties": {"data": {}, "meta": {"type": "object"}}}}}}, "400": {"description": "参数错误"}, "404": {"description": "活动不存在"}}}}}, "components": {"schemas": {"Departure": {"type": "object", "required": ["id", "source_id", "title", "observed_at", "warnings", "date_warning"], "properties": {"id": {"type": "string", "description": "来源命名空间中的稳定活动键"}, "source_id": {"type": "string"}, "source_name": {"type": "string"}, "title": {"type": "string"}, "departure_date": {"type": ["string", "null"], "format": "date"}, "end_date": {"type": ["string", "null"], "format": "date"}, "price_cny": {"type": ["number", "null"], "description": "观察时的人民币费用，不保证包含全部可选费用"}, "distance_km": {"type": ["number", "null"]}, "ascent_m": {"type": ["number", "null"]}, "advertised_from_price": {"type": ["number", "null"], "description": "来源起价，可能仅对应一个费用项目；不能当作整团总价"}, "price_basis": {"type": "string"}, "price_options": {"type": "array", "items": {"type": "object"}, "description": "来源票种/费用项目，价格资格和组合关系需核实"}, "remaining": {"type": ["integer", "null"], "description": "观察时的余位，不是实时库存"}, "meeting_points": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string"}, "boarding_time": {"type": "string"}}}}, "observed_at": {"type": "string", "format": "date-time"}, "stale": {"type": "boolean", "description": "超过24小时未成功更新"}, "date_warning": {"type": "boolean"}, "warnings": {"type": "array", "items": {"type": "string"}}, "recommendation_candidate": {"type": "boolean", "description": "日期异常按用户策略保留候选；不等于保证可报名"}, "source_start": {"type": ["string", "null"]}, "source_end": {"type": ["string", "null"]}, "detail_status": {"type": "string", "enum": ["complete", "list_only"]}, "source_schedule_id": {"type": ["integer", "null"], "description": "未知则为空，不从文字生成场次"}, "details": {"type": "object", "description": "详情接口提供的纯文本介绍、费用、行程等；列表查询省略"}, "source_entry": {"type": "object", "description": "平台或样本入口，不能当作本场已核验报名链接"}, "booking_url": {"type": ["string", "null"]}}}}}}