ditto-product-research

Ditto の製品リサーチ

Ditto の 300,000 人以上の合成ペルソナを活用し、ターミナルから直接、顧客調査、価格テスト、製品検証の調査を実施できます。

完全なドキュメント： https://askditto.io/claude-code-guide

Ditto の機能

Ditto は、米国、英国、ドイツ、カナダの国勢調査データに合わせて調整された、300,000 人以上の AI 搭載合成ペルソナを管理しています。自由形式の質問をすると、実際のインタビューのように具体的な質的回答が得られます。

• 92% の重複率：従来のフォーカスグループとの比較（EY Americas による検証）
• 95% の相関：従来の調査との比較
• Harvard／Cambridge／Stanford／Oxford の査読済み手法
• 10 人のペルソナに 7 つの質問をする調査が 10～12 分で完了
• 従来の方法で同等の調査を行う場合：4～8 週間、10,000～50,000 ドル

クイックスタート（無料プラン）

無料の API キーを取得できます。クレジットカードも営業担当者との通話も不要です。

curl -sL https://app.askditto.io/scripts/free-tier-auth.sh | bash

または、こちらをご覧ください：https://app.askditto.io/docs/free-tier-oauth

すぐに質問できます。

curl -s -X POST "https://app.askditto.io/v1/free/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What frustrates you most about grocery shopping?"}'

無料キー（rk_free_）：共有ペルソナ約 12 人、人口統計フィルターなし。 有料キー（rk_live_）：カスタムグループ、人口統計フィルター、調査件数無制限。

API の基本

ベース URL： https://app.askditto.io 認証ヘッダー： Authorization: Bearer YOUR_API_KEY Content-Type： application/json

標準ワークフロー（6 ステップ）

重要：必ず以下の手順を順番に実行してください。質問は必ず順に行い、次の質問をする前にすべての回答を待つ必要があります。

ステップ 1：パネルを募集する

curl -s -X POST "https://app.askditto.io/v1/research-groups/recruit" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Adults 30-55",
    "group_size": 10,
    "filters": {"country": "USA", "age_min": 30, "age_max": 55}
  }'

レスポンスから uuid を保存します（5～15 秒）。

重要： size ではなく group_size を使用します。グループの id ではなく uuid を使用します。 州のフィルターには 2 文字のコードを使用します（「Michigan」ではなく「MI」）。

ステップ 2：調査を作成する

curl -s -X POST "https://app.askditto.io/v1/research-studies" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Concept Validation",
    "objective": "Understand customer pain points and validate pricing",
    "research_group_uuid": "UUID_FROM_STEP_1"
  }'

調査の id を保存します。レスポンスは data.study の下にネストされています。response["id"] ではなく、response["study"]["id"] で取得します。

ステップ 3：質問する（一度に 1 つ）

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Your open-ended question here"}'

job_ids（ペルソナごとに 1 つ）が返されます。次の質問をする前に、完了するまでポーリングします。

ステップ 4：完了するまでポーリングする

curl -s "https://app.askditto.io/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $DITTO_API_KEY"

10 人のペルソナによる調査のポーリング戦略：

• 最初のポーリングの前に 45～50 秒待ちます
• その後は 20 秒ごとにポーリングします
• 代表として 1 つの job_id をポーリングします。同じ質問のすべてのジョブは同時に完了します
• ステータス：queued → started → finished（または failed）

次の質問をする前に、すべてのジョブが finished になっている必要があります。

ステップ 5：調査を完了する

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/complete" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

AI 分析（要約、セグメント、意見の相違、おすすめ）が実行されます（20～40 秒）。 完了済みの調査で分析を再実行するには（409 を回避するには）、"force": true を使用します。

ステップ 6：共有リンクを取得する

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/share" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

公開 URL が返されます。share_url よりも share_link フィールドの使用をおすすめします。 既存の共有状態を変更せずに確認するには、次のようにします。

curl -s "https://app.askditto.io/v1/research-studies/STUDY_ID/share" \
  -H "Authorization: Bearer $DITTO_API_KEY"

ワークフローのパターン

標準的な 7 問の調査

デフォルトの方法です。ペルソナ 10 人を募集 → 調査を作成 → 7 つの質問をする → 完了 → 共有。 所要時間は合計約 10～12 分です。

多めに募集して選別する

ニッチな対象者を調査する場合や、参加者の質が最も重要な場合（例：VC のデューデリジェンス）に適しています。

1. 参加者を 15～20 人募集します："group_size": 15
2. そのグループから調査を作成します
3. Q1 をスクリーニング質問として尋ねます（「あなたの役割と、その業務をどのくらいの頻度で行うか教えてください……」）
4. Q1 の回答を確認し、各エージェントの関連性を高・中・低で評価します
5. 関連性の低いエージェントをグループではなく調査から削除します。

   curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/agents/remove" \
     -H "Authorization: Bearer $DITTO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"agent_ids": [123, 456, 789]}'
   

   agent_ids は list[int] である必要があります。文字列や UUID は使用しないでください。
