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

​
使用状況 API | Twitter API

​
概要

Enterprise これは、アカウント配下の各種 API 全体の使用状況を監視・管理するうえで、最も重要かつ_最適_なツールです。 重要な注意事項: Usage API によって返される使用量は、トライアルやその他の課金調整により、請求書の金額と一致しない場合があります。すべての数値は、特定の日（UTC）において消費された重複排除済みのアクティビティに基づきます。

​
機能

  • console.gnip.com の UI で確認できる使用状況データをプログラムで取得可能
  • stream レベルの使用状況データ — 製品レベルに加え、stream レベル（例: dev、prod）での使用状況データを提供
  • 詳細かつ説明的なデータ — 検索の「requests」は Full-Archive と 30-Day Search の各製品ごとに内訳を提供
  • Historical 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 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使用状況データを取得
ここで:
  • :account_name は、console.gnip.com に表示されるアカウントに紐づく名前で、大小文字を区別します

​
認証とレートリミット

認証
Usage API へのすべてのリクエストは、HTTP Basic Authentication を必要とします。console.gnip.com へのログインや任意の Gnip stream への接続に使用している、アカウントで有効なメールアドレスとパスワードのいずれかの組み合わせを認証情報として使用してください。
レートリミット
Usage API は、1 分あたり 2 件のリクエストというレートリミットを適用します。

​
ベストプラクティスと制約

データ可用性
利用状況データは、data が処理された最後の完全な時間帯（UTC）までに取り込まれた重複排除済みのアクティビティに基づきます。Gnip がシステムをデプロイしている場合を除き、データは通常、分単位で処理・更新されます。
  • Usage API を使用すると、2018年5月1日以降の利用状況データにアクセスできます。2019年7月1日以降は、Usage API により、直近13か月の利用状況データにアクセスできます。
  • fromDate と toDate で定義された3か月単位で利用状況データにアクセスできます

​
データのリクエストと受信

Usage API は、アカウントの API endpoint に対して HTTP BASIC-AUTH の認証情報を用いた HTTP GET リクエストを送信することで動作します。
GET リクエスト:
ユーザーの認証情報とアカウント名を用いて、次の endpoint に対して 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 日を含め、同日以降のデータを返します。
toDate (YYYYMMDDHHMM)任意。使用量データが提供される最新の UTC タイムスタンプを指定します。タイムスタンプは日単位の粒度で、非包含です（例: 201703020000 には 03/02 のデータは含まれません）。toDate に当日または将来の日付を指定した場合、使用量データは直近の完全な 1 日分（UTC）まで返されます。時・分に ‘0000’ 以外の値を指定したリクエストは ‘0000’ に丸められます。

toDate を省略した場合、次の bucket にデフォルトします（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 タイムスタンプ（含まない）。
publishers3 つの主要なオブジェクト（Used、projected、products）を含む。
⌘I