アンケート API

Databricks に置かれた Creative Survey / Ask One の回答データの参照。共通規約は API 共通仕様を参照。

ベースパス: /api/v1/surveys

メソッド	パス	概要
GET	`/`	アンケート一覧取得
GET	`/{surveyId}`	アンケート詳細取得
GET	`/{surveyId}/questions`	アンケート質問一覧取得
GET	`/{surveyId}/preview`	アンケートデータプレビュー
GET	`/{surveyId}/panels`	回答者一覧取得
GET	`/{surveyId}/panels/{panelId}`	回答者詳細取得
GET	`/{surveyId}/respondents`	回答者一覧取得（レガシー）

全エンドポイントで Authorization: Bearer <access_token> が必要。

ロール制限がない

このルータだけは requireRole() を適用していない。参照専用になったため実害は小さいが、viewer でも全アンケートの回答を閲覧できる。

ページネーションは offset / limit

一覧系は page ではなく offset / limit を使い、data の中に { items, total, limit, offset } 形式で返る。共通の pagination フィールドは付かない。

データの流れ

graph LR
  CS[(Creative Survey)]
  S3[(S3<br/>answers.csv.gz / panels.csv.gz)]
  Pipe[cs_data_pipeline_s3_delivery<br/>毎日 5:00:45 JST]
  DM[(cs.cs_dm.dm_answers_&lt;survey_id&gt;<br/>回答 × パネル 結合済み)]
  DWH[(cs.cs_dwh)]
  Meta[databricks-meta-sync]
  Cache[(databricks_surveys)]
  API[アンケート API]

  CS --> S3 --> Pipe --> DM
  Pipe --> DWH
  DWH --> Meta --> Cache
  DM --> API
  Cache --> API

Databricks 側のパイプラインが S3 から取り込み、調査ごとに dm_answers_<survey_id> として回答とパネルを結合済みの形まで加工する。API はそれを直接読む。

参照先	使う API
`databricks_surveys`（Postgres）	一覧・詳細。集計に 15 秒かかるため日次でキャッシュする
`cs.cs_dm.dm_answers_<survey_id>`	質問一覧・プレビュー・回答者系

1 クエリあたり約 1 秒の固定オーバーヘッド

Databricks の SQL Statement Execution API は 1 往復に約 1 秒かかる。一覧を引くたびに調査別テーブルを叩かないよう、メタは Postgres 側のキャッシュを使っている。

未知の調査 ID は 404

調査別エンドポイントは databricks_surveys に行があるかを先に確認する。Databricks のテーブル未存在エラー（502）を返さないため。

アンケート一覧取得

databricks_surveys（メタデータキャッシュ）から一覧を返す。

URI

GET /api/v1/surveys

クエリパラメータ

フィールド	型	必須	既定値	ルール	説明
`search`	string	-	-	-	アンケート名で部分一致検索
`sort`	string	-	`-latestResponseAt`	-	`-` プレフィックスで降順
`limit`	integer	-	`20`	1〜100	件数
`offset`	integer	-	`0`	0 以上	開始位置

レスポンス（200 OK）

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": {
    "surveys": [
      {
        "surveyId": "234567",
        "name": "2026年春季ユーザー調査",
        "lastModified": "2026-01-31T05:00:00Z",
        "fileCount": 5,
        "respondentCount": 1234
      }
    ],
    "total": 12,
    "limit": 20,
    "offset": 0
  },
  "path": "/api/v1/surveys",
  "method": "GET"
}

例外処理

説明	ステータスコード	ステータス名
クエリの形式不正	400	Bad Request
トークンが欠落または無効	401	Unauthorized
Databricks 未設定（`DATABRICKS_NOT_CONFIGURED`）	503	Service Unavailable

アンケート詳細取得

URI

GET /api/v1/surveys/{surveyId}

パスパラメータ

フィールド	ルール
`surveyId`	必須。1 文字以上

レスポンス（200 OK）

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": {
    "surveyId": "234567",
    "surveyName": "2026年春季ユーザー調査",
    "collectorName": "メインコレクター",
    "statistics": {
      "totalRespondents": 1234,
      "completedRespondents": 1100,
      "questionCount": 25,
      "earliestResponseAt": "2026-01-15T10:00:00+09:00",
      "latestResponseAt": "2026-01-30T18:30:00+09:00"
    },
    "syncedAt": "2026-01-31T05:00:00+09:00"
  },
  "path": "/api/v1/surveys/234567",
  "method": "GET"
}

統計値は同期時点のスナップショット。

例外処理

説明	ステータスコード	ステータス名
トークンが欠落または無効	401	Unauthorized
アンケートが存在しない	404	Not Found

アンケート質問一覧取得

セグメント定義やインポートマッピングの選択肢を作るために使う。

URI

GET /api/v1/surveys/{surveyId}/questions

クエリパラメータ

フィールド	型	必須	既定値	ルール	説明
`search`	string	-	-	-	質問テキストで部分一致検索
`limit`	integer	-	`50`	1〜200	件数
`offset`	integer	-	`0`	0 以上	開始位置
`includeOptions`	boolean	-	`false`	-	選択肢を含めるか

レスポンス（200 OK）

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": {
    "surveyId": "234567",
    "questions": [
      {
        "questionId": "q_1",
        "questionText": "サービスの満足度を教えてください",
        "questionType": "single_select",
        "options": ["とても満足", "満足", "普通", "不満"]
      }
    ],
    "total": 25,
    "limit": 50,
    "offset": 0
  },
  "path": "/api/v1/surveys/234567/questions",
  "method": "GET"
}

