real-estate-search

韩国房地产搜索

技能功能

通过向 https://k-skill-proxy.nomadamas.org/v1/real-estate/... 发送请求，查询韩国房地产实际交易价格和全租/月租数据。数据基于韩国国土交通部（MOLIT）实际交易价格申报数据。

使用场景

• “帮我查一下蚕室LéCiel 2024年的买卖实际交易价格”
• “显示麻浦区公寓的全租实际交易价格”
• “我想看圣水洞写字楼的月租实际交易数据”
• “江南区联排别墅的买卖实际交易价格”
• “龙山区商业办公用房的交易记录”

不使用场景

• 查询海外房地产行情/交易
• 仅需比较民间挂牌价/房源（非实际交易价格）
• 需要税务、登记、中介法律咨询等判断的情况
• 查询青약Home的分销/中签（暂不支持）

输入参数

• q：地区名称（region-code 端点，例如："서울 강남구"、"마포구"）
• lawd_cd：5位法定洞代码（transaction 端点，例如："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千万韩元）
• 已取消的交易由服务器自动过滤。