Quickstart (5-min)

5분 안에 Veacon API 첫 호출까지. 키 발급 → curl → 응답 해석.

Last updated: 2026-06-12

전제

  • 웹 브라우저
  • 터미널 (Mac Terminal / Windows PowerShell / Linux bash)
  • 이메일 주소 (Veacon 계정 생성용)

총 소요 시간: 약 5분

1단계. API Key 발급 (1분)

  1. veacon.io 방문 → 우상단 Sign in 클릭
  2. 로그인 또는 무료 회원가입 (Google 또는 이메일 · 결제 정보 불필요)
  3. /dashboard 이동 → Starter 플랜 API Key 자동 발급
  4. 키 전체를 Copy (아래와 같은 형식):
veacon_pk_live_a3c9e2f8b4...

API Key 는 발급 직후 1회만 평문 노출됩니다. 닫으면 다시 볼 수 없으니 안전한 곳(1Password, .env 등)에 저장하세요.

2단계. 첫 호출 (1분)

터미널에서 아래 명령을 실행합니다. veacon_pk_live_... 을 발급받은 실제 키로 교체. 강남구 (sigungu_code=11680) 오피스 매매 실거래 분포를 조회합니다.

bash
curl -H "X-API-Key: veacon_pk_live_..." \
  "https://veacon.io/api/v1/real-estate/pulse?sigungu_code=11680&property_type=office&transaction_type=sale"

3단계. 응답 해석 (3분)

정상 응답 예시 (일부 필드 생략 — 전체 스키마는 API Reference):

json
{
  "data": [
    {
      "sigungu_code": "11680",
      "sigungu": "서울특별시 강남구",
      "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_area_m2": "250.77",
      "confidence": "medium",
      "source_mix": {
        "rtms_official": 3,
        "rone_index_derived": 1,
        "public_assessment": 1
      }
    }
  ],
  "_meta": {
    "service": "veacon",
    "api_version": "v1",
    "vertical": "real_estate",
    "data_sources": ["rtms_official"],
    "coverage_note": "RTMS-reported transactions only. ...",
    "generated_at": "2026-06-12T10:00:00Z",
    "count": 1,
    "confidence": "medium",
    "auth_method": "api_key",
    "rate_limit": { "limit_per_min": 10, "remaining": 9 }
  }
}

핵심 필드 해석

필드의미사용 예
median_price거래가 중앙값 (KRW). avg 와 큰 차이면 편향된 분포 의미강남구 오피스 매매 중앙값 41.5억
p25_price / p75_price하위 25% / 상위 25% 경계박스플롯, 사분위 범위
sample_countcohort 안의 거래 수5 — 표본이 작으면 confidence 강등
source_mix출처별 표본 비중 (RTMS / R-ONE / 공시지가)IC 메모에 출처 표기로 그대로 인용
confidence다중 출처 합의 기반 신뢰도low/medium/high — Confidence Score 참조
_meta.coverage_note데이터 커버리지 한계 명시보고서 각주(caveat)에 활용

응답 헤더 — 쿼터 확인

헤더의미
X-Quota-Limit월 호출 한도 (플랜별)
X-Quota-Used이번 달 사용량
X-Quota-Resets-At다음 리셋 UTC 시각
X-RateLimit-Limit분당 호출 한도
X-RateLimit-Remaining현재 분에 남은 호출 수

실패 케이스

401 Unauthorized

  • API Key 누락 또는 오타. X-API-Key 헤더 다시 확인.

402 Quota Exceeded

  • 월 호출 한도 초과. resets_at 시각에 자동 리셋되거나 Pricing 에서 플랜 업그레이드.

429 Rate Limited

  • 분당 호출 제한 초과. 응답의 Retry-After 초만큼 대기 후 재시도.

400 Invalid Params

  • sigungu_code, property_type, transaction_type 형식 오류. sigungu_code 는 5자리 행정코드입니다.

404 Not Found

  • 해당 조합에 데이터 없음. /api/v1/real-estate/dimensions 로 가능한 조합을 먼저 조회하세요.

자세한 에러 목록은 Errors 를 참조.

다음으로