`questionType`	意味
`single_select`	単一選択
`multi_select`	複数選択
`text`	自由記述
`number`	数値
`date`	日付
`other`	その他

options は includeOptions=true のときのみ含まれる。

質問の識別子

mart は設問 ID を持たず 設問文そのもので識別する。インポートマッピングの sourceField にも設問文を指定する。マトリクス設問は 設問文|||選択肢文 の複合キーになる。

例外処理

説明	ステータスコード	ステータス名
クエリの形式不正	400	Bad Request
トークンが欠落または無効	401	Unauthorized
アンケートが存在しない	404	Not Found

アンケートデータプレビュー

設問一覧とサンプル回答者をまとめて返す。

URI

GET /api/v1/surveys/{surveyId}/preview

レスポンス（200 OK）

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": {
    "surveyId": "234567",
    "questions": [
      { "questionId": "q_1", "questionText": "サービスの満足度を教えてください", "questionType": "single_select" }
    ],
    "totalRespondents": 1234,
    "sampleRespondents": [
      {
        "respondentId": "119466675",
        "answers": { "q_1": "とても満足", "q_2": "使いやすい" },
        "completedAt": "2026-01-28T14:30:00Z",
        "metadata": {}
      }
    ]
  },
  "path": "/api/v1/surveys/234567/preview",
  "method": "GET"
}

例外処理

説明	ステータスコード	ステータス名
トークンが欠落または無効	401	Unauthorized
アンケートが存在しない	404	Not Found

回答者一覧取得

調査別テーブルの回答行からパネルを重複排除して一覧する。

URI

GET /api/v1/surveys/{surveyId}/panels

クエリパラメータ

フィールド	型	必須	既定値	ルール	説明
`isCompleted`	boolean	-	-	-	回答完了で絞り込み
`search`	string	-	-	-	パネル ID などで検索
`sort`	string	-	`-completedAt`	-	`-` プレフィックスで降順
`limit`	integer	-	`20`	1〜100	件数
`offset`	integer	-	`0`	0 以上	開始位置

レスポンス（200 OK）

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": {
    "panels": [
      {
        "panelId": "119466675",
        "isCompleted": true,
        "customKey": "user_abc123",
        "completedAt": "2026-01-28T14:30:00+09:00",
        "deviceInfo": {
          "platform": "Windows",
          "browser": "Chrome",
          "browserVersion": "120.0",
          "os": "Windows 11",
          "resolution": "1920x1080",
          "isMobile": false,
          "ipAddress": "192.168.1.xxx"
        },
        "createdAt": "2026-01-28T14:00:00+09:00"
      }
    ],
    "total": 1100,
    "limit": 20,
    "offset": 0
  },
  "path": "/api/v1/surveys/234567/panels",
  "method": "GET"
}

例外処理

説明	ステータスコード	ステータス名
クエリの形式不正	400	Bad Request
トークンが欠落または無効	401	Unauthorized
アンケートが存在しない	404	Not Found

回答者詳細取得

1 人の回答者の属性と全回答を返す。

URI

GET /api/v1/surveys/{surveyId}/panels/{panelId}

パスパラメータ

フィールド	ルール
`surveyId`	必須。1 文字以上
`panelId`	必須。1 文字以上（回答者 ID）

クエリパラメータ

フィールド	型	必須	既定値	説明
`includeUnanswered`	boolean	-	`false`	未回答の設問も含めるか

レスポンス（200 OK）

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": {
    "panel": {
      "panelId": "119466675",
      "isCompleted": true,
      "customKey": "user_abc123",
      "urlParameter": "source=email&campaign=spring2026",
      "completedAt": "2026-01-28T14:30:00+09:00",
      "deviceInfo": { "platform": "Windows", "browser": "Chrome", "browserVersion": "120.0", "os": "Windows 11", "resolution": "1920x1080", "isMobile": false, "ipAddress": "192.168.1.xxx" },
      "createdAt": "2026-01-28T14:00:00+09:00",
      "updatedAt": "2026-01-28T14:30:00+09:00"
    },
    "answers": [
      {
        "questionSentence": "お名前をご記入ください",
        "answerType": "テキスト入力",
        "answerItemSentence": null,
        "subItemSentence": null,
        "value": "山田太郎",
        "isAnswered": true
      }
    ],
    "answersSummary": {
      "totalQuestions": 25,
      "answeredQuestions": 23,
      "unansweredQuestions": 2
    }
  },
  "path": "/api/v1/surveys/234567/panels/119466675",
  "method": "GET"
}

answers は mart の縦持ちをそのまま返す（1 行 = 1 設問 × 1 選択肢）。1 設問が複数行に分かれるため、画面側は設問単位にまとめて表示する。

例外処理

説明	ステータスコード	ステータス名
トークンが欠落または無効	401	Unauthorized
アンケートまたは回答者が存在しない	404	Not Found

回答者一覧取得（レガシー）

廃止予定

/panels 系のエンドポイントに置き換えられている。新規実装では使わない。

URI

GET /api/v1/surveys/{surveyId}/respondents

クエリパラメータ

フィールド	型	必須	ルール
`limit`	integer	-	1〜1000
`offset`	integer	-	0 以上
`onlyCompleted`	boolean	-	-

レスポンス（200 OK）

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": {
    "surveyId": "234567",
    "respondents": [
      { "respondentId": "119466675", "answers": { "q_1": "とても満足" }, "completedAt": "2026-01-28T14:30:00Z" }
    ],
    "total": 1100,
    "limit": 100,
    "offset": 0
  },
  "path": "/api/v1/surveys/234567/respondents",
  "method": "GET"
}

回答が 横持ち（answers オブジェクト）で返る点が /panels/{panelId} と異なる。