GET /real-estate/pulse

RTMS-grade Korean commercial real estate aggregate pulse. sigungu × property_type × transaction_type × period. ADR-014 vertical.

Last updated: 2026-04-26

한국 상업용 부동산 (CRE) 의 실거래가 기반 quartile + sample + multi-source confidence 를 반환합니다. ADR-014 hybrid data architecture 의 real-estate vertical 의 primary endpoint입니다.

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

인증

X-API-Key 헤더 또는 veacon_session 쿠키. 자세한 내용은 Authentication.

쿼리 파라미터

이름필수타입예시설명
sigungu_code필수string116805-digit 행정코드 (강남구 = 11680). 가능한 값은 /real-estate/dimensions 로 조회
property_type선택stringofficeoffice, retail, commercial_complex, mixed_use 중 하나. 미지정 시 전체
transaction_type선택stringsalesale (매매), chartered_lease (전세), monthly_lease (월세). 미지정 시 전체
period선택stringlast_6mlast_3m / last_6m (default) / last_12m / YYYY-MM / YYYY-Q1..Q4
geo_precision선택stringsigungusigungu (default) / dong. dong 은 Pro tier 이상.
dong선택string역삼동geo_precision=dong 일 때만 사용

응답 200

json
{
  "data": [
    {
      "sigungu_code": "11680",
      "sigungu": "서울특별시 강남구",
      "gu": null,
      "dong": null,
      "property_type": "office",
      "transaction_type": "sale",
      "period": "last_6m",
      "sample_count": 5,
      "avg_price": 4383333333,
      "p25_price": 3675000000,
      "median_price": 4150000000,
      "p75_price": 4975000000,
      "avg_monthly_rent": null,
      "p25_monthly_rent": null,
      "median_monthly_rent": null,
      "p75_monthly_rent": null,
      "avg_area_m2": "250.77",
      "confidence": "medium",
      "source_mix": {
        "rtms_official": 3,
        "rone_index_derived": 1,
        "public_assessment": 1
      },
      "source_means": {
        "rtms_official": 4383333333,
        "rone_index_derived": 4000000000,
        "public_assessment": 10769230769
      },
      "confidence_factors": {
        "distinct_sources": 3,
        "relative_spread": 1.21,
        "sample_count": 5,
        "ladder_reason": "single-source >= 5 samples"
      }
    }
  ],
  "_meta": {
    "service": "veacon",
    "api_version": "v1",
    "vertical": "real_estate",
    "data_sources": ["rtms_official"],
    "coverage_estimate": null,
    "coverage_estimate_method": "pending_kab_integration_phase_1_5",
    "coverage_note": "RTMS-reported transactions only. Industry research suggests 40-60% of actual Korean CRE sale transactions are publicly reported. Excluded: trust-vehicle transfers, partial-share transactions, SPV stock transfers, sub-30-day post-contract activity.",
    "lease_data_status": "not_mandated",
    "lease_data_note": "Korean commercial lease contracts have no reporting mandate. chartered_lease / monthly_lease aggregates derive from voluntarily reported subset only — interpret as directional, not market-representative.",
    "known_limitations": [
      "Reporting lag: 30-60 days median between contract and RTMS visibility",
      "Property heterogeneity: CRE units less standardized than residential",
      "No counterparty deduplication across related parties"
    ],
    "disclosure_url": "https://veacon.io/data-trust",
    "generated_at": "2026-04-26T10:00:00Z",
    "count": 1,
    "confidence": "medium",
    "source_mix": {
      "rtms_official": 3,
      "rone_index_derived": 1,
      "public_assessment": 1
    },
    "tier": "team",
    "auth_method": "api_key",
    "query": {
      "sigungu_code": "11680",
      "property_type": "office",
      "transaction_type": "sale",
      "period": "last_6m",
      "geo_precision": "sigungu",
      "dong": null
    },
    "rate_limit": {
      "limit_per_min": 200,
      "remaining": 199
    }
  }
}

필드 의미

data 배열의 각 row

  • sample_count — cohort 안의 거래 수. HAVING ≥ 2 로 quartile 의미가 약한 single-row cohort 는 응답에서 제외됩니다.
  • avg_price / p25_price / median_price / p75_price — 거래가 분포 (KRW). transaction_type='sale' 은 매매가, chartered_lease 는 전세금, monthly_lease 는 보증금.
  • avg_monthly_rent / p25/median/p75_monthly_rent — transaction_type='monthly_lease' 일 때만 값 존재 (월 임대료 KRW).
  • avg_area_m2 — 평균 면적 (전용/연면적, 출처별 정의 다름).
  • confidence — low / medium / high. Confidence Score 공식 참조.
  • source_mix — {source_type: count} per-cohort histogram. 어느 출처에서 sample 이 왔는지.
  • source_means — {source_type: avg_price} per-source 평균 가격.
  • confidence_factors — confidence 라벨의 reasoning 을 surface. relative_spread 는 (MAX(src_mean) - MIN(src_mean)) / AVG(price) — 출처 간 disagreement 의 정량화.

_meta 의 Layer 1 envelope (ADR-015)

매 응답에 부착되는 boundary disclosure. 한국 CRE 데이터의 구조적 한계를 표면화합니다 (자세한 내용은 /data-trust):

  • coverage_note — RTMS 신고 비율, 제외 거래 유형 명시.
  • lease_data_status — 상업용 임대 신고 의무 부재.
  • known_limitations — 신고 lag, 단위 비균일성, counterparty 식별 한계.
  • disclosure_url — 한 번 더 강조: https://veacon.io/data-trust.

응답 404 (no-match)

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No transactions match these parameters within the disclosed coverage.",
    "hint": "Call /api/v1/real-estate/dimensions to list available values."
  },
  "_meta": {
    /* same Layer 1 envelope as 200 */
  }
}

ADR-015 acceptance: 404 도 동일한 Layer 1 envelope 를 carry 합니다. cohort 가 비었다는 사실 자체가 disclosure context 안에서 의미 있어야 하기 때문.

응답 403 TIER_RESTRICTED

Starter tier 가 geo_precision=dong 으로 호출하면:

json
{
  "error": {
    "code": "TIER_RESTRICTED",
    "message": "geo_precision='dong' requires Pro tier or higher.",
    "current_tier": "starter",
    "required_tier": "pro",
    "upgrade_url": "https://veacon.io/pricing"
  }
}

curl 예시

bash
curl -G https://veacon.io/api/v1/real-estate/pulse \
  -H "X-API-Key: $VEACON_API_KEY" \
  --data-urlencode "sigungu_code=11680" \
  --data-urlencode "property_type=office" \
  --data-urlencode "transaction_type=sale" \
  --data-urlencode "period=last_6m"

다음 단계