메인 콘텐츠로 건너뛰기

​
Usage API | Twitter API

​
개요

Enterprise 이는 계정에 속한 다양한 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 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-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 기본 인증이 필요합니다. console.gnip.com에 계정으로 로그인하거나 Gnip 스트림에 연결할 때 사용하는 계정의 활성화된 이메일/비밀번호 자격 증명 중 아무 것이나 사용할 수 있습니다.
요청 한도
Usage API는 분당 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&#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가 지정된 경우, 사용량 데이터는 마지막으로 완료된 전체 일자(UTC)까지 반환됩니다. 시와 분이 ‘0000’이 아닌 값을 포함하는 요청은 기본적으로 ‘0000’으로 처리됩니다.

toDate가 없는 요청은 다음 버킷으로 기본값이 설정됩니다(bucket=day인 경우 내일, bucket=month인 경우 다음 달). fromDate와 toDate가 모두 없으면 기본적으로 bucket=month로 처리되며, 현재 달과 바로 이전 두 달의 데이터를 표시합니다.

예: 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가 반환하는 사용량 데이터의 루트 수준 데이터 구조를 설명합니다. 하위 필드가 여러 단계로 구성된 경우, 제공된 링크를 클릭해 하위 필드의 상세 정보를 확인하세요. 전체 Usage API 페이로드 예시를 보려면 이 페이지를 방문하세요.
account사용량 데이터가 요청된 계정을 나타내는 객체입니다.
bucket사용량 데이터가 제공되는 시간 단위입니다. ‘day’ 또는 ‘month’일 수 있습니다.
fromDate조회하려는 사용량 데이터의 가장 이른 UTC 타임스탬프(포함)입니다.
toDate조회하려는 사용량 데이터의 가장 늦은 UTC 타임스탬프(제외)입니다.
publishers세 가지 기본 객체를 포함합니다: used, projected, products.