メインコンテンツへスキップ

​
使用状況 API | Twitter API

​
概要

エンタープライズ アカウント配下の各種 API 全体における利用状況の監視と管理に役立つ、最も重要で、かつ_最良_のツールです。 重要な免責事項: トライアルやその他の課金調整により、Usage API が返す利用数が請求書の金額と一致しない場合があります。すべての数値は、特定の日（UTC）において消費された重複排除後のアクティビティに基づいています。

​
機能

  • console.gnip.com の UI にある使用状況データをプログラムで取得
  • ストリーム単位の使用状況データ - プロダクト単位に加え、ストリーム（例：dev、prod）単位の使用状況データを提供
  • 粒度の高いわかりやすいデータ - 検索の「requests」を Full-Archive と 30-Day Search の各プロダクトごとに内訳表示
  • Historical PowerTrack の「days」と「jobs」 

​
サポート対象の API

以下は、Usage API が現在サポートしている API の一覧です:
  • PowerTrack API エンタープライズ
  • 30-Day Search API エンタープライズ
  • Full-Archive Search API エンタープライズ
  • Historical PowerTrack エンタープライズ

​
制限事項

  • 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 Subscription",
          "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-Day) 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-Day) 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 (Full-Archive)",
          "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 (Full-Archive)",
              "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 (Full-Archive)",
              "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

​
メソッド

メソッド説明
GET /metrics/usage/accounts/.json使用状況データを取得
Where:
  • :account_name は、console.gnip.com に表示されるあなたのアカウントに関連付けられた（大文字と小文字を区別する）名前です

​
認証とレート制限

認証
Usage API へのすべてのリクエストには、HTTP ベーシック認証が必要です。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 認証の資格情報を用いた HTTP GET リクエストを送信することで動作します。
GET リクエスト:
以下のエンドポイントに、ユーザー認証情報とアカウント名を用いて GET リクエストを送信してください: https://gnip-api.x.com/metrics/usage/accounts/:account&#95;name.json 追加パラメータ
bucket任意。使用状況データを提供する時間単位。日次または月次の粒度で返せます。

bucket を指定しない場合は月次粒度で返されます。

指定可能値: ‘month’ または ‘day’
fromDate (YYYYMMDDHHMM)任意。使用状況データは 2018 年 5 月 1 日以降のみ利用可能です。提供される使用状況データの最古の UTC タイムスタンプです。タイムスタンプは日単位の粒度で、包含的です（例: 201805010000 は 05/01 当日を含みます）。時および分に ‘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 当日のデータを含みません）。toDate に当日または未来の日付を指定した場合、直近の完全な 1 日分（UTC）までのデータが返されます。時および分に ‘0000’ 以外の値が含まれるリクエストは ‘0000’ に丸められます。

toDate を省略した場合は次のバケットにデフォルトされます（bucket=day なら翌日、bucket=month なら翌月）。fromDate と toDate の両方を省略した場合は bucket=month がデフォルトとなり、当月分と直前 2 か月分のデータを表示します。

例: 201703050000 は 2017 年 3 月 5 日までのデータを返しますが、3 月 5 日のデータは含みません。
GET リクエスト例 このリクエストは、2017 年 3 月 1 日から 2017 年 3 月 5 日までの月次粒度のデータを返しますが、2017 年 3 月 5 日のデータは含みません。 curl -u “https://gnip-api.x.com/metrics/usage/accounts/:account&#95;name.json?bucket=month&amp;fromdate=201403010000&amp;toDate=201403150000”

​
データ形式

以下の表は、Usage API から返される使用状況データのルートレベルのデータ構造を説明します。複数レベルのサブフィールドを持つ fields については、リンクをクリックしてサブフィールドの詳細を表示してください。 Usage API の完全なペイロードのサンプルをご覧になりたい場合は、このページをご覧ください。
account使用状況データがリクエストされたアカウントを表すオブジェクト。
bucket使用状況データが提供される時間単位。‘day’ または ‘month’ のいずれか。
fromDate取得対象となる使用状況データの最も早い UTC タイムスタンプ（含む）。
toDate取得対象となる使用状況データの最新の UTC タイムスタンプ（含まない）。
publishers次の 3 つの主要オブジェクトを含む: used、projected、products。