サーベイのためのレスポンスAPIリファレンス

AIを使用して英語から翻訳されました

この記事はAI技術を使用して翻訳されたことにご注意ください。正確性を維持するよう努めていますが、一部の詳細は元のテキストを完全に反映していない場合があります。情報に不明な点がある場合は、英語版を参照してください。

概要
API資格情報の生成と削除方法
認証
レート制限
レスポンスとエラー
ページネーション
バージョン管理

APIリファレンス

調査レスポンス
ユーザー検索

概要

レスポンスAPIはJSONベースのHTTP APIです：

リソース指向です（RESTのように）
JSONリクエストボディを受け入れます
JSONレスポンスを返します
標準のHTTP動詞（メソッド）を使用します
HTTPステータスコードを使用してステータスを伝えます
認証にはOAuthクライアント資格情報フローを使用します

すべてのAPI呼び出しは同じベースドメインに対して行われます： https://api.hotjar.io

トップに戻る

API資格情報の生成と削除方法

API資格情報の生成

1. あなたのAPIページにアクセスします。

2. API資格情報のための組織を選択します。

3. 資格情報名を入力します。

4. 機能の範囲を制限するためにAPI資格情報のスコープを選択します。

APIページ、組織、名前、スコープが選択されている様子。

5. '資格情報を生成'をクリックします。

以前に生成された資格情報はAPIページに表示されます。

API資格情報の削除

1. あなたのAPIページにアクセスします。

2. 削除する関連するAPI資格情報を特定します。

3. '資格情報を削除'をクリックします。

これにより、生成されたAPI資格情報が削除されます。

トップに戻る

認証

レスポンスAPIは、APIキーとOAuthクライアント資格情報フローの組み合わせを使用して認証を行います。APIキーは顧客の声APIページから生成できます。APIキーは、クライアントIDとクライアントシークレットのペアで構成されています。APIを使用する際は、次のことを行う必要があります：

クライアントIDとクライアントシークレットを使用してトークンエンドポイントにリクエストを送信します
応答として一時的なベアラートークンを受け取ります
すべての他のAPI呼び出しにベアラートークンをAuthorization HTTPヘッダーで送信します

APIキーは多くの特権へのアクセスを付与するため、秘密にしておく必要があります。Gitlabなどの公開アクセス可能な場所やアプリケーションに埋め込んで共有しないでください。APIキーは、APIキーが秘密に保たれる機械間通信を目的としています。

ベアラートークンの取得

アクセストークンを取得するには、/v1/oauth/tokenにHTTP POSTリクエストを送信する必要があります。リクエストはapplication/x-www-form-urlencodedとしてエンコードされる必要があり（これはOAuthの要件です）、3つのパラメータを含める必要があります：

grant_typeはclient_credentialsに設定する必要があります
client_idはAPIキーのクライアントIDに設定する必要があります
client_secretはAPIキーのクライアントシークレットに設定する必要があります

以下は簡略化された例です：

POST /v1/oauth/token HTTP/1.1
Host: api.hotjar.io

grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx

成功した場合のレスポンスは、3つのキーを含むJSONオブジェクトレスポンスです：

token_typeはBearerに設定されます
expires_inはベアラートークンが期限切れになるまでの秒数を指定します
access_tokenはベアラートークン自体です

以下はレスポンスの例です：

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"<token>",
"token_type":"Bearer",
"expires_in":3600,
}

ベアラートークンの使用

API呼び出しを行う際には、上記の方法で取得したベアラートークンをAuthorization HTTPヘッダーを介して送信する必要があります。ヘッダーの値はBearer <token here>である必要があります。以下は簡略化された例です：

GET /v1/sites/1/surveys HTTP/1.1
Host: api.hotjar.io
Authorization: Bearer token_goes_here

リクエストにヘッダーが含まれていない場合、HTTPステータスコード401で応答します。トークンが無効であるか、APIキーに要求されたアクションを実行する権限がない場合、HTTPステータスコード403で応答します。

