このページでは

HTTP V2 API

地域

ベースURLは、プロジェクトのデータのレジデンシーによって異なります。このページ内のすべての例では、プロジェクトがAmplitudeのEUデータセンターを利用している場合を除き、デフォルトのベースURLを使用してください。EUデータセンターを利用している場合は、この表に記載されているEU用のベースURLを使用してください。

このAPIでは、イベント取り込みのホストとしてapi2.amplitude.com（デフォルト）またはapi.eu.amplitude.com（EU）が使用されます。他のAmplitude APIでは、別のホスト名（api.amplitude.com、core.amplitude.com、data-api.amplitude.com、experiment.amplitude.comなど）が使用されます。https://analytics.amplitude.comのホスト名は、アナリティクスWebアプリ（ブラウザーUI）であり、取り込みのエンドポイントではありません。

データのレジデンシーベースURL
デフォルトhttps://api2.amplitude.com
欧州連合https://api.eu.amplitude.com

考慮事項

HTTP V2 API を使用する際は、次の点に注意してください。

レート制限

Amplitudeは、ユーザープロパティを1時間あたり1800回以上更新する個々のユーザーを（Amplitude IDによって）レート制限します。この制限はユーザープロパティの同期に適用され、イベントの取り込みには適用されません。Amplitudeは引き続きイベントを取り込みますが、そのユーザーのユーザープロパティ更新をドロップする場合があります。

アップロード制限

無料プランをご利用のお客様の場合：

アップロードを毎秒100バッチ、毎秒1000イベントに制限してください。イベントを一括してアップロードすることもできますが、Amplitudeは1バッチあたり10件以下のイベントを送信することを推奨しています。 Amplitudeでは、1秒あたり100件以下のバッチを想定しており、1,000件/秒のイベント制限は引き続き適用されます。

グロースプランとエンタープライズプランをご利用のお客様向け：

リクエストサイズを1MB未満に抑え、リクエストあたりのイベント数を2,000未満に抑えます。これらのサイズ制限を超えると、413エラーが発生します。

大量データにより規模を拡大する必要がある場合は、device_idまたはuser_idベースで作業を分割してください。作業を分割することで、特定のdevice_idやuser_idでのスロットリングによるシステム内の送信者への影響を抑えられる場合があります。プロキシサービスを使用してイベントをAmplitudeに送信する場合、クライアントへのスロットリングを十分に確認して、スパムクライアントによりシステム内での作業分割が遅れないようにしてください。

各プロジェクトのスループット上限は、HTTP API および HTTP V2 エンドポイントに対して 1 秒あたり 50,000 イベントです。 比較のために、SDK エンドポイントはプロジェクトごとに最大 150,000 件/秒のイベントをサポートしています。

パートナー統合に関する情報

Amplitudeとのイベント取り込み連携がある場合は、連携に割り当てられたパートナーIDをイベントペイロードで送信してください。

連携のパートナーIDとペイロードの例を確認するには、「イベント取り込み連携の作成」を参照してください。

デバイスIDがすべてゼロ：追跡型広告の制限が有効

iOS 10 以降、Apple はユーザーが広告追跡の制限を有効にしている場合、広告主識別子（IDFA）をすべて 0 に置き換えます。 すべてのイベントにはデバイス ID が必要であるため、Amplitude はすべてゼロのデバイス ID を廃棄し、リクエストに対してエラーを返します。

デバイス ID として IDFA を渡す場合は、まず IDFA 値を確認してください。 IDFA がすべてゼロの場合、デバイス ID に別の値を渡します（たとえば、ベンダー識別子（IDFV）など）。

Windows OS

Windows オペレーティング システムを使用している場合は、すべての単一引用符をエスケープされた二重引用符に置き換える必要がある場合があります。

文字列の字数上限

user_id、イベント、ユーザープロパティ値など、文字列値の字数上限はすべて1024文字までです。

日付値を設定する

