📖 kw-platform-api マニュアル›連携レシピ

▮▮ 4. 連携レシピ

目的別のコピペで動く手順集です。事前に API キーの発行を済ませてください。
  1. Google スプレッドシート — 数式1つ（IMPORTDATA）
  2. Google Apps Script（GAS）— キーを隠して定期更新
  3. Python で分析する（pandas / Jupyter）
  4. 記事制作ツールに組み込む（コンテンツ分析の完全版）
  5. Looker Studio に出力する
  6. AI にコーディングを任せる（Claude Code 等）

4.1 Google スプレッドシート — 数式1つ（IMPORTDATA）

一番かんたんな方法です。セルに数式を貼るだけで、上位サイト表が読み込まれ、約1時間ごとに自動更新されます。

  1. スプレッドシートの空きセル（例: A1）を選択します
  2. 次の数式を貼り付け、市場名 と kwk_あなたのキー を書き換えます
=IMPORTDATA("https://<BASE_URL>/v1/export/csv?resource=market.report&name=市場名&table=sites&key=kwk_あなたのキー")
table= の値出力される表
sites上位サイト（順位・ドメイン・推計流入数・シェア%）
queries市場の全クエリと検索ボリューム
queryRanksサイト × クエリ順位の縦持ち（ピボット向き）
この方法はキーが URL・シートの数式に残ります。シートの共有範囲に注意してください。社外共有するシートでは次の GAS 方式（キーをスクリプトプロパティに隠す）を使ってください。

4.2 Google Apps Script（GAS）— キーを隠して定期更新

キーをシートに出さず、複数市場をまとめて取得し、トリガーで毎朝自動更新もできる方法です。

手順

  1. スプレッドシートのメニュー「拡張機能 → Apps Script」を開きます
  2. エディタに下のコードを貼り付けます（markets の市場名は自分のものに書き換え）
  3. 左メニューの歯車「プロジェクトの設定」→ 下部の「スクリプト プロパティ」→「スクリプト プロパティを追加」で、プロパティ名 KW_API_KEY・値 kwk_あなたのキー を保存します
  4. エディタに戻り、関数 watchMarkets を選んで「実行」（初回は権限の承認ダイアログが出ます）
  5. シートに「市場ウォッチ」タブが作られ、データが入れば成功です
  6. 自動更新したい場合は、左メニューの時計「トリガー」→「トリガーを追加」で watchMarkets を時間主導型（例: 毎日 朝8〜9時）に設定します
function watchMarkets() {
  const KEY = PropertiesService.getScriptProperties().getProperty("KW_API_KEY");
  const BASE = "https://<BASE_URL>";
  const markets = ["旅行"];   // 自分の市場名に書き換える
  const rows = [["市場名","調査週","順位","ドメイン","推計流入数","シェア%"]];
  for (const name of markets) {
    const r = UrlFetchApp.fetch(
      BASE + "/v1/query?resource=market.report&name=" + encodeURIComponent(name),
      { headers: { "X-API-Key": KEY }, muteHttpExceptions: true });
    if (r.getResponseCode() !== 200) continue;   // 404(市場名違い)等はスキップ
    const d = JSON.parse(r.getContentText());
    d.sites.forEach(s => rows.push([d.market.name, d.weekEnd, s.rank, s.domain, s.estClicks, s.shareRate]));
  }
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("市場ウォッチ")
             || SpreadsheetApp.getActiveSpreadsheet().insertSheet("市場ウォッチ");
  sheet.clearContents();
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}

他のデータ（全クエリ・セグメント・重要形態素など）も resource= を変えるだけで同じパターンで取れます。resource の一覧は「3. API リファレンス」を参照してください（GAS 用の汎用ヘルパー kwQuery() も掲載しています）。

4.3 Python で分析する（pandas / Jupyter）

キーを環境変数に置けば、ノートブックや分析スクリプトからそのまま使えます。

# 事前に: export KW_API_KEY=kwk_...
import os, httpx
import pandas as pd