トップに戻る

レート制限

現在、Responses APIはソースアドレスによってレート制限されており、1分あたり3000リクエスト（1秒あたり50リクエスト）に制限されています。リクエストが多すぎる場合、APIはHTTPステータスコード429で応答します。

トップに戻る

レスポンスとエラー

HTTPステータスコードは権威があります。ステータスコードが2XXの範囲にある場合、API呼び出しは成功し、ステータスコードが4XXの範囲にある場合、クライアントエラーが発生し、ステータスコードが5XXの範囲にある場合、サーバーエラーが発生します。

APIエンドポイントがデータを返す場合、それはJSONとして返されます。この場合、最上位のレスポンスはJSONオブジェクト（配列ではなく）になります。エンドポイントが複数のオブジェクト（行）を返す場合、それらはresultsキーの下に配列として送信されます。ページネーションのあるエンドポイントには、レスポンスに最上位のnext_cursorキーが含まれます（下記参照）。

エラーが返された場合、エラーに関する追加情報が含まれることがあります。この場合、レスポンスはJSONエンコードされ、以下のフィールドが含まれます：

code - 機械可読のための文字列で、エラーコードを含みます
msg - エラーの原因を説明する人間可読の文字列です。

トップに戻る

ページネーション

Responses APIはカーソルベースのページネーションを利用しています。エンドポイントがページネーションをサポートしている場合、受け取りたいアイテムの数を指定するためにlimitパラメータを送信できます。最初のリクエストを行うと、レスポンスにnext_cursorフィールドが含まれます。次のリクエストを行う際に次のページのアイテムを取得するには、next_cursorの値をcursorというパラメータとして渡します。APIはこの値を使用して次のページのアイテムを返します。追加の結果がない場合、next_cursorはnullです。

トップに戻る

バージョン管理

Responses APIは、各エンドポイントがバージョン管理されるのではなく、「グローバル」バージョン番号を使用しています。バージョン内で後方互換性のない変更を導入することはありません。現在、APIバージョンは1つ（v1）のみで、将来的に他のバージョンを導入する可能性があります。将来的にAPIのバージョンのサポートを停止することを決定した場合、サポートを削除する前に少なくとも6か月の通知を行うことを保証します。

トップに戻る

APIリファレンス

調査の回答

調査の一覧

調査の回答を一覧表示する際、回答は作成日で降順にソートされます。つまり、最も最近の回答が最初に表示されます。この時点では、特定の日付からの回答をフィルタリングするなど、回答をフィルタリングすることはできません。

GET /v1/sites/:site_id/surveys

site_id: サイトの一意の識別子。このIDは、調査ページを表示しているときのURLにあります - https://insights.hotjar.com/sites/{site_id}/surveys/list。

URLパラメータ（オプション）:

limit: レスポンスに返される調査の数。最大100。
cursor: 特定のページを取得するために使用されるカーソル。
with_questions: 質問情報をレスポンスに含めるべきかどうかを示すフラグ（true/false）。デフォルトでは含まれていません。

レスポンスフィールド:

results: アンケート項目のリスト。各アンケートには以下のフィールドが含まれます：
- id (string): アンケートの一意の識別子。
- url (string): レスポンスAPI用のアンケートのURL。
- created_time (datetime): アンケートの作成時間（rfc3339形式）。
- updated_time (datetime): アンケートの更新時間（rfc3339形式）。
- is_enabled (boolean): アンケートが有効かどうかを示すフラグ。
- name (string): アンケートの名前。
- responses_url (string): このアンケートのレスポンス用のレスポンスAPI URL。
- type (string): アンケートのタイプ。link、full_screen、またはpopoverのいずれかです。
- questions: 質問項目のリスト。リクエストパラメータでフラグがtrueに設定されている場合にオプションで含まれます。
  - id (string): 質問の一意の識別子。
  - is_required (boolean): 質問が必須かどうかを示すフラグ。
  - text (string): 質問のテキスト。
  - type (string): 質問のタイプ。可能な値はreaction、long-text、short-text、single-option、multiple-option、email、rating-1-5、rating-1-7、nps、statement、およびthank-youです。
  - image_url (Optional url): 質問に関連付けられた画像のURL（ある場合）。
  - choices (Optional list of Choice objects): ユーザーが選択できる可能な選択肢。このフィールドはsingle-optionまたはmultiple-option質問タイプにのみ使用されます。
    - text (string): 選択肢のテキスト。
    - allow_comment (boolean): ユーザーがこの選択肢を選択した場合にコメントできるかどうかを示すフラグ。
  - labels (Optional Label object): 低ラベルと高ラベルの命名に関する情報。このフィールドはrating-1-5、rating-1-7、nps、およびreaction質問タイプにのみ使用されます。
    - low_label (string): 質問の最低スコアオプションの命名。
    - high_label (string): 質問の最高スコアオプションの命名。
- sentiment_analysis_enabled (boolean): レスポンスが感情分析を通過するかどうかを示します。
next_cursor (string): 次のページのカーソル。

サンプルレスポンス：

{
  "next_cursor": "gAAAAABj90lFO37F7V3M0GLNa-cp0QIqq91P3faMKqptoVZpRGn8LH9lufXhTX2MOtv566sVsbVz_YGS9FYp_N19DNK8brCAhEbIFKcgYUjh6vX2FjRgtoELfj9E3_kggNZ5DF8Ul3oE",
  "results": [
    {
      "created_time": "2023-02-23T11:08:53.287Z",
      "id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
      "is_enabled": false,
      "name": "私の調査名",
      "responses_url": "/v1/sites/12345/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
      "type": "popover",
      "url": "/v1/sites/12345/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
      "questions": [
        {
          "choices": null,
          "id": "question_f5937a53-674a-43d1-b4b7-ada420568ebf_7b725dac",
          "image_url": null,
          "is_required": true,
          "labels": null,
          "text": "私たちのAPIについてどう思いますか？",
          "type": "long-text"
        }
      ],
      "sentiment_analysis_enabled": false
    }
  ]
}

調査を取得

GET /v1/sites/:site_id/surveys/:survey_id

site_id: サイトの一意の識別子。このIDは、調査ページを表示しているときのURLにあります - https://insights.hotjar.com/sites/{site_id}/surveys/list .
survey_id: 調査の一意の識別子。

レスポンスフィールド:

レスポンスフィールドは、上記のリスト調査エンドポイントで説明されている調査項目と同じです。質問は常にこのエンドポイントに含まれます。

サンプルレスポンス:

{
  "created_time": "2023-02-23T11:08:53.287Z",
  "id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
  "is_enabled": false,
  "name": "私の調査名",
  "responses_url": "/v1/sites/123456/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
  "type": "popover",
  "url": "/v1/sites/123456/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
  "questions": [
    {
      "choices": null,
      "id": "question_f5937a53-674a-43d1-b4b7-ada420568ebf_7b725dac",
      "image_url": null,
      "is_required": true,
      "labels": null,
      "text": "私たちのAPIについてどう思いますか？",
      "type": "long-text"
    }
  ],
  "sentiment_analysis_enabled": true
}

調査の回答をリスト

GET /v1/sites/:site_id/surveys/:survey_id/responses

site_id: サイトの一意の識別子。このIDは、調査ページを表示しているときのURLにあります - https://insights.hotjar.com/sites/{site_id}/surveys/list .
survey_id: 調査の一意の識別子。

URLパラメータ（オプション）:

limit: レスポンスで返される調査回答の数。最大100。
cursor: 特定のページを取得するために使用されるカーソル。

レスポンスフィールド:

results: アンケート回答項目のリスト。各アンケート回答には以下のフィールドが含まれます：
- id (string): 回答の一意の識別子。
- answers (アンケート回答オブジェクトのリスト)。各アンケート回答には以下のフィールドが含まれます：
  - question_id (string): 質問の識別子
  - answer (string): 回答。
  - comment (string): ユーザーが提供した任意のコメント。
  - tags (アンケート回答タグオブジェクトのリスト)。各アンケート回答タグには以下のフィールドが含まれます：
    - name (string): タグの名前。
  - sentiment (string): 回答テキストの感情。 "positive"、"negative"、"neutral"、または `null` のいずれかです。null値は、テキスト以外の回答や感情が設定されていない場合に設定されます。感情キーは、Ask製品プランの一部である場合にのみ存在します。
- browser (string): 回答がキャプチャされたブラウザ。
- country (string): ユーザーの国の2文字コード。国コードのリストはここで見つけることができます https://www.iso.org/iso-3166-country-codes.html
- created_time (datetime): rfc3339形式での回答の提出時間。
- device (string): 回答を提出するために使用されたデバイスタイプ。 "tablet"、"mobile"、"desktop" のいずれかです。
- hotjar_user_id (string): 回答を提出したユーザーの一意の識別子。
- is_complete (boolean): 回答が完了しているかどうかを示すフラグ。
- os (string): ユーザーのオペレーティングシステム。
- recording_url (string): その回答を含む録音へのリンク（存在する場合）。
- response_origin_url (string): ユーザーが回答を提出したサイトのURL。
- user_attributes (ユーザー属性のリスト): Identify APIによって提供されたユーザーの属性のリスト。各ユーザー属性には以下のフィールドが含まれます：
  - name (string): ユーザー属性の名前
  - value (string/integer/float/boolean/datetime): ユーザー属性の値
- window_size: ユーザーのブラウザのウィンドウサイズ。以下のフィールドが含まれます：
  - width (integer): ウィンドウの幅（存在する場合）。
  - height (integer): ウィンドウの高さ（存在する場合）。
next_cursor (string): 次のページのカーソル。

サンプル回答：

{
  "next_cursor": "gAAAAABj91CIjMAhTxEHLEyeycuAsTylGzwlaKMIo5lBl_zKikJeO3DQa9hvsChE2Kc032DlDne0HE7xURLuyFTDWWaiBZoob0wCLhb39eCotgBKNW5vodsXEVIrNT0nX_X5kdziNDup",
  "results": [
    {
      "answers": [
        {
          "answer": "あなたの製品が大好きです。",
          "comment": "私は毎日使っています。",
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
          "tags": [
            {
              "name": "todo"
            },
            {
              "name": "positive"
            }
          ],
          "sentiment": "positive"
        },
        {
          "answer": "10",
          "comment": null,
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
          "tags": [],
          "sentiment": null
        }
      ],
      "browser": "Mobile Safari UI/WKWebView",
      "country": "mt",
      "created_time": "2023-02-23T11:39:51.473Z",
      "device": "desktop",
      "hotjar_user_id": "8c9edf6f-ff84-3f2b-9755-15bbfff75aaf",
      "id": "response_f8ccb724-8110-48d0-8715-2138be7a9c06",
      "is_complete": false,
      "os": "iOS",
      "recording_url": null,
      "response_origin_url": "https://www.example.com/484845acc8164763ba6d",
      "user_attributes": [
        {
          "name": "customer_type",
          "value": "enterprise"
        }
      ],
      "window_size": {
        "height": 768,
        "width": 1024
      }
    }
  ]
}

異なる調査質問タイプの例のペイロード：

reaction

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
  "type": "reaction",
  "text": "あなたの体験をどのように評価しますか？",
  "is_required": true,
  "labels": {
    "low_label": "全く良くない",
    "high_label": "素晴らしい！"
  }
}

short-text

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcb",
  "type": "short-text",
  "text": "私たちの新しいレイアウトは好きですか？",
  "is_required": true
}

long-text

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcc",
  "type": "long-text",
  "text": "新しいレイアウトの何が好きですか？",
  "is_required": false
}

single-option

