GET /markets/pulse

지역 × 카테고리 × 기간 조합별 시세·수요 집계. Veacon 의 primary endpoint.

Last updated: 2026-04-23

지역 × 카테고리 × 기간 조합별 시세·수요 지표를 반환합니다.

GET https://veacon.io/api/v1/markets/pulse

인증

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

쿼리 파라미터

이름	필수	타입	예시	설명
`region`	필수	string	`강남권`	집계 권역. 가능한 값은 /markets/dimensions 로 조회
`category`	필수	string	`office`	공간 카테고리 — `office`, `meeting_room`, `warehouse`, `retail`, `studio`, `share_office`, `event_space`, `party_room`, `residence`, `other`
`period`	필수	string	`2026-01`	`YYYY-MM` 형식의 월
`product_type`	선택	string	`rental`	`rental` 또는 `meeting`. 미지정 시 전체 결합

응답 200

json

{
  "data": [
    {
      "region": "강남권",
      "category": "office",
      "period": "2026-01",
      "product_type": "rental",
      "avg_price": 2577493.75,
      "median_price": 1530000.00,
      "min_price": 180000.00,
      "max_price": 12600000.00,
      "price_p25": 537500.00,
      "price_p75": 2774925.00,
      "sample_size": 16,
      "total_views": 1112,
      "total_bookings": 0,
      "demand_index": 613.69,
      "booking_conv_rate": 0.0000,
      "occupancy_proxy": 0.0000,
      "confidence": "medium"
    }
  ],
  "_meta": {
    "service": "veacon",
    "api_version": "v1",
    "generated_at": "2026-04-23T10:00:00Z",
    "count": 1,
    "confidence": "medium",
    "auth_method": "api_key",
    "query": {
      "region": "강남권",
      "category": "office",
      "period": "2026-01",
      "product_type": null
    },
    "rate_limit": {
      "limit_per_min": 60,
      "remaining": 59
    }
  }
}

응답 필드

각 지표의 정확한 계산식과 해석 방법은 Data Dictionary / Metrics 에서 상세히 다룹니다. 여기서는 핵심만:

필드	타입	설명
`avg_price`	number \| null	평균 (discounted_price 우선 COALESCE)
`median_price`	number \| null	중간값 (P50)
`min_price` / `max_price`	number \| null	극값. 이상치 탐지용
`price_p25` / `price_p75`	number \| null	25/75 percentile
`sample_size`	integer	매물 수. k-anonymity ≥ 3 강제
`total_views`	integer	집계 기간 내 조회 수 합계
`total_bookings`	integer	예약 수 합계
`demand_index`	number \| null	카테고리 평균 대비 수요 (100 = 평균)
`booking_conv_rate`	number \| null	`total_bookings / total_views`
`occupancy_proxy`	number \| null	점유율 근사 (0.0 ~ 1.0)
`confidence`	`low` / `medium` / `high`	Data Dictionary / Confidence

응답 헤더

헤더	예시	의미
`X-Quota-Limit`	`100000`	월 호출 한도
`X-Quota-Used`	`17`	이번 달 사용량 (성공 호출만 카운트)
`X-Quota-Resets-At`	`2026-05-01T00:00:00.000Z`	다음 리셋 UTC 시각
`X-RateLimit-Limit`	`60`	분당 호출 한도
`X-RateLimit-Remaining`	`59`	현재 분에 남은 호출 수

에러

Status	Code	원인
400	`INVALID_PARAMS`	파라미터 누락/형식 오류
401	`UNAUTHORIZED`	인증 실패
402	`QUOTA_EXCEEDED`	월 쿼터 소진
404	`NOT_FOUND`	해당 조합 데이터 없음
429	`RATE_LIMITED`	분당 한도 초과
500	`QUERY_FAILED` / `INTERNAL`	서버 내부 오류

전체 에러 매트릭스는 Errors 참조.

예제

curl

bash

curl -H "X-API-Key: veacon_pk_live_..." \
  "https://veacon.io/api/v1/markets/pulse?region=강남권&category=office&period=2026-01&product_type=rental"

Node.js

const res = await fetch(
  `https://veacon.io/api/v1/markets/pulse?region=${encodeURIComponent('강남권')}&category=office&period=2026-01`,
  { headers: { 'X-API-Key': process.env.VEACON_API_KEY } },
);
const { data } = await res.json();
console.log(data[0].avg_price);

Python

python

import requests
import pandas as pd

r = requests.get(
    "https://veacon.io/api/v1/markets/pulse",
    headers={"X-API-Key": "veacon_pk_live_..."},
    params={"region": "강남권", "category": "office", "period": "2026-01"},
)
r.raise_for_status()
df = pd.DataFrame(r.json()["data"])
print(df[["avg_price", "median_price", "demand_index", "confidence"]])

더 많은 SDK 예제는 SDKs 참조.