Usage API

Usage API は、エンタープライズアカウントに紐づく各種プロダクトにおける利用量に、プログラムからアクセスし可視化できる無料の REST API です。

​

利用状況 API | Twitter API

​

概要

Enterprise

これは、アカウント配下のさまざまな API における利用状況を監視および管理するための、最も重要かつ 最適な ツールです。

重要な免責事項:

Usage API から返される利用量は、トライアルやその他の請求調整により、請求書に記載される数値と一致しない場合があります。すべての数値は、ある 1 日 (UTC) に消費された重複排除済みのアクティビティに基づいています。

​

機能

• console.gnip.com の UI で利用可能な使用状況データをプログラムで取得
• ストリームレベルの使用状況データ - プロダクトレベルに加え、ストリームレベル (例: dev と prod) での使用状況データを提供
• きめ細かくわかりやすいデータ - 検索の「requests」は Full-Archive と 30-Day Search 各プロダクトごとに区分
• PowerTrack の履歴「days」と「jobs」 

​

対応している API

以下は、Usage API が現在サポートしている API のリストです。

• PowerTrack API enterprise
• 30-Day Search API enterprise
• Full-Archive Search API enterprise
• Historical PowerTrack enterprise

​

制限事項

• Usage API を使用すると、2018 年 5 月 1 日以降の利用状況データにアクセスできます。2019 年 7 月 1 日以降は、Usage API を使用して、直近 13 か月間の各暦月分 の利用状況データにアクセスできます。

• fromDate と toDate で定義される 3 か月間の期間 ごとに、利用状況データにアクセスできます。

以下にリクエストとレスポンスの例を示します。

curl -u<username>:<password> \
"https://gnip-api.x.com/metrics/usage/accounts/<account-name>.json?bucket=month"

{
  "account": {
    "name": "accountnamehere"
  },
  "publishers": [
    {
      "type": "twitter",
      "used": [
        {
          "timePeriod": "201805010000",
          "activities": 1235,
          "searchRequests30Day": 3,
          "searchRequestsFullArchive": 19,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        },
        {
          "timePeriod": "201806010000",
          "activities": 23467,
          "searchRequests30Day": 0,
          "searchRequestsFullArchive": 66,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        },
        {
          "timePeriod": "201807010000",
          "activities": 431,
          "searchRequests30Day": 11,
          "searchRequestsFullArchive": 4,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        }
      ],
      "projected": {
        "timePeriod": "201807010000",
        "activities": 803,
        "searchRequests30Day": 20,
        "searchRequestsFullArchive": 7,
        "historicalPowertrackDays": 0,
        "historicalPowertrackJobs": 0
      },
      "products": [
        {
          "type": "Historical PowerTrack サブスクリプション",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201806010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201807010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 0,
            "days": 0,
            "jobs": 0
          }
        },
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 267
            },
            {
              "timePeriod": "201806010000",
              "activities": 3
            },
            {
              "timePeriod": "201807010000",
              "activities": 32
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 59
          },
          "endpoints": [
            {
              "type": "PowerTrack 2.0",
              "label": "actformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 0
              }
            },
              {
              "type": "PowerTrack Replay 2.0",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 0
              }
            }
          ]
        },
        {
          "type": "Search API（30日間）2.0",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 10,
              "searchRequests30Day": 3
            },
            {
              "timePeriod": "201806010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201807010000",
              "activities": 23,
              "searchRequests30Day": 11
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 42,
            "searchRequests30Day": 20
          },
          "endpoints": [
            {
              "type": "Search API（30日間）2.0",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 10,
                  "searchRequests30Day": 3
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 21,
                  "searchRequests30Day": 10
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 39,
                "searchRequests30Day": 18
              }
            }
          ]
        },
        {
          "type": "Search API（全アーカイブ）",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 961,
              "searchRequestsFullArchive": 19
            },
            {
              "timePeriod": "201806010000",
              "activities": 23466,
              "searchRequestsFullArchive": 66
            },
            {
              "timePeriod": "201807010000",
              "activities": 379,
              "searchRequestsFullArchive": 4
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 706,
            "searchRequestsFullArchive": 7
          },
          "endpoints": [
            {
              "type": "Search API（全アーカイブ）",
              "label": "actformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 1,
                  "searchRequestsFullArchive": 3
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 2,
                  "searchRequestsFullArchive": 1
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 3,
                "searchRequestsFullArchive": 1
              }
            },
            {
              "type": "Search API（全アーカイブ）",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 961,
                  "searchRequestsFullArchive": 16
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 23466,
                  "searchRequestsFullArchive": 66
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 379,
                  "searchRequestsFullArchive": 3
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 706,
                "searchRequestsFullArchive": 5
              }
            }
          ]
        }
      ]
    }
  ],
  "bucket": "month",
  "fromDate": "201805010000",
  "toDate": "201808010000"
}

​

ペイロードのサンプル

以下はペイロードの例です。

{
  "account": {
    "name": "gnip-username"
  },
  "bucket": "month",
  "publishers": [
    {
      "type": "automattic",
      "used": [
        {
          "activities": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201603010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "dev",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            }
          ]
        }
      ]
    },
    {
      "type": "twitter",
      "used": [
        {
          "activities": 84,
          "searchRequests30Day": 4,
          "searchRequestsFullArchive": 0,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "searchRequests30Day": 0,
        "searchRequestsFullArchive": 0,
        "historicalPowertrackDays": 0,
        "historicalPowertrackJobs": 0,
        "timePeriod": "201601010000"
      },
      "products": [
        {
          "type": "Historical PowerTrack 2.0",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 11884,
              "days": 5,
              "jobs": 5
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            }
          ]
        },
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 27456
            },
            {
              "timePeriod": "201601010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 2930
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "devel-v2",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 24542
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "devel-v2-1",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            }
          ]
        },
        {
          "type": "Search API",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequests30Day": 0
          },
          "endpoints": [
            {
              "type": "Search API",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequests30Day": 0
              }
            }
          ]
        },
        {
          "type": "Search API (30-Day)",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequests30Day": 0
          },
          "endpoints": [
            {
              "type": "Search API (30-Day)",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequests30Day": 0
              }
            }
          ]
        },
        {
          "type": "Search API (Full-Archive)",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequestsFullArchive": 0
          },
          "endpoints": [
            {
              "type": "Search API (Full-Archive)",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequestsFullArchive": 0
              }
            }
          ]
        }
      ]
    }
  ]
}

