# kw-platform-api

kwtool のマーケット・キーワード・コンテンツ分析データを提供する API ゲートウェイ。
この文書は AI コーディングエージェント (Claude Code 等) が組み込み実装するための仕様要約。

## 認証
- 全リクエストに API キーを付与する: ヘッダー `X-API-Key: <key>`
  - API キー `kwk_...`: 利用者がダッシュボード「API キー」画面から自己発行する
    不透明キー（管理者の利用許可が前提）。プラン別にスコープ・月次上限・
    レート制限があり、個別失効・有効期限・ローテーションに対応（推奨）
  - gateway キー `gwk_...`: ダッシュボード/内部向けのステートレスキー
  - ヘッダーを付けられない場合のみクエリ `?key=<key>` も可（外販キーは
    不透明値なので URL に出ても認証情報は復元されないが、ヘッダー推奨）
- キーは秘匿情報。コードに直書きせず環境変数 (例: KW_API_KEY) で扱うこと

## エンドポイント: 単一URL (これだけ使えばよい)
GET /v1/query?resource=<resource>&<params...>
- レスポンスは JSON。エラーは {"detail": "..."} と HTTP ステータス
- 同じ内容を POST /v1/query に {"resource": "...", "params": {...}} でも可
- resource 一覧 (機械可読): GET /v1/query/resources
- ここに書かれていない resource・エンドポイントを推測で使わないこと
- 詳細な入出力仕様 (パラメータ表・レスポンス例) が必要なら GET /manual/api を読む

resource:
- calendar.latestWeek  params なし → {"weekEnd": "YYYY-MM-DD"} 最新の有効調査週 (疎通確認にも最適)
- market.report    params: name (市場名/完全一致), weekEnd?, sites?(上位N,default20)
  → { market, weekEnd, queries[{query,volume,economicScale}],
      sites[{rank,domain,title,estClicks,flowRate,shareRate,queryRanks[]}], warnings[] }
- market.queries   params: name, weekEnd? → 全クエリと検索ボリュームのみ
- market.search    params: queries (複数指定可), weekEnd? → 市場の検索
- market.segments  params: marketId, plan? → カテゴリ別クエリ内訳
- market.segmentPlans  params: marketId → セグメント計画一覧 (planId を segments の plan に渡す)
- contentAnalysis.files  params: marketId?, projectId? → 分析済み一覧 (fileId の供給源)。
    レスポンスは {"files": [...], "result": "ok"} の包み構造 (配列は files キーの中)。
    各行: searchWord (対策キーワード), searchConditionId (その分析の市場ID),
    contentsAnalysisFileId (= fileId), status ("researched"=完了 / "rank_researching"=調査中),
    researchDate, validUntil (表示期限)。
    注意: linkAnalysisStatus は別機能「複ページ分析(リンク分析)」の状態で、コンテンツ分析の
    完了とは無関係 ("未分析" でも status が researched ならコンテンツ分析は使える)
- contentAnalysis.detail params: fileId → 分析詳細 (pages[] に上位10ページの競合情報:
    url, contentsScore, portalScore, uniqueScore, purity, contents(見出し・本文構造))
- contentAnalysis.status params: marketId, query → 分析状態
    {status: "not_analyzed"|"rank_researching"|"researched", fileId}
- contentAnalysis.request params: marketId, query (POST) → 分析を開始 (非同期・通常10-20分、
    1日の回数上限あり: result="over_limit")。完了は status のポーリングで確認
- contentAnalysis.keywords params: fileId, minSites?, minIndustryScore?, limit?
    → 業界特有度キーワード(重要形態素)。{term, industryScore(業界特有度),
    generalScore(一般度), siteCount(上位ページ中の出現サイト数), occurrences} を特有度降順で返す
- contentAnalysis.characters params: fileId, projectId? → ページ特性 (見出し構造等・パススルー)
- myMarkets.groups / myMarkets.groupMarkets (groupId, -1=全て, weekEnd?) / myMarkets.home
  / mySites.list / mySites.tags / projects.list / projects.detail (projectId)
  / projects.markets (projectId)
  → 認証アカウント固有のデータ (myMarkets.groupMarkets の各要素:
    name=市場名, searchConditionId=市場ID, volume, wordCount)。書き込みは提供しない
- gateway.me  params なし → 認証アカウントの情報 (キーがどのアカウントかの確認)
- insights.weekly  params: name (市場名/完全一致), weekEnd?, sites?
  → 前週比較の差分データ (changes) と LLM 生成の日本語要約 (summary)。
    前週データが無い週はスナップショット要約に縮退 (warnings[] 参照)

## 記事制作ツール連携の標準フロー (実測済み)
1. myMarkets.groupMarkets (groupId=-1) で注目市場を取得 → searchConditionId を保存
2. market.queries (name) で対策クエリを選定
3. contentAnalysis.status (marketId, query) で分析有無を確認
4. not_analyzed なら contentAnalysis.request で分析開始 → status を10-30秒間隔でポーリング
5. researched になったら contentAnalysis.keywords (fileId, minSites=6) で重要形態素、
   contentAnalysis.detail (fileId) で競合ページ情報を取得
注意: 分析データは「リクエスト時の searchConditionId」に紐づく (市場の scId は調査世代で
変わるため、request に使った scId を保存して status 照会に使う)。分析結果の表示期限は
分析日+28日 (validUntil)。

## 自然言語エージェント (β)
POST /v1/agent  body: {"message": "日本語の要望", "allowActions": false}
→ {answer, actions[], needsConfirmation, llm}
サーバー側の Claude が適切な resource を組み立てて実行し日本語で回答する。
分析開始 (状態変更) は allowActions=true の時のみ実行され、省略時は提案として返る。

## CSV エクスポート (スプレッドシート/BI 向け)
GET /v1/export/csv?resource=market.report&name=<市場名>&table=sites|queries|queryRanks&key=kwk_...

## 実装上の注意
- データは週次更新。同一週内の再取得はキャッシュを推奨
- market.report は部分成功あり (warnings[] を確認)。該当なしは 404
- 課金対象は成功したデータ取得コール (2xx)。/v1/query は 1リクエスト=1コール
- 外販キー (kwk_) にはプラン別のレート制限 (分単位) と月次上限がある。
  超過時は HTTP 429 ({"detail": "rate limit exceeded" | "monthly quota exceeded"})。
  429 は Retry-After を尊重し、直列・低頻度アクセスにすること
- スコープ外の resource は HTTP 403 ({"detail": ..., "requiredScope": ...})
- 使用量の確認: GET /v1/usage (granularity=day|week|month)

## 例 (Python)
import os, httpx
r = httpx.get("https://api.kwtool-ai.com/v1/query",
              params={"resource": "market.report", "name": "旅行"},
              headers={"X-API-Key": os.environ["KW_API_KEY"]})
r.raise_for_status()
report = r.json()