Usage API

Usage API는 엔터프라이즈 계정에서 여러 제품에 걸친 활동 사용량을 프로그램적으로 조회하고 파악할 수 있도록 해 주는 무료 REST API입니다.

​

사용량 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일) 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에 표시되는 계정 이름이며 대소문자를 구분합니다

​

인증 및 요청 제한

인증

Usage API에 대한 모든 요청에는 HTTP Basic 인증이 필요하며, console.gnip.com에 있는 계정에 로그인하거나 어떤 Gnip 스트림에 연결할 때 사용하는, 계정에서 사용 설정된 이메일/비밀번호 자격 증명 중 하나를 사용해야 합니다.

요청 한도

Usage API에는 분당 2회 요청으로 제한되는 rate limit이 적용됩니다.

​

모범 사례 및 제한 사항

데이터 가용성

사용량 데이터는 데이터가 처리된 마지막 전체 시간 구간(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 Request:

사용자 자격 증명과 계정 이름을 사용하여 다음 엔드포인트에 GET 요청을 보냅니다:

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

추가 매개변수

bucket	선택 사항. 사용량 데이터가 제공될 시간 단위입니다. 사용량 데이터는 일 단위 또는 월 단위 세분성으로 반환될 수 있습니다. bucket을 지정하지 않고 요청하는 경우 월 단위 세분성으로 반환됩니다. 옵션: ‘month’ 또는 ‘day’
fromDate (YYYYMMDDHHMM)	선택 사항. 사용량 데이터는 2018년 5월 1일부터만 제공됩니다. 사용량 데이터가 제공되는 가장 오래된 UTC 타임스탬프입니다. 타임스탬프는 일 단위 세분성이며 포함입니다(예: 201805010000에는 05-01 날짜가 포함됨). 시와 분 단위에 대해 ‘0000’ 이외의 값을 포함하는 요청은 ‘0000’으로 기본 설정됩니다. fromDate 또는 toDate 없이 이루어진 요청은 현재 월에 대한 월별 사용량 데이터와 직전 두 달에 대한 이력 데이터를 함께 반환합니다. 참고: 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을 기본값으로 사용합니다(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_name.json?bucket=month&fromdate=201403010000&toDate=201403150000”

​

데이터 형식

아래 표는 Usage API에서 반환되는 사용량 데이터의 루트 수준 데이터 구조를 설명합니다. 여러 단계의 하위 필드가 있는 필드는 제공된 링크를 클릭하여 하위 필드에 대한 상세 정보를 확인하세요.

전체 Usage API 페이로드 샘플을 확인하려면 이 페이지를 방문하세요.

account	사용량 데이터가 요청된 계정을 나타내는 객체입니다.
bucket	사용량 데이터가 제공되는 시간 단위입니다. ‘day’ 또는 ‘month’ 중 하나일 수 있습니다.
fromDate	사용량 데이터를 가져오려는 가장 이른 UTC 타임스탬프입니다(포함).
toDate	사용량 데이터를 가져오려는 가장 늦은 UTC 타임스탬프입니다(제외).
publishers	세 가지 기본 객체(Used, projected, products)를 포함합니다.