BASE = "https://<BASE_URL>"
KEY = os.environ["KW_API_KEY"]

# パターンA: CSV を DataFrame に直読み（1行）
sites = pd.read_csv(f"{BASE}/v1/export/csv?resource=market.report"
                    f"&name=旅行&table=sites&key={KEY}")

# パターンB: JSON で細かく制御（URL は /v1/query 1本、resource で切り替え）
r = httpx.get(f"{BASE}/v1/query",
              params={"resource": "market.report", "name": "旅行"},
              headers={"X-API-Key": KEY})
r.raise_for_status()
report = r.json()
queries = pd.DataFrame(report["queries"])   # 全クエリ×ボリューム
top = queries.nlargest(10, "volume")        # あとは普通の pandas 分析

4.4 記事制作ツールに組み込む（コンテンツ分析の完全版）

「注目市場の取り込み → 対策クエリのコンテンツ分析 → 重要形態素と競合情報の読み込み」を自社ソフトに組み込む完全版です。骨格は API リファレンスの標準フローと同じで、実運用で必要になるエラーハンドリング（既存分析の scId 照合・回数上限）を足しています。SDK は不要、必要なのは API キー1本です。

# 事前に: export KW_API_KEY=kwk_... / export KW_BASE_URL=https://<BASE_URL>
import os
import time

import httpx

BASE = os.environ["KW_BASE_URL"]
H = {"X-API-Key": os.environ["KW_API_KEY"]}


def q(resource: str, **params):
    r = httpx.get(f"{BASE}/v1/query", params={"resource": resource, **params},
                  headers=H, timeout=60)
    r.raise_for_status()
    return r.json()


# ① 注目市場を取り込む（searchConditionId は分析結果とセットで保存する）
markets = q("myMarkets.groupMarkets", groupId=-1)["markets"]
market = next(m for m in markets if m["name"] == "旅行")
sc_id = market["searchConditionId"]

# ② 市場のクエリから対策キーワードを選ぶ
queries = q("market.queries", name=market["name"])["queries"]
query = queries[0]["query"]

# ③ 分析の有無を確認し、無ければ開始して完了を待つ
# 既存分析は過去世代の scId に紐づいていることがあるため、まず分析済み一覧で照合する
known = next((f for f in q("contentAnalysis.files")["files"]
              if f["searchWord"] == query), None)
if known:
    sc_id = known["searchConditionId"]    # 既存分析はそのファイルの scId で照会する
st = q("contentAnalysis.status", marketId=sc_id, query=query)
if st["status"] == "not_analyzed":
    res = q("contentAnalysis.request", marketId=sc_id, query=query)  # 分析開始
    if not res["accepted"]:           # over_limit = 1日の回数上限
        raise RuntimeError(f"analysis not accepted: {res['result']}")
while st["status"] != "researched":   # 通常10〜20分、空いていれば1分程度
    time.sleep(20)
    st = q("contentAnalysis.status", marketId=sc_id, query=query)
file_id = st["fileId"]

# ④ 重要形態素（業界特有度キーワード）を読み込む
kw = q("contentAnalysis.keywords", fileId=file_id, minSites=6, limit=100)
for k in kw["keywords"][:10]:
    print(k["term"], k["industryScore"], f'{k["siteCount"]}/{kw["pageCount"]}サイト')

# ⑤ 競合情報を読み込む
detail = q("contentAnalysis.detail", fileId=file_id)
for page in detail["pages"]:          # 検索上位10ページのページ単位スコア
    print(page["url"], page["contentsScore"], page["portalScore"], page["uniqueScore"])

report = q("market.report", name=market["name"])
for site in report["sites"][:10]:     # 市場レベルの競合サイト（順位・推定流入）
    print(site["rank"], site["domain"], site["estClicks"])

Node.js（同じ流れ）

const BASE = process.env.KW_BASE_URL;
const H = { "X-API-Key": process.env.KW_API_KEY };