Amplitudeでは、日付を文字列として比較するため、ISO 8601形式（YYYY-MM-DDTHH:mm:ss）を使用します。この形式を使用すると、日付を比較できます（例：'2016-01-31' > '2016-01-01'）。この形式の日時値でも比較できます（例：'2017-08-07T10:09:08' > '2017-08-07T01:07:00'）。

時刻値を設定する

各イベントのtimeパラメータをエポックからのミリ秒単位で送信します。 それ以外の形式（ISO 形式など）を使用すると、400 Bad Request レスポンスが発生します。

イベント重複排除

Amplitudeでは、重複したイベントの送信を防ぐために、各イベントに対してinsert_idを送信することを強く推奨しています。Amplitudeでは、過去7日以内に各アプリで、同じdevice_id（イベントにdevice_id値がある場合）において同じinsert_idを使用してイベントが送信された場合、後続のイベントは無視されます。

デバイスIDとユーザーIDの最小長

デバイスIDとユーザーIDは、5文字以上の文字列である必要があります。最小の長さは、潜在的なインスツルメンテーションの問題を防ぎます。イベントに短すぎるデバイス ID またはユーザー ID が含まれている場合、Amplitude はそのイベントから ID 値を削除します。

リクエストにmin_id_lengthオプションを渡すことで、デフォルトの最小長である 5 文字を上書きします。

イベントにdevice_idの値もuser_idの値もない場合、Amplitudeではステータス「400」でイベントが拒否されることがあります。

言語フィールド

リクエスト内のlanguageフィールドにタグが含まれている場合、Amplitudeはタグを人間にわかりやすい言語名に変更します。 たとえば、リクエストに"language": "en-US"が含まれている場合、Amplitudeは値を保存する前に、それを"language": "English"に変更します。

言語タグは大文字と小文字を区別しません。

リクエスト

POST https://api2.amplitude.com/2/httpapi

ヘッダー

Amplitude HTTP V2 APIにデータを送信するには、Content-Typeヘッダーをapplication/jsonに設定します。

ボディパラメータ

名前概要
api_key必須です。 文字列です。 AmplitudeプロジェクトAPIキー。
events必須です。 [] アップロードするイベントの配列。
optionsオプションです。 [] オブジェクト。

イベント配列キー

これらのキーは、JSONイベントオブジェクトで送信できます。user_idまたはdevice_idのいずれかが必要です。また、event_typeも必須です。

トップレベルのプロパティ

イベントペイロードのトップレベルに session_id のようなプロパティを含めます。そうしないと、Amplitudeは値を正しくマッピングできません。

