Name: real-estate-search
Author: nomadamas

韓國房地產搜尋

這個技能做什麼

基本上透過 https://k-skill-proxy.nomadamas.org/v1/real-estate/... 發送請求，查詢韓國房地產實際交易價格與全租/月租數據。資料來源為國土交通部（MOLIT）實際交易價格申報數據。

使用時機

「幫我找蠶室 Ricenz 2024 年買賣實際交易價格」
「顯示麻浦區公寓全租實際交易價格」
「想看聖水洞商住兩用樓月租實際交易數據」
「江南區聯立多世代買賣實際交易價格」
「龍山區商業業務用建築交易明細」

不適合使用的情況

查詢海外房地產行情/交易
僅需比較民間報價/物件，而非實際交易價格
需要判斷稅金/登記/仲介法律諮詢等情況
查詢青약홈 分讓/中籤（尚未支援）

輸入參數

q：地區名稱（region-code 端點，例如："서울 강남구"、"마포구"）
lawd_cd：5 碼法定洞代碼（交易端點，例如："11680"）
deal_ymd：6 碼交易年月 YYYYMM（例如："202403"）
num_of_rows：查詢筆數（預設 100，最大 1000）

前置需求

無。使用者無需準備額外 API 金鑰。上游金鑰僅由代理伺服器注入。

預設路徑

不需要額外的客戶端 API 層。只需直接向代理伺服器發送 HTTP 請求即可。

如果存在 KSKILL_PROXY_BASE_URL 環境變數，則使用其值；否則使用預設路徑 https://k-skill-proxy.nomadamas.org。

支援的端點

地區代碼查詢

GET /v1/real-estate/region-code?q={地區名稱}

實際交易價格/全月租查詢

GET /v1/real-estate/:assetType/:dealType?lawd_cd={代碼}&deal_ymd={年月}

assetType	dealType	說明
`apartment`	`trade`	公寓買賣
`apartment`	`rent`	公寓全月租
`officetel`	`trade`	商住兩用樓買賣
`officetel`	`rent`	商住兩用樓全月租
`villa`	`trade`	聯立多世代買賣
`villa`	`rent`	聯立多世代全月租
`single-house`	`trade`	獨棟/多戶住宅買賣
`single-house`	`rent`	獨棟/多戶住宅全月租
`commercial`	`trade`	商業業務用買賣

不支援 commercial/rent。

範例請求

地區代碼查詢：

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/real-estate/region-code' \
  --data-urlencode 'q=강남구'

公寓買賣實際交易價格查詢：

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/real-estate/apartment/trade' \
  --data-urlencode 'lawd_cd=11680' \
  --data-urlencode 'deal_ymd=202403'

商住兩用樓全月租查詢：

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/real-estate/officetel/rent' \
  --data-urlencode 'lawd_cd=11680' \
  --data-urlencode 'deal_ymd=202403'

回應格式

地區代碼回應

{
  "results": [
    { "lawd_cd": "11680", "name": "서울특별시 강남구" }
  ],
  "query": "강남구",
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

買賣實際交易價格回應

{
  "items": [
    {
      "name": "래미안 퍼스티지",
      "district": "반포동",
      "area_m2": 84.99,
      "floor": 12,
      "price_10k": 245000,
      "deal_date": "2024-03-15",
      "build_year": 2009,
      "deal_type": "중개거래"
    }
  ],
  "summary": {
    "median_price_10k": 230000,
    "min_price_10k": 180000,
    "max_price_10k": 310000,
    "sample_count": 42
  },
  "query": { "asset_type": "apartment", "deal_type": "trade", "lawd_cd": "11680", "deal_ymd": "202403" },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

全月租回應

結構與買賣相同，但項目中包含 deposit_10k、monthly_rent_10k、contract_type，摘要中則包含 median_deposit_10k、monthly_rent_avg_10k 等。

回應策略

若為實際交易價格/全月租請求，先透過 region-code 端點確認行政區代碼，再依資產類型端點查詢。
公寓買賣優先使用 apartment/trade，公寓全月租優先使用 apartment/rent。
商住兩用樓/別墅/獨棟住宅/商業業務用則路由至對應資產類型的端點。
若使用者未提供足夠的洞/建築名稱/年月，則先補齊地區、社區名稱、基準月份。
不混用實際交易價格與報價。此技能僅處理基於國土交通部的實際交易/全月租申報數據。

保持回答簡潔

地區名稱 + 資產類型 + 交易年月
交易筆數（summary.sample_count）
價格摘要：中位數、最小值、最大值
前 3-5 筆代表性交易（名稱、面積、樓層、價格、日期）
若為全月租，則包含保證金 + 月租摘要

失敗模式

lawd_cd 或 deal_ymd 格式錯誤時回傳 400
代理伺服器缺少 DATA_GO_KR_API_KEY 時回傳 503
上游 MOLIT API 錯誤時回傳 502 + molit_api_XXX 錯誤碼
該地區/期間無數據時回傳空 items 陣列

完成條件

已選擇符合請求資產類型的端點。
必要時已透過 region-code 確認地區代碼。
已查詢並摘要實際交易價格/全月租結果。
同時保留原始數據來源（國土交通部實際交易價格申報）。

備註

原始參考：https://github.com/tae0y/real-estate-mcp/tree/main
官方數據來源：공공데이터포털（https://www.data.go.kr）
價格單位：price_10k、deposit_10k = 萬韓元（例如：245000 = 24 億 5 千萬韓元）
已取消的交易會由伺服器自動過濾。

real-estate-search

相關技能