Quickstart (5-min)

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

Last updated: 2026-04-23

전제

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

총 소요 시간: 약 5분

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

  1. veacon.io 방문 → 우상단 Sign in 클릭
  2. Syncle 계정으로 로그인 (없으면 syncle.ai.kr/signup 가입 — 무료)
  3. /dashboard 이동 → Starter 플랜 API Key 자동 발급
  4. 키 전체를 Copy (아래와 같은 형식):
veacon_pk_live_a3c9e2f8b4...

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

2단계. 첫 호출 (1분)

터미널에서 아래 명령을 실행합니다. veacon_pk_live_... 을 발급받은 실제 키로 교체.

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

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

정상 응답 예시:

json
{
  "data": [
    {
      "region": "강남권",
      "category": "office",
      "period": "2026-01",
      "product_type": "rental",
      "avg_price": 2577493.75,
      "median_price": 1530000.00,
      "price_p25": 537500,
      "price_p75": 2774925,
      "sample_size": 16,
      "total_views": 1112,
      "demand_index": 613.69,
      "confidence": "medium"
    }
  ],
  "_meta": {
    "service": "veacon",
    "api_version": "v1",
    "generated_at": "2026-04-23T10:00:00Z",
    "count": 1,
    "confidence": "medium",
    "auth_method": "api_key",
    "rate_limit": { "limit_per_min": 60, "remaining": 59 }
  }
}

핵심 필드 해석

필드의미사용 예
avg_price평균 임대료 (월세, 원 단위)강남권 2026-01 오피스 평균 약 258만원
median_price중간값. avg 와 큰 차이면 편향된 분포 의미평균 258만원 vs 중간값 153만원 → 고가 이상치 존재
price_p25 / price_p75하위 25% / 상위 25% 경계박스플롯 만들 때 사용
sample_size집계된 매물 수16 — 중간 신뢰도 구간
demand_index수요 지수, 100 = 카테고리 평균613.69 → 카테고리 평균의 6배 수요
confidence샘플 기반 신뢰도low/medium/high — Data Dictionary 참조

응답 헤더 — 쿼터 확인

헤더의미
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

  • region, category, period 형식 오류. period 는 YYYY-MM 형식이어야 합니다.

404 Not Found

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

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

다음으로