API利用ガイドライン

HubSpotでは、すべてのユーザーに安定した品質をお届けするために、公開APIの利用状況を詳しくモニタリングしています。アプリや連携のすべての開発に際し、HubSpot利用規定APIに関する利用条件に従っていただく必要があります。HubSpotはAPIの変更や廃止の権利を有するものとしますが、そのような場合は常に変更ログ(英語)を通じて事前に開発者の皆さまへの通知を行います。

認証とセキュリティー

最適なセキュリティーを実現するために、すべてのアプリにはHubSpotのOAuthプロトコルをお使いいただく必要があります。このプロトコルに準拠したTTL(time-to-live)データの保存と、ユーザー アクセス トークンのリフレッシュは、アプリ側で責任を持って実装いただくことになります。OAuthアクセストークンの生成時には、リフレッシュまでのAPI呼び出しに使用できる期間を示すexpires_inパラメーターが含まれています。Unauthorized (401)(認証されていない)リクエストは、新しいアクセストークンを取得する必要性を示す指標とはなりません。

API利用状況の確認

OAuthを使ったアプリ

アプリの設定でAPI呼び出しのモニタリングを使用します。

APIキーによる連携

GET /integrations/v1/limit/daily*により、現在日のAPI呼び出し数や制限リセット時期を確認します。「現在日」は、接続したアカウントのタイムゾーン設定に基づく深夜0時から深夜0時を1日として測定されます。 

*1日のAPI制限に対する、このエンドポイントへの呼び出しのカウント。

 

必須パラメーター 説明 使い方
HubSpot APIキー API利用状況の確認対象とするHubSpotアカウントのAPIキー。 URLでhapikey=を使用

 

GET URLの例:

https://api.hubapi.com/integrations/v1/limit/daily?hapikey=demo

このエンドポイントから返されたデータは、5分間キャッシュに格納されます。キャッシュされたものかどうかを調べるには、レスポンスの中のfetchStatusフィールドとcollectedAtフィールドを確認します

レスポンスの例:

JSON
// [
  {
    "name": "api-calls-daily",
    "usageLimit": 1000000,
    "currentUsage": 31779,
    "collectedAt": 1560189939285,
    "fetchStatus": "SUCCESS",
    "resetsAt": 1560204000000
  }
]

resetsAtフィールドは、制限がリセットされる時刻のUnixタイムスタンプ(ミリ秒単位)です。制限は、アカウントのタイムゾーン設定に基づいて深夜0時にリセットされます。

キャッシュレスポンスの例:

JSON
// [
  {
    "name": "api-calls-daily",
    "usageLimit": 1000000,
    "currentUsage": 31779,
    "collectedAt": 1560189939285,
    "fetchStatus": "CACHED",
    "resetsAt": 1560204000000
  }
]

キャッシュからのレスポンスの場合、fetchStatusCACHEDで、collectedAtはキャッシュ最終更新時を示すUnixタイムスタンプ(ミリ秒単位)です。

レート制限

OAuthを使ったアプリ

OAuthを使ったアプリに対する制限は、10秒あたり100回のリクエストだけです(検索APIを除く。下記の「その他の制限」を参照)。API追加機能に関連する制限は適用されません。

APIキーによる連携

APIキーによる連携には、下記の1日あたりの制限が適用されます(検索APIを除く。下記の「その他の制限」を参照)。1日あたりの制限は、接続したアカウントのタイムゾーン設定に基づいて深夜0時にリセットされます。 

 

製品プラン

制限

無料版、Starter

瞬間(バースト):10秒あたり100

1日あたり:250,000

Professional、Enterprise

瞬間(バースト):10秒あたり150

1日あたり:500,000 

API追加機能(すべてのプラン)

瞬間(バースト):10秒あたり200 

1日あたり:1,000,000

 

エラーレスポンス

レート制限を超えたアプリまたは連携は、その後のすべてのAPI呼び出しに対し、429のエラーレスポンスを受け取ることになります。エラーレスポンスが返されるリクエストの数が、1日の合計リクエスト数の5%を超えないようにしてください。アプリマーケットプレイスへのアプリの掲載を予定している場合、この5%の制限を守っていただく必要があります。 

429レスポンスの形式を次に示します。 

JSON
//Example
{
  "status": "error",
  "message": "You have reached your daily limit.",
  "errorType": "RATE_LIMIT",
  "correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24",
  "policyName": "DAILY",
  "requestId": "3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd"
}