const q = async (resource, params = {}) => {
  const url = new URL(BASE + "/v1/query");
  url.searchParams.set("resource", resource);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
  const r = await fetch(url, { headers: H });
  if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
  return r.json();
};

const { markets } = await q("myMarkets.groupMarkets", { groupId: -1 });
const market = markets.find((m) => m.name === "旅行");
const scId = market.searchConditionId;
const query = "ハワイ旅行 費用";

let st = await q("contentAnalysis.status", { marketId: scId, query });
if (st.status === "not_analyzed") {
  const res = await q("contentAnalysis.request", { marketId: scId, query });  // 分析開始
  if (!res.accepted) throw new Error(`analysis not accepted: ${res.result}`);
}
while (st.status !== "researched") {
  await new Promise((r) => setTimeout(r, 20000));
  st = await q("contentAnalysis.status", { marketId: scId, query });
}

const kw = await q("contentAnalysis.keywords", { fileId: st.fileId, minSites: 6, limit: 100 });
const detail = await q("contentAnalysis.detail", { fileId: st.fileId });   // 競合ページ情報 (pages[])

組み込み時の注意（実測済みの挙動）

項目内容
scId の世代分析データはリクエスト時の scId に紐づく。市場の scId は調査世代で変わるため、request に使った scId を分析結果とセットで保存し、status 照会は同じ scId で行う
回数上限分析リクエストは1日あたりの上限あり。result: "over_limit" をハンドリングし、翌日リトライやキュー化を推奨
所要時間非同期で通常10〜20分（空いていれば1分程度）。同期待ちにせずポーリング（10〜30秒間隔）で
表示期限分析結果は validUntil（分析日+28日）で期限切れ。キャッシュする場合は再分析を考慮
キャッシュ市場データは週次更新。同一週内の再取得はソフト側キャッシュを推奨（課金対象は成功したデータ取得コール）

4.5 Looker Studio に出力する

Looker Studio は Google シートをデータソースにできるため、CSV → シート → Looker Studio が最短経路です。

  1. 4.1（IMPORTDATA）または 4.2（GAS + トリガー）でシートにデータを流し込む
  2. Looker Studio で「データを追加」→「Google スプレッドシート」→ 該当シートを選択
  3. 順位表・推移グラフ等を作成（シートが自動更新されればレポートも追随します）

大量データ・多市場の本格運用では BigQuery 連携を計画しています（要望があれば管理者まで）。

4.6 AI にコーディングを任せる（Claude Code / Cursor 等）

この API は、AI コーディングエージェントに読ませるための仕様書を2種類配信しています。URL を指示文に入れて渡すだけで、AI が仕様を読み取って組み込みコードを書きます。

読ませる URL使い分け
https://<BASE_URL>/llms.txt仕様の要約1枚（プレーンテキスト）。まずはこちら。認証・全リソース・標準フロー・実装上の注意が短くまとまっています
https://<BASE_URL>/manual/api本マニュアルの詳細リファレンス。パラメータ表・レスポンス例まで必要な込み入った実装のとき

指示文の例（コピペして市場名・要件を書き換え）

https://<BASE_URL>/llms.txt を読んで、この API を使って
「担当市場の上位サイト一覧を表示するページ」を管理画面に追加して。
API キーは環境変数 KW_API_KEY から読むこと。キーをブラウザ側に出さないこと。
https://<BASE_URL>/manual/api を読んで、
「注目市場ごとに対策キーワードのコンテンツ分析を回し、業界特有度キーワード
（重要形態素）上位20語を DB に保存するバッチ」を Python で書いて。
分析は非同期なのでポーリングし、over_limit と 429 はリトライキューに積むこと。

AI に実装させるときのチェックリスト

なお、コードを書かずに試したいだけなら、ダッシュボードの「API サポート」（日本語で要望を書くと取得コードを生成する機能）や自然言語エージェント（POST /v1/agent・β）も使えます。

← 3. API リファレンス 5. 料金・トラブル →

問い合わせ: kw-platform-api 管理者まで。 ← ダッシュボードへ戻る

▲ 先頭へ