{"openapi":"3.1.0","info":{"title":"西城成交档案只读查询 API","version":"1.2.0","description":"公开、只读的成交记录 API。AI 应先调用 /api/query/catalog，沿 nextCursor 遍历完整目录，再使用每项 detailUrl 逐条读取完整记录。/api/query 继续提供参数化组合查询且不会执行调用方提供的 SQL。"},"servers":[{"url":"https://hotel.xbrain.site"}],"paths":{"/api/query":{"get":{"operationId":"queryTransactionsByParameters","summary":"使用 URL 参数组合查询成交记录","parameters":[{"name":"keyword","in":"query","required":false,"schema":{"type":["string","null"],"maxLength":100}},{"name":"community","in":"query","required":false,"schema":{"type":["string","null"],"maxLength":100}},{"name":"district","in":"query","required":false,"schema":{"type":["string","null"],"maxLength":60}},{"name":"school","in":"query","required":false,"schema":{"type":["string","null"],"maxLength":100}},{"name":"orientation","in":"query","required":false,"schema":{"type":["string","null"],"maxLength":40}},{"name":"floorBand","in":"query","required":false,"schema":{"type":["string","null"],"maxLength":20}},{"name":"reviewStatus","in":"query","required":false,"schema":{"type":["string","null"],"enum":["auto_verified","needs_review","sample-reviewed","unreviewed",null]}},{"name":"articleId","in":"query","required":false,"schema":{"type":["string","null"],"maxLength":100}},{"name":"startDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date"}},{"name":"endDate","in":"query","required":false,"schema":{"type":["string","null"],"format":"date"}},{"name":"bedrooms","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0,"maximum":30}},{"name":"livingRooms","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0,"maximum":20}},{"name":"bathrooms","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0,"maximum":20}},{"name":"minListPrice","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"maxListPrice","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"minPrice","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"maxPrice","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"minArea","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"maxArea","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"minUnitPrice","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"maxUnitPrice","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0}},{"name":"minNegotiation","in":"query","required":false,"schema":{"type":["number","null"],"minimum":-100,"maximum":100}},{"name":"maxNegotiation","in":"query","required":false,"schema":{"type":["number","null"],"minimum":-100,"maximum":100}},{"name":"minCycleDays","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0}},{"name":"maxCycleDays","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0}},{"name":"minFloor","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":-10,"maximum":300}},{"name":"maxFloor","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":-10,"maximum":300}},{"name":"minFloorTotal","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":1,"maximum":300}},{"name":"maxFloorTotal","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":1,"maximum":300}},{"name":"minConfidence","in":"query","required":false,"schema":{"type":["number","null"],"minimum":0,"maximum":1}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["newest","oldest","price-asc","price-desc","area-asc","area-desc","unit-asc","unit-desc","discount-asc","discount-desc","cycle-asc","cycle-desc"],"default":"newest"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},{"name":"facets","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"设为 1 时返回可选片区、楼层类型和数据状态。"}],"responses":{"200":{"description":"分页成交记录或筛选项元数据"},"422":{"description":"查询参数无效"}}},"post":{"operationId":"queryTransactionsByJson","summary":"使用 JSON 组合查询成交记录","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"keyword":{"type":["string","null"],"maxLength":100},"community":{"type":["string","null"],"maxLength":100},"district":{"type":["string","null"],"maxLength":60},"school":{"type":["string","null"],"maxLength":100},"orientation":{"type":["string","null"],"maxLength":40},"floorBand":{"type":["string","null"],"maxLength":20},"reviewStatus":{"type":["string","null"],"enum":["auto_verified","needs_review","sample-reviewed","unreviewed",null]},"articleId":{"type":["string","null"],"maxLength":100},"startDate":{"type":["string","null"],"format":"date"},"endDate":{"type":["string","null"],"format":"date"},"bedrooms":{"type":["integer","null"],"minimum":0,"maximum":30},"livingRooms":{"type":["integer","null"],"minimum":0,"maximum":20},"bathrooms":{"type":["integer","null"],"minimum":0,"maximum":20},"minListPrice":{"type":["number","null"],"minimum":0},"maxListPrice":{"type":["number","null"],"minimum":0},"minPrice":{"type":["number","null"],"minimum":0},"maxPrice":{"type":["number","null"],"minimum":0},"minArea":{"type":["number","null"],"minimum":0},"maxArea":{"type":["number","null"],"minimum":0},"minUnitPrice":{"type":["number","null"],"minimum":0},"maxUnitPrice":{"type":["number","null"],"minimum":0},"minNegotiation":{"type":["number","null"],"minimum":-100,"maximum":100},"maxNegotiation":{"type":["number","null"],"minimum":-100,"maximum":100},"minCycleDays":{"type":["integer","null"],"minimum":0},"maxCycleDays":{"type":["integer","null"],"minimum":0},"minFloor":{"type":["integer","null"],"minimum":-10,"maximum":300},"maxFloor":{"type":["integer","null"],"minimum":-10,"maximum":300},"minFloorTotal":{"type":["integer","null"],"minimum":1,"maximum":300},"maxFloorTotal":{"type":["integer","null"],"minimum":1,"maximum":300},"minConfidence":{"type":["number","null"],"minimum":0,"maximum":1},"sort":{"type":"string","enum":["newest","oldest","price-asc","price-desc","area-asc","area-desc","unit-asc","unit-desc","discount-asc","discount-desc","cycle-asc","cycle-desc"],"default":"newest"},"page":{"type":"integer","minimum":1,"default":1},"pageSize":{"type":"integer","minimum":1,"maximum":100,"default":24}}}}}},"responses":{"200":{"description":"分页成交记录"},"422":{"description":"查询条件无效"}}}},"/api/query/catalog":{"get":{"operationId":"listCompleteTransactionCatalog","summary":"稳定分页遍历全部房源成交摘要","description":"首次调用不传 cursor；随后原样请求 nextPageUrl，直到 nextCursor 为 null。每项包含稳定 recordId（id）和 detailUrl。","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":250}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"上一页返回的不透明 nextCursor，必须原样传回。"}],"responses":{"200":{"description":"目录页、总记录数与下一页游标","content":{"application/json":{"schema":{"type":"object","required":["ok","snapshot","items","nextCursor"],"properties":{"ok":{"const":true},"snapshot":{"type":"object","properties":{"totalRecords":{"type":"integer"},"maximumSequence":{"type":"integer"}}},"returnedCount":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"nextPageUrl":{"type":["string","null"],"format":"uri"},"aiWorkflow":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","required":["recordId","communityName","transactionDate","detailUrl"],"properties":{"recordId":{"type":"string","description":"稳定且唯一的成交记录 ID，用于逐条读取详情。"},"communityName":{"type":"string"},"districtName":{"type":["string","null"]},"schoolName":{"type":["string","null"]},"transactionDate":{"type":"string","format":"date"},"buildingAreaSqm":{"type":["number","null"]},"orientation":{"type":["string","null"]},"floorRaw":{"type":["string","null"]},"bedrooms":{"type":["integer","null"]},"livingRooms":{"type":["integer","null"]},"bathrooms":{"type":["integer","null"]},"listPriceWan":{"type":["number","null"]},"soldPriceWan":{"type":["number","null"]},"unitPriceWanSqm":{"type":["number","null"]},"negotiationPct":{"type":["number","null"]},"reviewStatus":{"type":"string"},"detailUrl":{"type":"string","format":"uri"}}}}}}}}},"422":{"description":"limit 或 cursor 无效"}}}},"/api/query/records/{recordId}":{"get":{"operationId":"getTransactionRecordById","summary":"按稳定 ID 读取一条完整房源成交记录","parameters":[{"name":"recordId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"完整字段、独立裁图和原图链接","content":{"application/json":{"schema":{"type":"object","required":["ok","record"],"properties":{"ok":{"const":true},"mode":{"const":"record-detail"},"record":{"type":"object","required":["id","communityName","transactionDate","imageUrl","originalImageUrl"],"properties":{"recordId":{"type":"string","description":"稳定且唯一的成交记录 ID，用于逐条读取详情。"},"communityName":{"type":"string"},"districtName":{"type":["string","null"]},"schoolName":{"type":["string","null"]},"transactionDate":{"type":"string","format":"date"},"buildingAreaSqm":{"type":["number","null"]},"orientation":{"type":["string","null"]},"floorRaw":{"type":["string","null"]},"bedrooms":{"type":["integer","null"]},"livingRooms":{"type":["integer","null"]},"bathrooms":{"type":["integer","null"]},"listPriceWan":{"type":["number","null"]},"soldPriceWan":{"type":["number","null"]},"unitPriceWanSqm":{"type":["number","null"]},"negotiationPct":{"type":["number","null"]},"reviewStatus":{"type":"string"},"detailUrl":{"type":"string","format":"uri"},"id":{"type":"string"},"articleId":{"type":"string"},"articleTitle":{"type":"string"},"articleSourceUrl":{"type":"string","format":"uri"},"articlePublishedAt":{"type":"integer"},"assetPosition":{"type":"integer"},"assetFilename":{"type":"string"},"assetWidth":{"type":["integer","null"]},"assetHeight":{"type":["integer","null"]},"sourceRecordIndex":{"type":"integer"},"sourceRegion":{"type":["object","null"]},"floorCurrent":{"type":["integer","null"]},"floorBand":{"type":["string","null"]},"floorTotal":{"type":["integer","null"]},"transactionCycleDays":{"type":["integer","null"]},"extractionConfidence":{"type":["number","null"]},"imageUrl":{"type":"string","format":"uri"},"originalImageUrl":{"type":"string","format":"uri"}}}}}}}},"404":{"description":"记录不存在"}}}}}}