名前概要
user_iddevice_idが使用されていない場合は必須です。文字列です。 ユーザーのID。min_id_lengthオプションで上書きされない限り、5文字以上の長さが必要です。
device_iduser_idが使用されていない場合は必須です。文字列です。 デバイス固有の識別子（iOSのベンダー識別子など）。device_idがイベントとともに送信されない場合、user_idのハッシュバージョンになります。
event_type必須です。 文字列です。 イベントの一意の識別子です。 Amplitudeでは、内部使用向けに次のイベント名が用意されています：[Amplitude]Start Session"、[Amplitude]End Session"、[Amplitude]Revenue"、[Amplitude]Revenue (Verified)"、[Amplitude]Revenue (Unverified)"、[Amplitude]Merged User"。注: $identifyおよび $groupidentifyは、識別およびグループ識別のために事前に定義されています。
user_agentオプションです。ユーザーデバイスからの未解析および未省略のユーザーエージェント文字列。Amplitudeは、この文字列を解析してイベント上のユーザープロパティに変換します。
timeオプションです。エポックからのイベントのタイムスタンプ（ミリ秒単位）。 イベントと一緒に時刻が送信されない場合、その時刻はリクエストのアップロード時刻に設定されます。
event_propertiesオプションです。オブジェクト。イベントとともに送信するデータを表すキーと値のペアの辞書。 プロパティ値は配列に格納できます。 日付値は文字列値に変換されます。 オブジェクトの深さは40レイヤーを超えることはできません。
user_propertiesオプションです。オブジェクト。ユーザーに関連付けられたデータを表すキーと値のペアの辞書。 プロパティ値は配列に格納できます。 日付値は文字列値に変換されます。 ユーザープロパティの操作（$set、$setOnce、$add、$append、$unset）はevent_typeが$identifyの場合にサポートされます。オブジェクトの深さは40レイヤーを超えることはできません。
groupsオプションです。オブジェクト。この機能は、アカウントアドオンを購入したグロースまたはエンタープライズのお客様が利用できます。このフィールドは、ユーザーのグループを表すキーと値のペアの辞書をイベントレベルのグループとしてイベントに追加します。 イベントごとに最大 5 つの固有のグループタイプと合計 10 個のグループ値を追跡できます。 このしきい値を超えるグループはすべて追跡されません。
group_propertiesオプションです。オブジェクト。この機能は、アカウントアドオンを購入済みのお客様が利用できます。「event_type」が$groupidentifyの場合、フィールドはキーと値のペアの辞書となります。これらのペアは「groups」フィールドにリストされているグループに関連付けられたプロパティを表します。このフィールドは、他のイベントタイプでは無視されます。グループプロパティの操作（$set、$setOnce、$add、$append、$unset）もサポートされています。
$skip_user_properties_syncオプションです。ブール値trueのユーザープロパティが同期されていない場合。デフォルトはfalseです。
app_versionオプションです。文字列です。 アプリケーションの現在のバージョンです。
platformオプションです。文字列です。 デバイスのプラットフォーム。
os_nameオプションです。文字列です。 ユーザーが使用しているモバイルオペレーティングシステムまたはブラウザの名前です。
os_versionオプションです。文字列です。 ユーザーが使用しているモバイルオペレーティングシステムまたはブラウザのバージョン。
device_brandオプションです。文字列です。 ユーザーが使用しているデバイスのブランドです。
device_manufacturerオプションです。文字列です。 ユーザーが使用しているデバイスの製造元です。
device_modelオプションです。文字列です。 ユーザーが使用しているデバイスのモデル。
carrierオプションです。文字列です。 ユーザーが使用している通信事業者です。
countryオプションです。文字列です。 ユーザーの現在の国名。
regionオプションです。文字列です。 ユーザーの現在の地域。
cityオプションです。文字列です。 ユーザーの現在の都市。
dmaオプションです。文字列です。 ユーザーの現在の指定市場エリア。
languageオプションです。文字列です。 ユーザーが設定した言語です。
priceオプションです。浮動小数点数。購入されたアイテムの価格。 収益フィールドが送信されていない場合、収益データに必要です。 払い戻しには負の値を使用できます。
quantityオプションです。整数です。 購入されたアイテムの数量。 指定されていない場合、デフォルトは 1 です。
revenueオプションです。浮動数です。 Revenue = (pricex 個の数量）。価格、数量、収益の3つのフィールドすべてを送信した場合、収益値は（価格x数量）になります。払い戻しには負の値を使用してください。
productIdオプションです。文字列です。 購入されたアイテムの識別子です。 このフィールドを使用して価格と数量、または収益を送信する必要があります。
revenueTypeオプションです。文字列です。 購入されたアイテムの収益のタイプ。 このフィールドを使用して価格と数量、または収益を送信する必要があります。
currencyオプションです。文字列です。 購入されたアイテムの通貨。3文字の大文字のISO 4217コードで指定されます（例：USD、EUR）。
location_latオプションです。浮動小数点数。ユーザーの現在の緯度です。
location_lngオプションです。浮動小数点数。ユーザーの現在の経度です。
ipオプションです。文字列です。 ユーザーのIPアドレスです。アップロード要求でIPアドレスを使用する際は$remoteを使用します。Amplitudeでは、IPアドレスを使用してユーザーの所在地（都市、国、地域、DMA）をリバースルックアップします。Amplitudeは、イベントがAmplitudeサーバーに到達した後に、イベントからロケーションとIPアドレスを削除することができます。 ドロップを設定するには、サポートチームに連絡してください。
idfaオプションです。文字列。（iOS）広告主の識別子です。
idfvオプションです。文字列。（iOS）ベンダーの識別子です。
android_app_set_idオプションです。文字列です。 （Android）ベンダー識別子+
adidオプションです。文字列です。 （Android）Google Playサービスの広告ID
android_idオプションです。文字列です。 （Android）Android ID（広告IDではありません）
event_idオプションです。整数です。 （オプション）同一のuser_idやタイムスタンプを有するイベントを互いに区別できるインクリメンタルカウンター。Amplitudeは、特にイベントが同時に発生することが予想される場合に、時間をかけて増加させる event_id を送信することを推奨しています。
session_idオプションです。Long型。セッションの開始時刻（エポックからのミリ秒、Unixタイムスタンプ）。イベントを特定のシステムに関連付ける際に必要になります。「-1」のsession_idは、session_idの指定がないのと同じ状態です。
insert_idオプションです。文字列です。 イベントの一意の識別子です。 Amplitudeでは、過去7日以内に同じdevice_idおよびinsert_idでイベントが送信された場合、後続の重複イベントは削除されます。Amplitudeでは、UUIDを生成するか、device_id、user_id、event_type、event_id、時間などの組み合わせを使用することを推奨しています。
planオプションです。オブジェクト。トラッキングプランのプロパティAmplitudeはブランチ、ソース、バージョンのプロパティのみをサポートしています。
plan.branchオプションです。文字列です。 トラッキング計画のブランチ名。 たとえば、「main」などです。
plan.sourceオプションです。文字列です。 トラッキング計画のソース。例：「web」
plan.versionオプションです。文字列です。 トラッキング計画のバージョン。たとえば、「1」、「15」などです。

オプション

名前概要
min_id_lengthオプションです。整数です。 user_idおよびdevice_idフィールドのデフォルトの最小長「5」を上書きします。

レスポンス

Amplitudeでは、リトライロジックを実装し、イベント内でinsert_id（同じイベントの重複を排除する際に使用）を送信することを推奨しています。 リトライロジックやinsert_idを使用することで、APIが使用できない場合やリクエストが失敗した場合にイベントの損失や重複を防ぐことができます。

ログエラー

Amplitudeでは、200 以外のレスポンスをキャプチャするために独自のログを追加することをお勧めします。

200

200 OK：リアルタイムイベントのアップロードに成功しました。200 OKのレスポンスが届かない場合は、リクエストをリトライしてください。

json
{
  "code": 200,
  "events_ingested": 50,
  "payload_size_bytes": 50,
  "server_upload_time": 1396381378123
}
名前概要
code整数。200成功コード
events_ingested整数です。 アップロード要求から取り込まれたイベントの数。
payload_size_bytes整数です。 アップロード要求ペイロードのサイズ（バイト単位）。
server_upload_timeLong型。Amplitudeのイベントサーバーがアップロードリクエストを受け入れた時点からの時間（エポック（Unixタイムスタンプ）をミリ秒単位で表記）。

400

400 不正なリクエストです。 400は、無効なアップロード要求を示します。詳細については、応答を確認してください。

無効なリクエストの考えられる理由：

  • リクエスト本文は有効なJSONではありません。「Invalid JSON request body」というerrorが返されます。
  • リクエスト本文に必須フィールドがありません。 「Request missing required field」というerrorが返され、不足しているフィールドが示されます。
  • イベントのオブジェクトに無効なフィールドがあります。events_with_invalid_fieldsは、エラーを返す最初のイベントのインデックスにフィールド名をマップします。
  • 一部のデバイスはサイレント状態です。

プロパティ（JSONが無効であるか、または存在しません）

名前概要
code整数。400エラーコード
error文字列です。 エラーの説明。 使用可能な値：Invalid request path、Missing request body、Invalid JSON request body、Request missing required field、Invalid event JSON、Invalid API key、Invalid field values on some events
missing_field文字列です。 欠落しているリクエストレベルの必須フィールドを示します。
events_with_invalid_fieldsオブジェクト。フィールド名からエラーが発生した最初のイベントのインデックスを含む配列へのマップ。
events_with_missing_fieldsオブジェクト。フィールド名からエラーが発生した最初のイベントのインデックスを含む配列へのマップ。

プロパティ（SilencedDeviceID）

名前概要
code整数。400エラーコード
error文字列です。 エラーの説明。
eps_threshold整数です。 アプリの現行イベント数/秒のしきい値。このレートを超えると、リクエストは制限されます。
exceeded_daily_quota_devicesオブジェクト。アプリの日次イベント割り当て数を超過したすべてのデバイスに対する、「device_id」から現在の日次イベント数へのマップ。
silenced_devices[文字列]です。 Amplitudeがサイレント状態のdevice_idの配列。
silenced_events[整数です]。 events配列内のインデックスの配列で、device_idがサイレント化されたイベントを示します。
throttled_devicesオブジェクト。アプリの現在のしきい値を超えているすべてのデバイスについて、device_id からその現在のイベント/秒レートへのマップ。
throttled_events[整数です]。 イベント配列内のインデックス配列で、user_idまたはdevice_idがスロットリングされているイベントを示します。

403 (禁止されています)

403 禁止されています。 Amplitudeのウェブアプリケーションファイアウォール（WAF）がリクエストをブロックしました。

この応答の考えられる理由：

  • リクエストのヘッダー、本文、またはURI内にAmplitudeセキュリティフィルターに一致する無効な値が含まれています。
  • リクエストは、Amplitudeがリクエストを受け入れることを許可されていない制裁対象地域から送信されました。
json
{
  "code": 403,
  "error": "Forbidden"
}

プロパティ

名前概要
code整数です。403エラーコード
error文字列です。 エラーの説明。

413（ペイロードが大きすぎます）

413ペイロードが大きすぎます。ペイロードサイズが大きすぎます（要求サイズが1 MBを超えています）。イベント配列ペイロードを複数のリクエストに分割し、再度お試しください。

json
{
  "code": 413,
  "error": "Payload too large"
}

プロパティ

名前概要
code整数です。413エラーコード
error文字列です。 エラーの説明。

429（リクエスト数が多すぎます）

429リクエストが多すぎます。ユーザーまたはデバイスに対するリクエストが多すぎます。 Amplitudeは、1秒間に30イベントを超えるユーザーおよびデバイスに対するリクエストを抑制します。これは、最近の時間枠内の平均値として測定されます。 そのユーザーまたはデバイスに対するイベントの送信を30秒間一時停止してから、再試行してください。429応答がなくなるまで再試行を続行してください。

json
{
  "code": 429,
  "error": "Too many requests for some devices and users",
  "eps_threshold": 30,
  "throttled_devices": {
    "C8F9E604-F01A-4BD9-95C6-8E5357DF265D": 31
  },
  "throttled_users": {
    "datamonster@amplitude.com": 32
  },
  "throttled_events": [3, 4, 7]
}

プロパティ

名前概要
code整数です。429エラーコード
error文字列です。 エラーの説明。
eps_threshold整数です。 アプリの現行イベント数/秒のしきい値。このレートを超えると、リクエストは制限されます。
throttled_devicesオブジェクト。アプリの現在のしきい値を超過しているすべてのデバイスに対する、device_idから現在のイベントレート（回/秒）へのマップ。
throttled_usersオブジェクト。アプリの現在のしきい値を超過しているすべてのユーザーに対する、user_idからの現在のイベントレート（回/秒）へのマップ。
throttled_eventsイベント配列内のインデックス配列で、user_idまたはdevice_idがスロットリングされたイベントを示します。

サーバエラー 500、502、504

500、502、および504サーバーエラーです。Amplitudeはリクエストの処理中にエラーが発生しました。Amplitudeでは、このレスポンスを伴うリクエストを受け入れていない可能性があります。 リクエストを再試行した場合、再試行によってイベントが重複する可能性があります。 重複を回避するには、リクエストでinsert_idを送信してください。

503 サービスが利用できません

503 サービスが利用できません。 内部的なAmplitudeの問題が原因でリクエストが失敗しました。 503のレスポンスを伴うリクエストをリトライしても、イベントが重複するリスクはありません。

これは役に立ちましたか？