real-estate-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Korean Real Estate Search

韩国房地产查询工具

What this skill does

工具功能

기본적으로

https://k-skill-proxy.nomadamas.org/v1/real-estate/...

로 요청해서 한국 부동산 실거래가/전월세 데이터를 조회한다. 국토교통부(MOLIT) 실거래가 신고 데이터를 기반으로 한다.

默认向

https://k-skill-proxy.nomadamas.org/v1/real-estate/...

发送请求，查询韩国房地产实际交易价/全税/月租数据，数据基于韩国国土交通部（MOLIT）的实际交易价申报数据。

When to use

适用场景

"잠실 리센츠 2024년 매매 실거래가 찾아줘"
"마포구 아파트 전세 실거래가 보여줘"
"성수동 오피스텔 월세 실거래 데이터 볼래"
"강남구 연립다세대 매매 실거래가"
"용산구 상업업무용 건물 거래 내역"

"帮我查询2024年蚕室Resenz的买卖实际交易价"
"给我看看麻浦区公寓的全税实际交易价"
"我要查看圣水洞商住两用房的月租实际交易数据"
"江南区联排住宅的买卖实际交易价"
"龙山区商业用途建筑的交易记录"

When not to use

不适用场景

해외 부동산 시세/거래 조회
실거래가가 아닌 민간 호가/매물 비교만 필요한 경우
세금/등기/중개 법률자문처럼 판단이 필요한 경우
청약홈 분양/당첨 조회 (아직 미지원)

查询海外房地产行情/交易
仅需要对比民间报价/在售房源，而非实际交易价的场景
需要税务/登记/中介法律咨询等判断类服务的场景
认购平台的预售/中签查询（暂不支持）

Inputs

输入参数

```
q
```
: 지역명 (region-code endpoint, 예:
```
"서울 강남구"
```
,
```
"마포구"
```
)
```
lawd_cd
```
: 5자리 법정동 코드 (transaction endpoint, 예:
```
"11680"
```
)
```
deal_ymd
```
: 6자리 거래년월 YYYYMM (예:
```
"202403"
```
)
```
num_of_rows
```
: 조회 건수 (기본 100, 최대 1000)

```
q
```
: 地区名（region-code 接口使用，例：
```
"首尔江南区"
```
、
```
"麻浦区"
```
）
```
lawd_cd
```
: 5位法定洞代码（交易查询接口使用，例：
```
"11680"
```
）
```
deal_ymd
```
: 6位交易年月，格式为 YYYYMM（例：
```
"202403"
```
）
```
num_of_rows
```
: 查询条数（默认100，最大1000）

Prerequisites

前置要求

없음. 사용자는 별도 API key를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.

无。用户无需准备单独的API key，上游密钥仅由代理服务器注入。

Default path

默认调用路径

추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.

KSKILL_PROXY_BASE_URL

환경변수가 있으면 그 값을 사용하고, 없으면 기본 경로

https://k-skill-proxy.nomadamas.org

를 사용한다.

不需要额外的客户端API层，直接向代理服务器发送HTTP请求即可。

如果存在

KSKILL_PROXY_BASE_URL

环境变量则使用该值，否则使用默认路径

https://k-skill-proxy.nomadamas.org

。

Supported endpoints

支持的接口

지역코드 조회

地区代码查询

GET /v1/real-estate/region-code?q={지역명}

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

는 지원하지 않는다.

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

接口。

Example requests

请求示例

지역코드 조회:

bash

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

아파트 매매 실거래가 조회:

bash

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

오피스텔 전월세 조회:

bash

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

查询地区代码：

bash

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

查询公寓买卖实际交易价：

bash

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

查询商住两用房全税/月租：

bash

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

Response shape

返回结构

지역코드 응답

地区代码返回结果

json

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

json

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

매매 실거래가 응답

买卖实际交易价返回结果

json

{
  "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 } }
}

json