6. 選別したパネルだけに Q2～Q7 を尋ねます。ペルソナは最低 8 人残してください。

クイック質問（調査を作成しない）

調査全体を作成せず、1～5 件の簡単な回答を得る場合に使用します。

特定のエージェントへの質問：

curl -s -X POST "https://app.askditto.io/v1/research-agents/AGENT_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What matters most when choosing a coffee brand?"}'

グループ全体への質問：

curl -s -X POST "https://app.askditto.io/v1/research-groups/GROUP_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What matters most when choosing a coffee brand?"}'

無料プラン

共有ペルソナ約 12 人、人口統計フィルターなし。簡単なテストに適しています。

curl -s -X POST "https://app.askditto.io/v1/free/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What frustrates you most about meal planning?"}'

3段階の反復調査

より深く検証するには、順番に3つの調査を実施します（同じグループを共有できます）。

段階	目的	質問数
1. 課題の発見	本当の問題を見つける	自由回答 7問
2. 詳細調査	要件と信頼を理解する	対象を絞った質問 7問
3. コンセプトテスト	ポジショニングと価格を検証する	構造化された質問 7問

各段階の質問は、前の段階で得られた知見を踏まえて作成してください。 合計で約30～45分です。

中断した調査の再開

調査が途中で中断された場合：

1. 調査の詳細を取得します：GET /v1/research-studies/STUDY_ID
2. 既存の質問を一覧表示します：GET /v1/research-studies/STUDY_ID/questions
3. 次の未回答の質問から再開します
4. すべての質問を尋ねたら完了します

Zeitgeist アンケート

あらかじめ用意された回答選択肢を使う、1問のみの簡易アンケートです。

curl -s -X POST "https://app.askditto.io/v1/zeitgeist/surveys/create" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Brand Awareness Pulse",
    "question": "Which brand comes to mind first for sustainable coffee?",
    "research_group_uuid": "GROUP_UUID",
    "answer_options": ["Brand A", "Brand B", "Brand C", "Other"]
  }'

結果を取得：GET /v1/zeitgeist/surveys/SURVEY_ID/results 削除：DELETE /v1/zeitgeist/surveys/SURVEY_ID

自然言語によるリクエスト

プレーンテキストの概要から、調査またはグループの設計をシステムに任せます。

調査リクエスト：

curl -s -X POST "https://app.askditto.io/v1/research-study-requests" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_text": "I want to understand why millennials are switching from coffee to matcha"}'

グループリクエスト：

curl -s -X POST "https://app.askditto.io/v1/research-group-requests" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_text": "US women aged 25-40 who drink matcha daily"}'

グループリクエストのステータスを確認：GET /v1/research-group-requests/REQUEST_ID

AI を活用したリクルート

目的を指定すると、システムがグループを設計します。

curl -s -X POST "https://app.askditto.io/v1/research-groups/interview" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Understand premium pet food purchasing decisions",
    "group_size": 10
  }'

7つの質問フレームワーク

実績のある次の順序に沿って調査を設計します（分野に応じて調整してください）。

1. 関連性を確認する — 「現在、[task] にどのように取り組んでいるか教えてください。典型的な1週間はどのような感じですか？」
2. 課題を特定する — 「[task] で最もストレスを感じるのはどの部分ですか？ノートパソコンを窓から投げ捨てたくなるのはどんなときですか？」
3. 影響を定量化する — 「[problem] によって、1週間あたりおよそどれくらいの時間や費用を失っていますか？」
4. 現在の解決策 — 「現在、どのようなツールや回避策を使っていますか？うまくいっている点は何ですか？うまくいっていない点は何ですか？」
5. 過去の試み — 「新しいものに切り替えようとしたことはありますか？どうなりましたか？」
6. 魔法の杖 — 「[task] に関して、1つだけ直せるとしたら、何を直したいですか？その理由も教えてください。」
7. 導入の障壁 — 「[problem] を解決するツールがあると想像してください。試すのをためらう要因は何でしょうか？」

ブランドや製品を紹介するのは、最も早くてもQ3です。Q1では紹介しないでください（アンカリングバイアスを避けます）。 魔法の杖の質問（Q6）は、一貫して最も多くの洞察を引き出します。

API リファレンス全体

調査グループ