messagepolicyNameは、どちらの上限に達したかを示します(日次制限または2次制限)。

1日あたりの制限は、タイムゾーン設定に基づいて深夜0時にリセットされます。

各APIリクエストのレスポンスには、次のレート制限ヘッダーが含まれます。注:これらのヘッダーは、APIキーを使用して行われたリクエストにのみ含まれます。

ヘッダー 説明
X-HubSpot-RateLimit-Daily 1日あたり可能なAPIリクエストの数。
X-HubSpot-RateLimit-Daily-Remaining 現在日に利用可能な残りのAPIリクエストの数。
X-HubSpot-RateLimit-Interval-Milliseconds X-HubSpot-RateLimit-MaxヘッダーとX-HubSpot-RateLimit-Remainingヘッダーが適用される時間。

例えば、値が10000なら10秒間を表します。
X-HubSpot-RateLimit-Max X-HubSpot-RateLimit-Interval-Millisecondsで示された時間内で可能なリクエストの数。

例えば、このヘッダー値が100で、X-HubSpot-RateLimit-Interval-Millisecondsヘッダーが10000の場合、適用された制限は10秒あたり100リクエストです。
X-HubSpot-RateLimit-Remaining  X-HubSpot-RateLimit-Interval-Millisecondsで示された時間内で利用可能な残りのAPIリクエストの数


:X-HubSpot-RateLimit-SecondlyヘッダーとX-HubSpot-RateLimit-Secondly-Remainingヘッダーが含まれている場合、データ自体は正確ですが、この2つのヘッダーで参照されている制限は既に適用されなくなり、廃止されたものとお考えください。

こちらのエンドポイントを使用することにより、現在日に使用された呼び出し数を確認することもできます。

TEN_SECONDLY_ROLLINGの制限に到達した場合は、アプリで発行するリクエストをスロットリングして制限内に収めてください。リクエストのスロットリングと併用するために、または1日あたりの制限に達する場合、以下の対策を参照してください。

これらの方法を検討しても呼び出し制限に到達する場合は、開発者フォーラム(英語)までご連絡ください。ご使用のAPIに関する利用状況や到達した制限など、できるだけ詳しい情報をご提供ください。

繰り返し呼び出すデータをキャッシュする

サイトまたはアプリの各ページの読み込み時にHubSpotからのデータを使用する場合は、HubSpot APIで毎回リクエストするのではなく、データのキャッシュ処理によってキャッシュからデータを読み込むようにしてください。一括処理のためにアカウント設定を取得する呼び出しを繰り返し行う場合(オブジェクトのプロパティー、担当者、またはフォーム設定を取得するなど)、こうした設定情報についても可能な限りキャッシュ処理を行ってください。

可能な限り一括APIを使用する

時間の影響を受けにくいデータを扱う場合は、データを1つずつ処理するよりも、複数の更新処理を定期的な一括処理としてまとめるほうが効果的です。 

CRMオブジェクト(コンタクト、会社、取引など)を扱う場合、さまざまな一括処理のメソッドを利用できます。

Webhookを使用してHubSpotから最新データを取得する

HubSpot Marketing Enterprise契約をご利用の場合、ワークフロー内でWebhookアクションを使用してコンタクトレコードのデータを貴社のシステムに送信できます。Webhookは、どのワークフローのアクションとしてもトリガー可能なため、コンタクトデータを貴社のシステムに送信するための条件としてどのようなワークフロー開始条件でも使用できます。Webhookの詳しい使い方については、こちらを参照してください。また、Webhookデータの例についてはこちら(英語)をご覧ください。

 

サービスの制限

HubSpotのサービスの制限と価格については、こちらをご覧ください。


その他の制限

  • 開発者アカウントにつきアプリ100個まで作成可能
  • 1アプリあたり1,000件までのWebhookサブスクリプションを作成可能
  • 1アプリあたり最大25個のCRM拡張機能を作成可能
  • 1アプリあたり最大750個のタイムライン イベント タイプを作成可能
  • 1つのタイムライン イベント タイプにつき最大500個のプロパティーを作成可能
  • 検索APIエンドポイントのレート制限:認証トークン1つにつき1秒あたり4つのリクエストまで

関連ドキュメント

アプリ内でのAPI利用状況の確認