メインコンテンツまでスキップ

QA ZERO API

概要​

QA ZERO REST API を使うと、QA ZERO の分析データにプログラムからアクセスできます。シンプルで構造化されたクエリ言語（QAL）を使って、ページビューデータ、Search Console のメトリクス、行動分析データを問い合わせられます。

ベース URL:

/wp-json/qa-platform/

利用可能なエンドポイント:

  • /qa-platform/guide - API ドキュメントとサーバー情報を取得
  • /qa-platform/query - QAL クエリを実行

なぜ QA ZERO API なのか？​

  • シンプルで構造化されている: QAL は分析データを曖昧さなく問い合わせる明確な手段を提供します
  • WordPress ネイティブ: WordPress REST API とアプリケーションパスワードを利用します
  • カラム指向: 大規模なデータセットに対して高速にクエリできます
  • AI フレンドリー: AI ツールや MCP サーバーとの統合が容易になるよう設計されています

バージョニング戦略​

QA ZERO は従来の v1、v2 といった番号付けの代わりに、カレンダーベースのバージョニングを採用しています。

なぜカレンダーバージョニングなのか？​

GitHub のアプローチに倣い、API の自然な進化を表現するために日付（YYYY-MM-DD）を使用します。

  • 明確なタイムライン: 機能がいつ導入されたかを理解しやすい
  • 非線形な進化: 破壊的変更があっても完全なバージョン番号の切り上げを強制しない
  • 長期サポート: 各バージョンは最低 24 ヶ月間メンテナンスされます
  • 自然な命名: v1 と v2 と v3 の混乱がない

バージョンの指定方法​

任意のエンドポイントに version クエリパラメーターを追加します。

GET /qa-platform/guide?version=2026-05-11

デフォルトの挙動（QA ZERO）​

version パラメーターが省略された場合、QA ZERO は信頼性と後方互換性を最大化するため、最も古い安定バージョンを使用します。これにより、新しいバージョンがリリースされても既存の連携がそのまま動作し続けます。

例:

GET /qa-platform/query
# 最も古い安定バージョンを使用します（現在は 2025-10-20）。
# 現行リリースを明示的に選ぶ場合は ?version=2026-05-11 を指定してください。

なぜ最も古いバージョンなのか？ QA ZERO はシステム連携のための信頼できるデータウェアハウスとして機能し、新機能よりも安定性を優先します。

利用可能なバージョン​

2026-05-11（Current）​

ステータス: ✅ Released 必要なプラグインバージョン: 3.0.0.0+ サポート期限: 2028-05-11（最低）

2025-10-20 からの変更（破壊的変更）:

  • calc 列宣言の対称化 — calc 式の中の material.column 参照は、from 側でも join.with 側でも fetch + preserve のトリガーになります。join 側 calc がサイレントに 0 を返していたバグが解消されます。
  • 新しいバリデータエラー E_CALC_COLUMN_UNRESOLVED が、不正な calc 参照をサイレントに 0 行を返す代わりにバリデーション時に拒否します。
  • E_INVALID_JOIN が構造化 details（side、received_value、expected_prefix、hint）を返し、on.left / on.right のピンポイント・スコープルールを強制します。

ドキュメント: Version 2026-05-11 →

適したユースケース:

  • 新規連携、および join 側 calc 参照を含むクエリを組み立てるすべてのクライアント。
  • 修復ループのためにクリーンなバリデーションシグナルを必要とする AI 駆動のクライアント。

2025-10-20（Previous、サポート継続中）​

ステータス: ⚠️ Stable（引き続きサポート） 必要なプラグインバージョン: 3.0.0.0+ サポート期限: 2027-10-20（最低）

機能:

  • from と keep による基本的な QAL クエリ
  • 2 つのマテリアル: allpv（ページビュー）と gsc（Google Search Console）
  • シンプルな result オプション: limit と count_only

ドキュメント: Version 2025-10-20 →

適したユースケース:

  • 対称 join 側 calc を必要としない既存の連携。
  • 2026-05-11 への移行が都合の良いタイミングまで使用 — 強制アップグレードはありません。

クイックスタート​

1. 認証の設定​

WordPress でアプリケーションパスワードを作成します。

  1. ユーザー → あなたのプロフィール に移動
  2. アプリケーションパスワード までスクロール
  3. 名前を入力: "QA API Access"
  4. 新しいアプリケーションパスワードを追加 をクリック
  5. 生成されたパスワードをコピー

2. 接続のテスト​

curl -u "username:your_app_password" \
  "https://your-site.com/wp-json/qa-platform/guide?version=2026-05-11"

3. 最初のクエリの実行​

curl -X POST \
  -u "username:your_app_password" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_id": "abc123",
  "materials": [{"name": "allpv"}],
    "time": {
      "start": "2025-10-01T00:00:00",
      "end": "2025-10-20T00:00:00",
      "tz": "Asia/Tokyo"
    },
    "make": {
      "my_view": {
        "from": ["allpv"],
        "keep": ["allpv.url", "allpv.title"]
      }
    },
    "result": {
      "use": "my_view",
      "limit": 10
    }
  }' \
  "https://your-site.com/wp-json/qa-platform/query?version=2026-05-11"

バージョン比較​

機能2025-10-202026-05-11
QAL — filter / join / calc / sort✅ サポート✅ サポート（変更なし）
calc — from 側の material.column✅ 自動 fetch + 集計✅ 自動 fetch + 集計（変更なし）
calc — join.with 側の material.column⚠️ サイレント 0 行バグ✅ from 側と対称、正しいカウント
不正な calc 参照⚠️ サイレントに 0 行✅ バリデーション時に拒否（E_CALC_COLUMN_UNRESOLVED）
E_INVALID_JOIN の形code + message + at+ details.{side, received_value, expected_prefix, hint}
features_detail.calc_join_symmetric非存在{ enabled: true, since: "2026-05-11" }

マイグレーションガイド​

新しいバージョンがリリースされたとき​

新しいバージョンがリリースされても、既存のクエリはそのまま動作し続けます。

  1. 既存のクエリ: ?version=2026-05-11 を使い続けます
  2. 新機能: 新しいバージョンパラメーターでテストします
  3. 段階的な移行: クエリを 1 つずつ更新していきます
  4. 強制アップグレードなし: 古いバージョンは 24 ヶ月以上サポートされます

破壊的変更ポリシー​

破壊的変更は新しいバージョン日付のときにのみ発生します。

  • 破壊的変更: 新バージョンが必要（例: 2026-03-01）
  • 新機能: 同一バージョン、後方互換
  • バグ修正: 同一バージョン、変更不要
  • ドキュメント: バージョン番号は変わらない

ヘルプを得る​

次のステップ​

👉 Version 2025-10-20 ではじめる - 完全な API ドキュメント

学べること:

  • 認証のセットアップ
  • 利用可能なマテリアル（allpv, gsc）
  • QAL クエリの基本
  • エンドポイントリファレンス
  • 複数言語でのコード例