メソッド	エンドポイント	目的
POST	/v1/research-groups/recruit	属性フィルターを使ってグループをリクルートする
POST	/v1/research-groups/create	明示的に指定したエージェント ID からグループを作成する
POST	/v1/research-groups/interview	目的に基づき、AI を活用してリクルートする
GET	/v1/research-groups	すべてのグループを一覧表示する（?limit=N&offset=N）
GET	/v1/research-groups/{id}	グループの詳細とエージェントのプロフィールを取得する
POST	/v1/research-groups/{id}/update	名前／説明／重複排除を更新する
DELETE	/v1/research-groups/{id}	グループをアーカイブする
POST	/v1/research-groups/{id}/agents/add	ID でエージェントを追加する
POST	/v1/research-groups/{id}/agents/remove	エージェントを完全に削除する
POST	/v1/research-groups/{uuid}/append	既存のグループにエージェントを追加でリクルートする

⚠️ 注意： append では group_uuid を使います（group_id ではありません）。他のエンドポイントとは一貫していません。

調査

メソッド	エンドポイント	目的
POST	/v1/research-studies	調査を作成する（research_group_uuid が必須）
GET	/v1/research-studies	調査を一覧表示する（?limit=N&offset=N）
GET	/v1/research-studies/{id}	調査の詳細（ステージ、share_url、件数）を取得する
POST	/v1/research-studies/{id}/complete	AI 分析を開始する
POST	/v1/research-studies/{id}/agents/remove	調査からエージェントを削除する（キュレーション）

質問

メソッド	エンドポイント	目的
POST	/v1/research-studies/{id}/questions	調査で質問する（job_ids を返します）
GET	/v1/research-studies/{id}/questions	すべての Q&A データを取得する
POST	/v1/research-agents/{id}/questions	1 人のエージェントに簡単な質問をする
POST	/v1/research-groups/{id}/questions	グループ全体に簡単な質問をする

ジョブ

メソッド	エンドポイント	目的
GET	/v1/jobs/{job_id}	非同期ジョブのステータスをポーリングする

共有

メソッド	エンドポイント	目的
POST	/v1/research-studies/{id}/share	共有を有効／無効にする
GET	/v1/research-studies/{id}/share	現在の共有状態を確認する

メディア添付ファイル

メソッド	エンドポイント	目的
POST	/v1/media-assets	質問に添付する画像／PDF をアップロードする

エージェント

メソッド	エンドポイント	目的
GET	/v1/agents/find	条件に一致するペルソナを 1 人見つける
GET	/v1/agents/search	人口統計情報でペルソナを検索する

自然言語リクエスト

メソッド	エンドポイント	目的
POST	/v1/research-study-requests	プレーンテキストの概要から調査を作成する
POST	/v1/research-group-requests	説明からグループを作成する
GET	/v1/research-group-requests/{id}	グループリクエストのステータスを取得する

Zeitgeist アンケート

メソッド	エンドポイント	目的
POST	/v1/zeitgeist/surveys/create	回答選択肢付きの簡易アンケートを作成する
GET	/v1/zeitgeist/surveys/{id}/results	アンケート結果を取得する
DELETE	/v1/zeitgeist/surveys/{id}	アンケートを削除する

無料プラン

メソッド	エンドポイント	目的
POST	/v1/free/questions	共有の無料プラングループに質問する

人口統計フィルター

募集時に filters 辞書にフィルターを指定します。

フィルター	型	例	備考
country	文字列	"USA", "UK", "Canada", "Germany"	必須。サポート対象はこの 4 か国のみです
state	文字列	"TX", "MI", "CA"	2 文字のコードのみ
city	文字列	"Austin", "Detroit"	サポートされていますが、対象者が絞られます
age_min	整数	25, 30, 45	推奨
age_max	整数	45, 55, 65	推奨
gender	文字列	"male", "female", "non_binary"	任意
is_parent	ブール値	true, false	家族／消費者関連に適しています
education	文字列	"high_school", "bachelors", "masters", "phd"	任意
industry	配列	["Healthcare", "Technology"]	任意

サポート対象外： income、employment、ethnicity、political_affiliation。

エージェントが 0 人返された場合： フィルターを広げます。state を削除し、industry を削除し、年齢の幅を +/- 10 年広げてください。最大 10 回まで条件を緩和して試します。

業種の代替指定： 自動車整備士 → Automotive Manufacturing、 レストラン経営者 → Food & Beverages、ペットの飼い主 → Veterinary ではなく年齢フィルターを使用、 セキュリティ専門家 → Cybersecurity。

メディア添付ファイル

質問する前に、スクリーンショット、広告クリエイティブ、PDF をアップロードします。

# Upload image
curl -s -X POST "https://app.askditto.io/v1/media-assets" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_url": "https://example.com/screenshot.png",
    "filename": "landing-page.png",
    "mime": "image/png"
  }'

または、base64 を使用します："file_data": "base64_encoded_content"、"encoding": "base64"。 使用できる形式：PNG、JPEG、GIF、WEBP、PDF。

