Pular para o conteúdo principal

​
Uso da API | Twitter API

​
Visão geral

Enterprise É a ferramenta mais importante — e a melhor — para ajudar a monitorar e gerenciar o uso das diferentes APIs da sua conta. Aviso importante: As contagens de uso retornadas pela Usage API podem não corresponder às de uma fatura devido a períodos de teste e outros ajustes de cobrança. Todos os números são baseados em atividades deduplicadas consumidas em um determinado dia (em UTC).

​
Recursos

  • Recuperação programática dos dados de uso disponíveis na interface do console.gnip.com
  • Dados de uso em nível de stream — fornece dados de uso no nível de stream (por exemplo, dev e prod), além do nível de produto
  • Dados granulares e descritivos — as “requests” de pesquisa são detalhadas por produto: Full-Archive e 30-Day Search
  • “days” e “jobs” do Historical PowerTrack 

​
APIs compatíveis

Abaixo está a lista de APIs atualmente compatíveis com a Usage API:
  • PowerTrack API enterprise
  • 30-Day Search API enterprise
  • Full-Archive Search API enterprise
  • Historical PowerTrack enterprise

​
Limitações

  • A API Usage permite acessar dados de uso desde 1º de maio de 2018. Após 1º de julho de 2019, a API Usage permite acessar dados de uso dos últimos 13 meses calendário
  • Você pode acessar dados de uso em intervalos de três meses, definidos com fromDate e toDate
Veja abaixo um exemplo de requisição e resposta: 
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"
}

​
Exemplo de payload

Abaixo está um exemplo do payload: 
{
  "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
              }
            }
          ]
        }
      ]
    }
  ]
}

​
Referência de API

​
get-usage

​
Métodos

MétodoDescrição
GET /metrics/usage/accounts/.jsonRecuperar dados de uso
Onde:
  • :account_name é o nome (sensível a maiúsculas e minúsculas) associado à sua conta, conforme exibido em console.gnip.com

​
Autenticação e limite de taxa

Autenticação
Todas as solicitações à Usage API exigem autenticação básica HTTP, usando qualquer credencial de e‑mail e senha habilitada na sua conta para acessar o console.gnip.com ou conectar-se a qualquer stream do Gnip.
Limite de taxa
A API Usage impõe um limite de taxa de duas solicitações por minuto.

​
Boas práticas e limitações

Disponibilidade de dados
Os dados de uso são baseados em atividades desduplicadas consumidas até o último período completo (UTC) em que os dados foram processados. Os dados geralmente são processados e atualizados em tempo quase real, exceto quando a Gnip está implementando sistemas.
  • A Usage API permite acessar dados de uso desde 1º de maio de 2018. Após 1º de julho de 2019, a Usage API permite acessar dados de uso dos últimos 13 meses do calendário.
  • Você pode acessar dados de uso em intervalos de três meses, definidos com fromDate e toDate

​
Solicitação e recebimento de dados

A Usage API funciona fazendo uma requisição HTTP GET com credenciais de HTTP BASIC-AUTH para o endpoint da API da sua conta.
Solicitação GET:
Faça uma solicitação GET para o seguinte endpoint com suas credenciais de usuário e nome da conta: https://gnip-api.x.com/metrics/usage/accounts/:account&#95;name.json Parâmetros adicionais
bucketOpcional. A unidade de tempo para a qual os dados de uso serão fornecidos. Os dados de uso podem ser retornados com granularidade diária ou mensal.

Solicitações feitas sem um bucket especificado retornarão a granularidade mensal.

Opções: ‘month’ ou ‘day’
fromDate (YYYYMMDDHHMM)Opcional. Os dados de uso estão disponíveis apenas a partir de 1º de maio de 2018. O carimbo de data/hora UTC mais antigo a partir do qual os dados de uso serão fornecidos. O carimbo de data/hora tem granularidade de dia e é inclusivo (ou seja, 201805010000 inclui o dia 0501). Solicitações que contiverem valores diferentes de ‘0000’ para a granularidade de hora e minuto serão ajustadas para ‘0000’.

Solicitações feitas sem fromDate ou toDate retornarão dados de uso por mês para o mês atual e incluirão uma referência histórica dos dois meses anteriores.

Atenção: A partir de 1º de junho de 2019, você pode acessar os últimos 13 meses corridos de dados de uso. Por exemplo, se fosse 10 de outubro, você poderia acessar dados de uso até 1º de setembro do ano anterior.
Exemplo: 201810010000 retornará dados a partir de 1º de outubro de 2018, incluindo o próprio dia 1º de outubro.
toDate (YYYYMMDDHHMM)Opcional. O carimbo de data/hora UTC mais recente até o qual os dados de uso serão fornecidos. O carimbo de data/hora tem granularidade de dia e não é inclusivo (ou seja, 201703020000 não inclui dados para o dia 0302). Quando um toDate é especificado para o dia atual ou um dia no futuro, os dados de uso serão retornados até o último dia completo (UTC). Solicitações que contiverem valores diferentes de ‘0000’ para a granularidade de hora e minuto serão ajustadas para ‘0000’.

Uma solicitação sem toDate terá como padrão o próximo bucket (amanhã para bucket=day e o próximo mês para bucket=month). Uma solicitação feita sem fromDate e toDate terá como padrão bucket=month e mostrará dados para o mês atual mais os dois meses imediatamente anteriores.

Exemplo: 201703050000 retornará dados até 5 de março de 2017, sem incluir quaisquer dados de 5 de março.
Exemplo de solicitação GET Esta solicitação retornará dados com granularidade mensal de 1º de março de 2017 a 5 de março de 2017, sem incluir quaisquer dados de 5 de março de 2017. curl -u “https://gnip-api.x.com/metrics/usage/accounts/:account&#95;name.json?bucket=month&amp;fromdate=201403010000&amp;toDate=201403150000”

​
Formato de dados

As tabelas a seguir descrevem as estruturas de dados no nível raiz para os dados de uso retornados pela Usage API. Para fields com vários níveis de subfields, clique nos links fornecidos para ver detalhes sobre os subfields. Se você quiser ver um exemplo de um payload completo da Usage API, visite esta página.
accountObjeto que representa a conta para a qual os dados de uso foram solicitados.
bucketA unidade de tempo para a qual os dados de uso são fornecidos. Pode ser “day” ou “month”.
fromDateO carimbo de data/hora em UTC mais antigo para o qual você deseja obter dados de uso (inclusivo).
toDateO carimbo de data/hora em UTC mais recente para o qual você deseja obter dados de uso (exclusivo).
publishersInclui três objetos principais: used, projected e products.
⌘I