GET /real-estate/dimensions

Real-estate API 의 가능한 sigungu / dong / property_type / transaction_type 값을 enumerate. UI dropdown용.

Last updated: 2026-04-26

/real-estate/pulse 호출에 사용할 수 있는 enumerable 값을 반환합니다. UI 드롭다운 / 자동완성 / 사용 가능 cohort 발견에 사용.

GET https://veacon.io/api/v1/real-estate/dimensions

인증

X-API-Key 헤더 또는 veacon_session 쿠키.

쿼리 파라미터

이름	필수	타입	예시	설명
`geo_precision`	선택	string	`sigungu`	`sigungu` (default) / `dong`. `dong` 은 Pro tier 이상, gu_dongs 배열을 채워줍니다.

응답 200

json

{
  "data": {
    "sigungus": [
      { "value": "서울특별시 강남구",   "code": "11680", "sample_count": 7 },
      { "value": "서울특별시 중구",     "code": "11140", "sample_count": 3 },
      { "value": "서울특별시 영등포구", "code": "11560", "sample_count": 3 }
    ],
    "gu_dongs": [
      /* `geo_precision=dong` 일 때만 채워짐. 예: */
      { "value": "강남구 > 역삼동",     "code": "11680", "sample_count": 4 }
    ],
    "property_types": [
      { "value": "office",              "sample_count": 15 },
      { "value": "retail",              "sample_count": 3 },
      { "value": "commercial_complex",  "sample_count": 1 },
      { "value": "mixed_use",           "sample_count": 1 }
    ],
    "transaction_types": [
      { "value": "sale",            "sample_count": 9 },
      { "value": "monthly_lease",   "sample_count": 6 },
      { "value": "chartered_lease", "sample_count": 5 }
    ]
  },
  "_meta": {
    /* 동일한 Layer 1 envelope */
  }
}

필드 의미

sigungus — 6개월 sample window 안에서 거래가 있는 sigungu 목록. code 가 sigungu_code 파라미터에 직접 사용 가능.
gu_dongs — geo_precision=dong 일 때만 채워짐. 형식 "<구> > <동>". Pro tier 이상에서만 활용 가능.
property_types / transaction_types — 가능한 enum 값.
sample_count — 6개월 window 안 거래 수.

응답 403 TIER_RESTRICTED

Starter tier 가 geo_precision=dong 으로 호출하면 /real-estate/pulse 와 동일한 형식으로 403 반환.

curl 예시

bash

# Sigungu list
curl -H "X-API-Key: $VEACON_API_KEY" \
  https://veacon.io/api/v1/real-estate/dimensions

# Pro tier — dong precision
curl -G -H "X-API-Key: $VEACON_API_KEY" \
  https://veacon.io/api/v1/real-estate/dimensions \
  --data-urlencode "geo_precision=dong"

활용 예시

javascript

// React 드롭다운 채우기
const r = await fetch('/api/v1/real-estate/dimensions', {
  headers: { 'X-API-Key': process.env.VEACON_API_KEY }
});
const { data } = await r.json();

setSigunguOptions(data.sigungus.map(s => ({
  value: s.code,
  label: `${s.value} (n=${s.sample_count})`,
})));