{ "openapi": "3.1.0", "info": { "title": "선자산 공개 API", "version": "1.0.0", "description": "서울·경기·인천 경매·공매 물건, 실거래 대비 할인율·참고 시세, 단지 실거래 요약, 아파트 필요 현금, 내 돈으로 살 수 있는 아파트 추천, 통계, 가격 3방식 계산기(참고용).\n\n호출 한도: IP당 분 60회, 하루 2000회. 목록은 페이지당 24건, 20페이지까지 (원자료 대량 다운로드 불가).\n\n모든 응답의 meta에 출처·기준일·원문 링크·라이선스가 있습니다. 법원 자료에는 대법원 저작권보호정책 링크를 함께 둡니다. 사진과 개인 정보는 제공하지 않습니다.\n\n라이선스: 선자산 계산값은 CC BY 4.0 (출처: 선자산 (https://staging.lineestate.co.kr)). 참고용 가격 시뮬레이션입니다. 입찰·거래 전 원문 공고와 권리관계를 확인하세요.\n\nMCP 서버: https://staging.lineestate.co.kr/api/mcp (Streamable HTTP)", "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" } }, "servers": [ { "url": "https://staging.lineestate.co.kr/api/v1" } ], "paths": { "/properties": { "get": { "operationId": "searchProperties", "summary": "경매·공매 물건 검색", "parameters": [ { "name": "section", "in": "query", "required": false, "description": "apartment(아파트·오피스텔·빌라, 기본) | commercial(상가·건물·토지)", "schema": { "type": "string", "enum": [ "apartment", "commercial" ] } }, { "name": "sido", "in": "query", "required": false, "description": "서울 | 경기 | 인천 (또는 서울특별시 등)", "schema": { "type": "string" } }, { "name": "sigungu", "in": "query", "required": false, "description": "시군구 (예: 마포구). sido와 함께", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "아파트 섹션 유형: apt | officetel | villa", "schema": { "type": "string", "enum": [ "apt", "officetel", "villa" ] } }, { "name": "source", "in": "query", "required": false, "description": "court(법원 경매) | onbid(온비드 공매)", "schema": { "type": "string", "enum": [ "court", "onbid" ] } }, { "name": "q", "in": "query", "required": false, "description": "주소·단지명 검색어", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "recommend | discount | deadline | price | recent", "schema": { "type": "string", "enum": [ "recommend", "discount", "deadline", "price", "recent" ] } }, { "name": "min_discount", "in": "query", "required": false, "description": "실거래 대비 할인율 하한(%). 아파트 섹션, 신뢰도 보통 이상만", "schema": { "type": "number" } }, { "name": "page", "in": "query", "required": false, "description": "1~20", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "물건 목록", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/properties/{id}": { "get": { "operationId": "getProperty", "summary": "물건 상세", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "물건 id (UUID)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "물건 상세", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/properties/{id}/valuation": { "get": { "operationId": "getPropertyValuation", "summary": "가격 3방식 계산 (참고용)", "description": "비교·수익·원가 방식. 기본값은 우리 데이터로 채우며 쿼리로 바꿔 볼 수 있습니다. 금액은 원.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "물건 id (UUID)", "schema": { "type": "string" } }, { "name": "method", "in": "query", "required": false, "description": "compare | income | cost (없으면 가능한 것 모두)", "schema": { "type": "string", "enum": [ "compare", "income", "cost" ] } }, { "name": "floor", "in": "query", "required": false, "description": "비교: first | low | mid | high | top", "schema": { "type": "string" } }, { "name": "condition", "in": "query", "required": false, "description": "비교: needs | basic | partial | full", "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "description": "비교: worse | normal | better", "schema": { "type": "string" } }, { "name": "deposit", "in": "query", "required": false, "description": "수익: 보증금(원)", "schema": { "type": "number" } }, { "name": "monthly_rent", "in": "query", "required": false, "description": "수익: 월세(원)", "schema": { "type": "number" } }, { "name": "conversion_rate", "in": "query", "required": false, "description": "수익: 전월세전환율(%)", "schema": { "type": "number" } }, { "name": "yield", "in": "query", "required": false, "description": "수익: 수익률(%)", "schema": { "type": "number" } }, { "name": "region", "in": "query", "required": false, "description": "수익(상가·오피스): 한국부동산원 조사 상권 키 (예: 서울>기타>장안동)", "schema": { "type": "string" } }, { "name": "land_multiplier", "in": "query", "required": false, "description": "원가: 공시지가→시세 배율 1.0~1.5", "schema": { "type": "number" } }, { "name": "structure", "in": "query", "required": false, "description": "원가: 구조 (응답 options.structure 중 하나)", "schema": { "type": "string" } }, { "name": "use", "in": "query", "required": false, "description": "원가: 용도 (응답 options.use 중 하나)", "schema": { "type": "string" } }, { "name": "age", "in": "query", "required": false, "description": "원가: 경과연수", "schema": { "type": "number" } }, { "name": "land_area", "in": "query", "required": false, "description": "원가: 토지 면적(㎡)", "schema": { "type": "number" } }, { "name": "floor_area", "in": "query", "required": false, "description": "원가: 건물 면적(㎡)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "방식별 가격 범위·근거", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/valuation": { "post": { "operationId": "calculateValue", "summary": "직접 넣은 값으로 계산 (참고용)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeValuation" }, "examples": { "income": { "value": { "method": "income", "monthly_rent": 12000000, "deposit": 200000000, "conversion_rate": 6, "yield": 3.5 } } } } } }, "responses": { "200": { "description": "가격 범위", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/complexes/{kaptCode}": { "get": { "operationId": "getComplex", "summary": "아파트 단지 정보, 평형별 최근 12개월 실거래, 매물화 가능성 신호(점수·신호 이름)", "parameters": [ { "name": "kaptCode", "in": "path", "required": true, "description": "공동주택 단지코드 (예: A10021339)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "단지", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/complexes/{kaptCode}/cash-needed": { "get": { "operationId": "getCashNeeded", "summary": "이 아파트 사려면 현금이 얼마 필요한가 (만원)", "description": "최근 12개월 실거래 중앙값 + 대출 규칙(LTV·집값별 한도·DSR) + 취득세·중개보수. 처지별·연소득별 표, 적용 규칙, 월 상환액, 기준일(가격·금리·규정). data.rental은 임대 구분(kind: 임대 | 혼합, 해당 없으면 null). 임대 단지는 계산하지 않고 200으로 status=rental_only, reason(이유), rental과 price·cash_needed·loan=null을 줍니다.", "parameters": [ { "name": "kaptCode", "in": "path", "required": true, "description": "공동주택 단지코드", "schema": { "type": "string" } }, { "name": "area", "in": "query", "required": false, "description": "전용면적(㎡). 없으면 대표 평형", "schema": { "type": "number" } }, { "name": "income", "in": "query", "required": false, "description": "세전 연소득 부부 합산(만원). 4000·6000·8000·10000·15000 중 가까운 값. 기본 6000", "schema": { "type": "number" } }, { "name": "situation", "in": "query", "required": false, "description": "none | first | sell | keep", "schema": { "type": "string", "enum": [ "none", "first", "sell", "keep" ] } } ], "responses": { "200": { "description": "필요 현금", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/recommend": { "get": { "operationId": "recommend", "summary": "내 돈으로 살 수 있는 아파트 TOP 3", "description": "기준점 근처(2→3→5km) 예산 안 단지만 순위를 매깁니다. 기준점이 없으면 서울·경기·인천 전체. data.url은 같은 조건의 추천 화면.", "parameters": [ { "name": "cash", "in": "query", "required": true, "description": "가진 현금(억 원)", "schema": { "type": "number" } }, { "name": "near", "in": "query", "required": false, "description": "기준점: 역·동·단지 이름 (예: 가좌역)", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "기준점 위도 (near 대신)", "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": false, "description": "기준점 경도", "schema": { "type": "number" } }, { "name": "size", "in": "query", "required": false, "description": "10평대 | 20평대 | 30평대 | 40평대", "schema": { "type": "string" } }, { "name": "income", "in": "query", "required": false, "description": "세전 연소득 부부 합산(만원). 없으면 6000 가정", "schema": { "type": "number" } }, { "name": "situation", "in": "query", "required": false, "description": "none | first | sell | keep", "schema": { "type": "string", "enum": [ "none", "first", "sell", "keep" ] } }, { "name": "mode", "in": "query", "required": false, "description": "sale | jeonse", "schema": { "type": "string", "enum": [ "sale", "jeonse" ] } }, { "name": "move", "in": "query", "required": false, "description": "3m | 6m | 1y", "schema": { "type": "string", "enum": [ "3m", "6m", "1y" ] } } ], "responses": { "200": { "description": "추천", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stats/{kind}": { "get": { "operationId": "getStats", "summary": "통계 (할인율·낙찰가율·구별 ㎡당 가격·전세가율)", "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "discount", "sale-ratio", "market-trend" ] } } ], "responses": { "200": { "description": "통계", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "schemas": { "Envelope": { "type": "object", "properties": { "data": { "description": "본문" }, "meta": { "type": "object", "properties": { "as_of": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "as_of": { "type": "string" } } } }, "court_copyright_policy": { "type": "string", "description": "법원 자료가 있으면 대법원 저작권보호정책 링크" }, "license": { "type": "object" }, "attribution": { "type": "string" }, "disclaimer": { "type": "string" } } } } }, "FreeValuation": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "compare", "income", "cost" ] }, "median": { "type": "number", "description": "compare: 비교 사례 중앙값(원)" }, "min": { "type": "number" }, "max": { "type": "number" }, "count": { "type": "integer" }, "monthly_rent": { "type": "number", "description": "income: 월세(원)" }, "deposit": { "type": "number" }, "conversion_rate": { "type": "number" }, "vacancy": { "type": "number", "description": "income: 공실률(%)" }, "yield": { "type": "number", "description": "income: 수익률(%)" }, "build_cost_per_m2": { "type": "number", "description": "cost: ㎡당 건축비(원)" }, "land_price_per_m2": { "type": "number" }, "land_area": { "type": "number" }, "land_multiplier": { "type": "number" }, "floor_area": { "type": "number" }, "age": { "type": "number" }, "structure_index": { "type": "number" }, "use_index": { "type": "number" }, "depreciation_rate": { "type": "number" } } } }, "responses": { "Error": { "description": "오류", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }