| name | real-estate-search |
| description | Korean apartment/officetel/villa/single-house real transaction price and rent lookups via k-skill-proxy. Based on tae0y's real-estate-mcp and MOLIT public data APIs. |
| license | MIT |
| metadata | {"category":"real-estate","locale":"ko-KR","phase":"v1"} |
Korean Real Estate Search
What this skill does
๊ธฐ๋ณธ์ ์ผ๋ก https://k-skill-proxy.nomadamas.org/v1/real-estate/... ๋ก ์์ฒญํด์ ํ๊ตญ ๋ถ๋์ฐ ์ค๊ฑฐ๋๊ฐ/์ ์์ธ ๋ฐ์ดํฐ๋ฅผ ์กฐํํ๋ค. ๊ตญํ ๊ตํต๋ถ(MOLIT) ์ค๊ฑฐ๋๊ฐ ์ ๊ณ ๋ฐ์ดํฐ๋ฅผ ๊ธฐ๋ฐ์ผ๋ก ํ๋ค.
When to use
- "์ ์ค ๋ฆฌ์ผ์ธ 2024๋
๋งค๋งค ์ค๊ฑฐ๋๊ฐ ์ฐพ์์ค"
- "๋งํฌ๊ตฌ ์ํํธ ์ ์ธ ์ค๊ฑฐ๋๊ฐ ๋ณด์ฌ์ค"
- "์ฑ์๋ ์คํผ์คํ
์์ธ ์ค๊ฑฐ๋ ๋ฐ์ดํฐ ๋ณผ๋"
- "๊ฐ๋จ๊ตฌ ์ฐ๋ฆฝ๋ค์ธ๋ ๋งค๋งค ์ค๊ฑฐ๋๊ฐ"
- "์ฉ์ฐ๊ตฌ ์์
์
๋ฌด์ฉ ๊ฑด๋ฌผ ๊ฑฐ๋ ๋ด์ญ"
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)
Prerequisites
์์. ์ฌ์ฉ์๋ ๋ณ๋ API key๋ฅผ ์ค๋นํ ํ์๊ฐ ์๋ค. upstream key๋ proxy ์๋ฒ์์๋ง ์ฃผ์
ํ๋ค.
Default path
์ถ๊ฐ client 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/: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
์ง์ญ์ฝ๋ ์กฐํ:
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'
Response shape
์ง์ญ์ฝ๋ ์๋ต
{
"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 ์ด ํฌํจ๋๊ณ , summary์ median_deposit_10k, monthly_rent_avg_10k ๋ฑ์ด ๋ค์ด๊ฐ๋ค.
Response policy
- ์ค๊ฑฐ๋๊ฐ/์ ์์ธ ์์ฒญ์ด๋ฉด
region-code endpoint๋ก ํ์ ๊ตฌ์ญ ์ฝ๋๋ฅผ ๋จผ์ ํ์ธํ ๋ค ์์ฐ ํ์
๋ณ endpoint๋ก ์กฐํํ๋ค.
- ์ํํธ ๋งค๋งค๋
apartment/trade, ์ํํธ ์ ์์ธ๋ apartment/rent ๋ฅผ ์ฐ์ ์ฌ์ฉํ๋ค.
- ์คํผ์คํ
/๋น๋ผ/๋จ๋
์ฃผํ/์์
์
๋ฌด์ฉ์ ์์ฐ ํ์
์ ๋ง๋ endpoint๋ก ๋ผ์ฐํ
ํ๋ค.
- ์ฌ์ฉ์๊ฐ ๋/๊ฑด๋ฌผ๋ช
/์ฐ์์ ๋ ์คฌ์ผ๋ฉด ์ง์ญ, ๋จ์ง๋ช
, ๊ธฐ์ค ์์ ๋จผ์ ๋ณด๊ฐํ๋ค.
- ์ค๊ฑฐ๋๊ฐ์ ํธ๊ฐ๋ฅผ ์์ด ๋งํ์ง ์๋๋ค. ์ด ์คํฌ์ ๊ตญํ ๊ตํต๋ถ ๊ธฐ๋ฐ ์ค๊ฑฐ๋/์ ์์ธ ์ ๊ณ ๋ฐ์ดํฐ๋ฅผ ๋ค๋ฃฌ๋ค.
Keep the answer compact
- ์ง์ญ๋ช
+ ์์ฐ ํ์
+ ๊ฑฐ๋๋
์
- ๊ฑฐ๋ ๊ฑด์ (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 ๋ฐฐ์ด ๋ฐํ
Done when
- ์์ฒญ ์์ฐ ํ์
์ ๋ง๋ endpoint๋ฅผ ์ ํํ๋ค.
- ํ์ํ ๊ฒฝ์ฐ
region-code ๋ก ์ง์ญ์ฝ๋๋ฅผ ๋จผ์ ํ์ธํ๋ค.
- ์ค๊ฑฐ๋๊ฐ/์ ์์ธ ๊ฒฐ๊ณผ๋ฅผ ์กฐํํ๊ณ ์์ฝํ๋ค.
- ์๋ณธ ๋ฐ์ดํฐ ์ถ์ฒ(๊ตญํ ๊ตํต๋ถ ์ค๊ฑฐ๋๊ฐ ์ ๊ณ )๋ฅผ ํจ๊ป ๋จ๊ฒผ๋ค.
Notes
- ์๋ณธ ์ฐธ๊ณ :
https://github.com/tae0y/real-estate-mcp/tree/main
- ๊ณต์ ๋ฐ์ดํฐ ์ถ์ฒ: ๊ณต๊ณต๋ฐ์ดํฐํฌํธ (
https://www.data.go.kr)
- ๊ฐ๊ฒฉ ๋จ์:
price_10k, deposit_10k = ๋ง์ ๋จ์ (์: 245000 = 24์ต 5์ฒ๋ง์)
- ์ทจ์๋ ๊ฑฐ๋๋ ์๋ฒ์์ ์๋ ํํฐ๋ง๋๋ค.