{
  "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

이 포함되고, summary에

median_deposit_10k

monthly_rent_avg_10k

등이 들어간다.

结构和买卖接口一致，但返回项中包含

deposit_10k

、

monthly_rent_10k

、

contract_type

字段，统计摘要中包含

median_deposit_10k

、

monthly_rent_avg_10k

等字段。

Response policy

返回规则

실거래가/전월세 요청이면
```
region-code
```
endpoint로 행정구역 코드를 먼저 확인한 뒤 자산 타입별 endpoint로 조회한다.
아파트 매매는
```
apartment/trade
```
, 아파트 전월세는
```
apartment/rent
```
를 우선 사용한다.
오피스텔/빌라/단독주택/상업업무용은 자산 타입에 맞는 endpoint로 라우팅한다.
사용자가 동/건물명/연월을 덜 줬으면 지역, 단지명, 기준 월을 먼저 보강한다.
실거래가와 호가를 섞어 말하지 않는다. 이 스킬은 국토교통부 기반 실거래/전월세 신고 데이터를 다룬다.

如果是查询实际交易价/全税月租，需先通过
```
region-code
```
接口确认行政区代码，再调用对应资产类型的接口查询。
公寓买卖优先使用
```
apartment/trade
```
接口，公寓全税/月租优先使用
```
apartment/rent
```
接口。
商住两用房/别墅/独栋住宅/商业用途房产按资产类型路由到对应接口。
如果用户未提供完整的洞/建筑名/年月，需先补全地区、小区名、基准月份信息。
不要混淆实际交易价和报价，本工具仅处理基于韩国国土交通部的实际交易/全税月租申报数据。

Keep the answer compact

回答精简要求

지역명 + 자산 타입 + 거래년월
거래 건수 (summary.sample_count)
가격 요약: 중위값, 최소, 최대
상위 3-5건 대표 거래 (이름, 면적, 층, 가격, 날짜)
전월세면 보증금 + 월세 요약도 포함

地区名 + 资产类型 + 交易年月
交易条数（summary.sample_count）
价格摘要：中位数、最小值、最大值
3-5条代表性交易记录（名称、面积、楼层、价格、日期）
如果是全税/月租查询，还需包含保证金+月租摘要

Failure modes

错误场景

```
lawd_cd
```
또는
```
deal_ymd
```
형식이 잘못되면 400 응답
프록시 서버에
```
DATA_GO_KR_API_KEY
```
가 없으면 503 응답
upstream MOLIT API 오류면 502 +
```
molit_api_XXX
```
에러 코드
해당 지역/기간에 데이터가 없으면 빈
```
items
```
배열 반환

如果
```
lawd_cd
```
或
```
deal_ymd
```
格式错误，返回400响应
如果代理服务器没有配置
```
DATA_GO_KR_API_KEY
```
，返回503响应
如果上游 MOLIT API 报错，返回502 +
```
molit_api_XXX
```
错误码
如果对应地区/时间段无数据，返回空的
```
items
```
数组

Done when

完成标识

요청 자산 타입에 맞는 endpoint를 선택했다.
필요한 경우
```
region-code
```
로 지역코드를 먼저 확인했다.
실거래가/전월세 결과를 조회하고 요약했다.
원본 데이터 출처(국토교통부 실거래가 신고)를 함께 남겼다.

已选择与请求资产类型匹配的接口
必要时已通过
```
region-code
```
接口确认地区代码
已查询并汇总实际交易价/全税月租结果
已标注原始数据来源（韩国国土交通部实际交易价申报数据）

Notes

备注

원본 참고:

https://github.com/tae0y/real-estate-mcp/tree/main

공식 데이터 출처: 공공데이터포털 (
```
https://www.data.go.kr
```
)
가격 단위:
```
price_10k
```
,
```
deposit_10k
```
= 만원 단위 (예: 245000 = 24억 5천만원)
취소된 거래는 서버에서 자동 필터링된다.

原项目参考：

https://github.com/tae0y/real-estate-mcp/tree/main

官方数据来源：公共数据门户（
```
https://www.data.go.kr
```
）
价格单位：
```
price_10k
```
、
```
deposit_10k
```
单位为万韩元（例：245000 = 24亿5千万韩元）
已取消的交易由服务器自动过滤。