키워드마스터 API 문서

키워드 검색량·CPC 조회부터 키마비키 챌린지 관리까지, 키워드마스터의 데이터와 기능을 외부 프로그램에서 그대로 사용할 수 있는 REST API 레퍼런스입니다. API v2

1. 개요

모든 응답은 공통 구조를 가집니다.

// 성공
{ "success": true, "data": { ... }, "meta": { "api_version": "v2", "tier": "platinum", "timestamp": "..." } }

// 실패
{ "success": false, "error": "ERROR_CODE", "message": "사람이 읽는 설명" }

2. 인증

API 키는 마이페이지 → API에서 발급합니다. 모든 요청에 키를 포함하세요.

# 헤더 방식 (권장)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://keywordmaster.net/api/v2/?action=search&keyword=키마비키"

# 쿼리 파라미터 방식
curl "https://keywordmaster.net/api/v2/?action=search&keyword=키마비키&api_key=YOUR_API_KEY"

3. 플랜별 권한

4. 키워드 API

5. 키마비키 챌린지 API PLATINUM+

키마비키 챌린지(7vs3 키워드 수익화 챌린지)를 코드로 운영합니다. 참가 신청, 배정 키워드 조회, 결과물 URL·수익 인증 제출, 점수/랭킹 조회까지 전 과정을 자동화할 수 있습니다. 모든 엔드포인트는 challenge 스코프와 플래티넘 이상 플랜이 필요합니다.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"season_type":"7day"}' \
  "https://keywordmaster.net/api/v2/?action=challenge.join"

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"keyword_id":1234,"url":"https://blog.example.com/post","income_amount":120000}' \
  "https://keywordmaster.net/api/v2/?action=challenge.submit"

응답 예시 — challenge.status

{
  "success": true,
  "data": {
    "active": true,
    "room_id": 42,
    "season_title": "도전7일",
    "current_day": 3,
    "team_a_score": 120, "team_b_score": 90,
    "me": { "member_id": 511, "nickname": "키마a1b2", "team": "a", "role": "lieutenant",
            "total_score": 40, "submitted_count": 4, "missed_count": 1 },
    "members": [ { "member_id": 510, "nickname": "...", "team": "a", "role": "leader", ... } ]
  },
  "meta": { "api_version": "v2", "tier": "platinum" }
}

6. 에러 코드

7. 코드 예제

Python — 챌린지 자동 참가 + 제출

import requests

BASE = "https://keywordmaster.net/api/v2/"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# 1) 7일 챌린지 참가
requests.post(BASE, params={"action": "challenge.join"}, headers=H, json={"season_type": "7day"})

# 2) 오늘 배정 키워드 조회
kw = requests.get(BASE, params={"action": "challenge.keywords"}, headers=H).json()
for k in kw["data"]["keywords"]:
    if not k["submitted"]:
        # 3) 결과물 URL 제출
        requests.post(BASE, params={"action": "challenge.submit"}, headers=H, json={
            "keyword_id": k["keyword_id"],
            "url": f"https://blog.example.com/{k['keyword']}",
            "income_amount": 0,
        })

# 4) 현황 확인
print(requests.get(BASE, params={"action": "challenge.status"}, headers=H).json())

PHP

$base = "https://keywordmaster.net/api/v2/";
$ch = curl_init($base . "?action=challenge.status");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_API_KEY"],
]);
$res = json_decode(curl_exec($ch), true);