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.
기본적으로 https://k-skill-proxy.nomadamas.org/v1/real-estate/... 로 요청해서 한국 부동산 실거래가/전월세 데이터를 조회한다. 국토교통부(MOLIT) 실거래가 신고 데이터를 기반으로 한다.
q: 지역명 (region-code endpoint, 예: "서울 강남구", "마포구")lawd_cd: 5자리 법정동 코드 (transaction endpoint, 예: )"11680"deal_ymd: 6자리 거래년월 YYYYMM (예: "202403")num_of_rows: 조회 건수 (기본 100, 최대 1000)없음. 사용자는 별도 API key를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.
추가 client 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 이 포함되고, summary에 median_deposit_10k, monthly_rent_avg_10k 등이 들어간다.
region-code endpoint로 행정구역 코드를 먼저 확인한 뒤 자산 타입별 endpoint로 조회한다.apartment/trade, 아파트 전월세는 apartment/rent 를 우선 사용한다.lawd_cd 또는 deal_ymd 형식이 잘못되면 400 응답DATA_GO_KR_API_KEY 가 없으면 503 응답molit_api_XXX 에러 코드items 배열 반환region-code 로 지역코드를 먼저 확인했다.https://github.com/tae0y/real-estate-mcp/tree/mainhttps://www.data.go.kr)price_10k, deposit_10k = 만원 단위 (예: 245000 = 24억 5천만원)