판을 코드로 읽는다

3분 시작

• 1로그인 후 계정에서 API 키 발급 — 무료 계정도 됩니다
• 2아래 curl 을 복사해 키만 바꿔 실행
• 3JSON 이 오면 끝 — 무료는 하루 100회, Pro는 분당 120회

요금

• Free하루 100회 · 개인·평가용
• Pro분당 120회 · 월 14,900원
• Developer상용 서비스 탑재 허가 · 월 10만 회 · 메일 SLA — 월 49,000원, 도입 문의: [email protected]
• Enterprise전 기간 과거 데이터 · 맞춤 리포트(주간/월간 PDF) · 전용 알림 채널 · 팀 좌석 · 화이트라벨 — 견적 문의: [email protected]

인증과 한도

키는 계정 화면에서 발급합니다. 발급 직후 한 번만 전체가 표시되니 바로 보관하세요. 모든 요청에 아래처럼 붙입니다.

Authorization: Bearer ktb_xxxxxxxxxxxxxxxx

지금 계정으로 하루 100회까지 바로 쓸 수 있습니다. 상용 트래픽이면 Pro(분당 120회) →

GET /api/v1/sample 열쇠 없이

가입도 키도 없이 지금 바로 됩니다. 상위 다섯 줄이라 쓸 만큼은 아니지만, 응답이 어떻게 생겼는지는 다 보입니다 — 붙일지 말지는 그다음에 정하세요.

curl https://www.koreatrendboard.com/api/v1/sample

응답 형식은 JSON Schema 로도 드립니다 — /api/v1/schema. 코드 생성기나 검증기에 그대로 넣으실 수 있습니다.

브라우저에서 바로 열어도 됩니다. CORS 를 열어 뒀으니 fetch 로도 그대로 됩니다.

무료 키를 받으면 열 줄과 지난 기록까지 열립니다. 계단이 셋인 이유는 각 칸에 이유가 있기 때문입니다 — 맛보기는 모양을 보는 자리, 무료는 붙여 보는 자리, 유료는 쓰는 자리입니다.

GET /api/v1/trends

현재 시황판 전체(최대 200위)를 돌려줍니다. 5분마다 갱신됩니다.

curl -H "Authorization: Bearer ktb_..." \
  https://www.koreatrendboard.com/api/v1/trends

{
  "ok": true,
  "capturedAt": "2026-08-26T07:30:00.000Z",
  "rows": [
    { "rank": 1, "keyword": "전현무", "score": 45.0,
      "delta": 2.1, "sources": ["google", "youtube"] }
  ]
}

GET /api/feed

RSS·JSON 피드입니다. locale 은 ko·en·ja, format=json 이면 JSON Feed 1.1 로 줍니다. 키 없이 20위까지 무료입니다.

GET https://www.koreatrendboard.com/api/feed?locale=ko
GET https://www.koreatrendboard.com/api/feed?locale=en&format=json

key 파라미터에 API 키를 붙이면 60위까지 늘고 조기경보가 함께 실립니다 — 아직 판에 안 뜬 것을 먼저 받습니다. 키가 없거나 틀리면 무료 피드로 돌아갑니다(구독이 끊기지 않도록).

GET https://www.koreatrendboard.com/api/feed?locale=ko&key=YOUR_KEY

GET /api/v1/history

키워드 하나의 점수 시계열을 돌려줍니다. hours 는 기본 168(7일), 최대 4320(180일)입니다.

curl -H "Authorization: Bearer ktb_..." \
  "https://www.koreatrendboard.com/api/v1/history?keyword=%ED%95%98%EC%9D%B4%EB%B8%8C&hours=720"

{
  "ok": true,
  "keyword": "하이브",
  "hours": 720,
  "points": [
    { "capturedAt": "2026-08-25T10:00:00.000Z", "score": 27.6, "rank": 10 }
  ]
}

GET /api/v1/backfill

기간을 통째로 하루 단위로 묶어 돌려줍니다. keywords 를 비우면 그 구간에 오른 것 전부입니다. Pro 92일 · 무료 7일.

curl -H "Authorization: Bearer ktb_..." \
  "https://www.koreatrendboard.com/api/v1/backfill?from=2026-07-01&to=2026-07-31&format=csv"

{
  "ok": true,
  "from": "2026-07-01",
  "to": "2026-07-31",
  "days": 31,
  "count": 1842,
  "rows": [
    { "day": "2026-07-01", "keyword": "하이브", "bestRank": 4, "avgScore": 31.2, "appearances": 61 }
  ]
}

Pro 는 최근 92일까지 받으실 수 있습니다. 그보다 앞선 기록이 필요하시면 전 기간 데이터를 따로 드립니다 — [email protected]

GET /api/v1/insights

급상승·급락·판 교체율을 한 번에 돌려줍니다. limit 은 기본 20, 최대 100입니다.

curl -H "Authorization: Bearer ktb_..." \
  "https://www.koreatrendboard.com/api/v1/insights?limit=20"

{
  "ok": true,
  "generatedAt": "2026-08-26T01:40:00.000Z",
  "surges": [
    { "keyword": "하이브", "rank": 6, "prevRank": 14, "rankJump": 8, "score": 31.2 }
  ],
  "fallers": [],
  "turnover": { "turnoverRate": 12.5, "entered": [], "exited": [] }
}

GET /api/v1/daily

키워드 하나의 일 단위 장기 이력을 돌려줍니다. days 는 기본 90, 최대 730입니다. 최근 구간은 5분 회차를 일자로 집계한 값이고, 그 이전은 일 단위 롤업입니다 — 두 구간이 같은 모양으로 나가므로 경계를 신경 쓸 필요가 없습니다.

curl -H "Authorization: Bearer ktb_..." \
  "https://www.koreatrendboard.com/api/v1/daily?keyword=%ED%95%98%EC%9D%B4%EB%B8%8C&days=365"

{
  "ok": true,
  "keyword": "하이브",
  "days": 365,
  "points": [
    { "day": "2026-03-14", "bestRank": 3, "peak": 52.8 }
  ]
}

판에 오르지 않은 날은 행이 없습니다 — 없는 날짜를 0으로 채워 보내지 않습니다.

한도와 규칙

키당 분당 120회 요청까지 받습니다. 초과하면 429가 나가고 잠시 후 다시 받습니다. v1 응답의 필드 이름과 형태는 예고 없이 바꾸지 않습니다 — 바꿔야 할 일이 생기면 v2를 새로 엽니다.

401 = 키 없음/무효 · 402 = Pro 아님 · 429 = 한도 초과