​

APIリファレンス

​

get-usage

​

Methods

Method	Description
GET /metrics/usage/accounts/.json	使用状況データを取得します

Where:

• :account_name は、console.gnip.com に表示されるアカウントに関連付けられた名前で、大文字と小文字が区別されます

​

認証とレート制限

Authentication

Usage API へのすべてのリクエストには HTTP Basic 認証が必要です。console.gnip.com へのログインや任意の Gnip ストリームへの接続に使用している、アカウントで有効化されている任意のメールアドレス／パスワードの認証情報を使用してください。

レート制限

Usage API では、1 分あたり 2 件のリクエストというレート制限が適用されます。

​

ベストプラクティスと制限事項

データの可用性

利用状況データは、データが処理された最後の完全な時間帯 (UTC) までに消費された、重複排除済みのアクティビティに基づいています。通常、データは分単位まで処理・更新されますが、Gnip がシステムをデプロイしている場合はこの限りではありません。

• Usage API により、2018 年 5 月 1 日以降の利用状況データにアクセスできます。2019 年 7 月 1 日以降は、Usage API により、直近 13 か月間 の利用状況データにアクセスできます。

• fromDate と toDate で定義される 3 か月ごとの期間 で、利用状況データにアクセスできます。

​

データの要求と受信

Usage API は、アカウントの API エンドポイントに対して HTTP BASIC-AUTH 認証情報を付与した HTTP GET リクエストを送信することで動作します。

GET リクエスト:

ユーザー認証情報とアカウント名を使用して、次のエンドポイントに GET リクエストを送信します。

https://gnip-api.x.com/metrics/usage/accounts/:account_name.json

Additional Parameters

bucket	任意。利用状況データが提供される時間の単位です。利用状況データは日単位または月単位の粒度で取得できます。 bucket を指定せずにリクエストした場合、月単位の粒度で返されます。 指定可能な値: ‘month’ または ‘day’
fromDate (YYYYMMDDHHMM)	任意。利用状況データは 2018 年 5 月 1 日以降のみ利用可能です。利用状況データが提供される最も古い UTC タイムスタンプを指定します。タイムスタンプは日単位の粒度で、その日付を含みます (例: 201805010000 には 05/01 の 1 日分が含まれます) 。時刻 (時および分) に ‘0000’ 以外の値が指定されたリクエストは、‘0000’ に切り捨てられます。 fromDate または toDate を指定せずに行われたリクエストは、当月分の月単位の利用状況データと、過去 2 か月分の履歴データを返します。 注意: 2019 年 6 月 1 日以降、過去 13 か月分のカレンダー月ベースの利用状況データにアクセスできます。たとえば、10 月 10 日の場合、前年の 9 月 1 日までさかのぼって利用状況データにアクセスできます。 例: 201810010000 を指定すると、2018 年 10 月 1 日以降のデータが返され、10 月 1 日分も含まれます。
toDate (YYYYMMDDHHMM)	任意。利用状況データが提供される最新の UTC タイムスタンプを指定します。タイムスタンプは日単位の粒度で、その日付は含まれません (例: 201703020000 には 03/02 の 1 日分のデータは含まれません) 。toDate に当日または将来の日付が指定された場合、利用状況データは直近の完全な 1 日分 (UTC) まで返されます。時刻 (時および分) に ‘0000’ 以外の値が指定されたリクエストは、‘0000’ に切り捨てられます。 toDate を指定しないリクエストでは、次の bucket (bucket=day の場合は翌日、bucket=month の場合は翌月) がデフォルトになります。fromDate と toDate の両方を指定せずに行われたリクエストでは、bucket=month がデフォルトとなり、当月分と直近 2 か月分のデータが返されます。 例: 201703050000 を指定すると、2017 年 3 月 5 日までのデータが返されますが、3 月 5 日分のデータは含まれません。

Example GET Request

次のリクエストは、2017 年 3 月 1 日から 2017 年 3 月 5 日までの月単位の粒度でデータを返しますが、2017 年 3 月 5 日分のデータは含まれません。

curl -u “https://gnip-api.x.com/metrics/usage/accounts/:account_name.json?bucket=month&fromdate=201403010000&toDate=201403150000”

​

Data Format

以下のテーブルでは、Usage API から返される利用状況データのルートレベルのデータ構造について説明します。複数レベルのサブフィールドを持つフィールドについては、リンクをクリックするとサブフィールドの詳細を表示できます。

Usage API のペイロード全体のサンプルを確認したい場合は、このページをご覧ください。

account	利用状況データがリクエストされたアカウントを表すオブジェクト。
bucket	利用状況データが提供される時間単位。‘day’ または ‘month’ のいずれか。
fromDate	取得したい利用状況データの、最も早い UTC タイムスタンプ (含む) 。
toDate	取得したい利用状況データの、最も遅い UTC タイムスタンプ (含まない) 。
publishers	Used、projected、products という 3 つの主要なオブジェクトを含みます。