media_asset.id を保存し、質問時に attachments として渡します。

curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Look at this landing page. What would make you trust this product?",
    "attachments": [MEDIA_ASSET_ID]
  }'

ポーリング戦略

調査の規模	最初のポーリングまでの待機時間	以降の間隔	戦略
10 人のペルソナ	45～50 秒	20 秒	1 つの job_id を代表としてポーリングする
15～20 人のペルソナ	60 秒	20 秒	1 つの job_id を代表としてポーリングする
無料プラン（約 12 人）	45 秒	20 秒	1 つの job_id をポーリングする

同じ質問から作成されたすべてのジョブは同時に完了するため、各ジョブを個別にポーリングする必要はありません。 ジョブが failed を返した場合は、一部失敗として報告してください。自動で再試行しないでください。

回答の構造

調査の作成： response["study"]["id"]（study キーの下にネストされています）

質問への回答（GET /v1/research-studies/{id}/questions から取得）：

• response_text — ペルソナの回答（HTML を含む場合があります：<b>、<ul>、<li>）
• agent_name、agent_age、agent_city、agent_state、agent_country
• agent_occupation、agent_summary

完了時の結果： overall_summary、key_segments、divergences、 shared_mindsets、next_questions、stats。

共有リンク： share_link フィールドを優先してください。ない場合は、share_url を使用します。

回答を読む

ポーリングが完了したら、Q&A データをすべて取得します：

curl -s "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY"

エージェントの属性データを使って、年齢、所在地、職業別に調査結果を分類します。

テストできること

• ペインポイント — 顧客は実際にこの問題を抱えていますか？
• 価格設定 — どの価格ならお買い得ですか？ 高すぎますか？ 購入を諦める要因になりますか？
• ポジショニング — どのタグライン／価値提案が最も共感を得られますか？
• 機能 — 顧客は何を優先し、何を無視しますか？
• ランディングページ — スクリーンショットをアップロードして、定性的な反応を得られます
• 広告クリエイティブ — 見出し、画像、メッセージのバリエーションをテストします
• 競合への乗り換え — 現在のソリューションから乗り換えるきっかけは何ですか？
• 購入を断念する要因 — 製品が優れていても、購入を妨げるものは何ですか？

よくある間違い

• リクルーティングで group_size の代わりに size を使用する
• research_group_uuid に文字列の uuid ではなく数値の id を使用する
• append エンドポイントで group_uuid が必要なのに、group_id を使用する
• 調査の作成時に response["study"]["id"] ではなく response["id"] を使用する
• agent_ids に list[int] ではなく文字列／UUID を渡す
• 10～15 秒ごとにポーリングする（頻度が高すぎます。最初は45～50秒、その後は20秒にしてください）
• 質問をまとめて送る（1問ずつ質問し、完了までポーリングしてから次の質問をします）
• 2文字のコード（「MI」）ではなく州の正式名称（「Michigan」）を使用する
• income または employment フィルターを含める（サポートされていません）
• complete の手順を省略する（AI が生成する分析結果を取得できません）
• はい／いいえで答える質問をする（代わりに自由回答形式の質問を使用します）
• 誘導的な質問をする（「X は素晴らしいと思いませんか？」）
• 製品／市場を調査する前に質問を設計する
• Q1 でブランドを紹介する（バイアスを避けるため、早くても Q3 で紹介します）

制限事項

Ditto のペルソナは、特定の製品を実際に使用したことがありません。以下の場合は：

• 実ユーザーから実際の UX フィードバックを得る → 実ユーザーテストを使用します
• 法務／コンプライアンスに関する判断を行う → 人間による調査を使用します
• セーフティクリティカルな判断を行う → 人間による検証を使用します
• 正確な定量指標（NPS、コンバージョン）を得る → 実データを使用します

推奨するハイブリッド手法： 迅速な初回調査（インサイトの80％）には Ditto を使い、 残りの20％については、実際の顧客ならではのニュアンスを把握するために人間による調査を行います。

エラー処理

エラー	原因	対処法
409 Conflict	調査はすでに完了しています	"force": true を指定して再試行します
429 Too Many Requests	レート制限に達しました	30～60秒待ち、リクエストを順番に処理します
0 agents returned	フィルターの条件が厳しすぎます	州／業界を除外し、年齢の範囲を広げます
Job status failed	ペルソナ生成エラー	部分的な失敗として報告し、自動で再試行しないでください
500/502/504	サーバーエラー	15～30秒待ち、1回だけ再試行します

詳細情報

• API ガイド全文：https://askditto.io/claude-code-guide
• 質問の設計：@question-playbook.md
• 実例：@examples/carequarter.md
• API エンドポイントのリファレンス：@api-reference.md