{
    "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcd",
    "type": "single-option",
    "text": "再度私たちのサイトを利用しますか？",
    "is_required": true,
    "choices": [
      {
        "text": "はい",
        "allow_comment": false
      },
      {
        "text": "いいえ",
        "allow_comment": false
      },
      {
        "text": "わかりません",
        "allow_comment": false
      }
    ]
  }

multiple-option

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efde",
  "type": "multiple-option",
  "text": "あなたがもっと好きなことを教えてください",
  "is_required": false,
  "choices": [
    {"text": "ユーザーエクスペリエンス", "allow_comment": false},
    {"text": "機能", "allow_comment": false},
    {"text": "その他", "allow_comment": true}
  ]
}

rating-1-5

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef08",
  "type": "rating-1-5",
  "text": "1から5の中で、私たちのサービスをどのくらい好きですか？",
  "is_required": true,
  "labels": {"low_label": "嫌いです", "high_label": "大好きです"}
}

rating-1-7

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef09",
  "type": "rating-1-7",
  "text": "1から7の範囲であなたの体験を評価してください。",
  "is_required": false,
  "labels": {"low_label": "最悪の体験でした。", "high_label": "素晴らしい！"}
}

nps

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef10",
  "type": "nps",
  "text": "友人や同僚に私たちを推薦する可能性はどのくらいですか？",
  "is_required": true,
  "labels": {"low_label": "全く可能性がない。", "high_label": "絶対に！"}
}

email

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef11",
  "type": "email",
  "text": "ご連絡を希望される場合は、メールアドレスを入力してください。",
  "is_required": false
}

thank-you

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef12",
  "type": "thank-you",
  "text": "ご回答いただきありがとうございます！",
  "is_required": true
}

statement

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef13",
  "type": "statement",
  "text": "この調査は5分かかります。",
  "is_required": true
}

ユーザー検索

ユーザー検索を実行する（オプションの削除あり）

POST /v1/organizations/:organization_id/user-lookup

organization_id: 組織の一意の識別子。

JSONボディパラメータ：

このエンドポイントへのリクエストは、Content-Type: application/json; charset=utf-8.

data_subject_email: 対象ユーザーのメールアドレスの文字列。
data_subject_site_id_to_user_id_map: <site_id>から<user_id_on_your_site>へのマップ（オブジェクト）。ユーザー属性APIを使用してユーザーの一意のIDを送信した場合に便利です。
delete_all_hits: 見つかったデータを即座に削除するかどうかを示すブール値（true/false）。

成功したリクエストには、data_subject_email またはdata_subject_site_id_to_user_id_map のいずれか（または両方）をリクエストのボディに送信する必要があります。

もし delete_all_hits が false の場合、つまりすべてのヒットを自動的に削除しないということを意味し、data_subject_email アドレスと、ユーザー検索ページで指定したデフォルトの受信者アドレスにデータレポートへのリンクを含むメールが送信されます。これは、ウェブアプリケーションを通じてユーザー検索ツールが機能する方法を模倣しています。

もし delete_all_hits が true の場合、あなたやデータ主体にメールは送信されません。私たちは見つけたデータを静かに削除します。

サンプルリクエスト：

## ユーザー検索
curl -X "POST" "https://api.hotjar.io/v1/organizations//user-lookup" \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"delete_all_hits": false,
"data_subject_email": "text@example.com",
"data_subject_site_id_to_user_id_map": {
"42": "unique_id_42"
}

サンプルレスポンス：

202 Accepted, データはありません。

トップに戻る

このセクションの記事

概要

API資格情報の生成と削除方法

API資格情報の生成

API資格情報の削除

認証

ベアラートークンの取得

ベアラートークンの使用

レート制限

レスポンスとエラー

ページネーション

バージョン管理

APIリファレンス

調査の回答

調査の一覧

調査を取得

調査の回答をリスト

ユーザー検索

ユーザー検索を実行する（オプションの削除あり）