Saltar al contenido principal

​
API de uso | API de Twitter

​
Descripción general

Empresarial Es la herramienta más importante y la mejor para ayudar a supervisar y gestionar el uso en las distintas API de su cuenta. Aviso importante: Los conteos de uso devueltos por la Usage API pueden no coincidir con los de una factura debido a periodos de prueba y otros ajustes de facturación. Todos los números se basan en actividades deduplicadas consumidas dentro de un día determinado (en UTC).

​
Características

  • Recuperación programática de datos de uso disponibles en la interfaz de console.gnip.com
  • Datos de uso a nivel de stream: proporciona datos a nivel de stream (p. ej., dev y prod) además del nivel de producto
  • Datos granulares y descriptivos: las “solicitudes” de búsqueda se desglosan entre los productos Full-Archive y 30-Day Search
  • “Días” y “tareas” de Historical PowerTrack 

​
APIs compatibles

A continuación se muestra una lista de las APIs actualmente compatibles con la Usage API:
  • PowerTrack API Empresarial
  • 30-Day Search API Empresarial
  • Full-Archive Search API Empresarial
  • Historical PowerTrack Empresarial

​
Limitations

  • La Usage API permite acceder a datos de uso desde el 1 de mayo de 2018. A partir del 1 de julio de 2019, la Usage API permite acceder a datos de uso de los últimos 13 meses calendario.
  • Puede acceder a datos de uso en intervalos de tres meses definidos con un fromDate y un toDate.
Vea a continuación una solicitud y su respuesta: 
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"
}

​
Ejemplo de carga

A continuación se muestra un ejemplo del 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
              }
            }
          ]
        }
      ]
    }
  ]
}

​
Referencia de API

​
obtener-uso

​
Métodos

MétodoDescripción
GET /metrics/usage/accounts/.jsonObtener datos de uso
Donde:
  • :account_name es el nombre (distingue mayúsculas y minúsculas) asociado a tu cuenta, tal como aparece en console.gnip.com

​
Autenticación y límite de velocidad

Autenticación
Todas las solicitudes a la Usage API requieren autenticación básica HTTP, usando cualquiera de las credenciales de correo electrónico y contraseña habilitadas en su cuenta para iniciar sesión en console.gnip.com o conectarse a cualquier stream de Gnip.
Límite de velocidad
La API de Usage impone un límite de 2 solicitudes por minuto.

​
Buenas prácticas y limitaciones

Disponibilidad de datos
Los datos de uso se basan en actividades deduplicadas consumidas hasta el último período completo (UTC) en el que se procesaron los datos. Por lo general, los datos se procesan y actualizan al minuto, excepto cuando Gnip está realizando despliegues de sistemas.
  • La Usage API le permite acceder a datos de uso desde el 1 de mayo de 2018. A partir del 1 de julio de 2019, la Usage API le permite acceder a datos de uso de los últimos 13 meses calendario.
  • Puede acceder a datos de uso en intervalos de tres meses definidos con fromDate y toDate

​
Solicitud y recepción de datos

La Usage API funciona realizando una solicitud HTTP GET con credenciales de autenticación básica (HTTP Basic Auth) al endpoint de la API de tu cuenta.
Solicitud GET:
Realiza una solicitud GET al siguiente endpoint con tus credenciales de usuario y el nombre de tu cuenta: https://gnip-api.x.com/metrics/usage/accounts/:account&#95;name.json Parámetros adicionales
bucketOpcional. La unidad de tiempo para la que se proporcionarán los datos de uso. Los datos de uso pueden devolverse con granularidad diaria o mensual.

Las solicitudes realizadas sin un bucket especificado devolverán datos con granularidad mensual.

Opciones: ‘month’ o ‘day’
fromDate (YYYYMMDDHHMM)Opcional. Los datos de uso solo están disponibles a partir del 1 de mayo de 2018. Es la marca de tiempo UTC más antigua desde la cual se proporcionarán los datos de uso. La marca de tiempo tiene granularidad de día y es inclusiva (es decir, 201805010000 incluye el día 0501). Las solicitudes que incluyan valores distintos de ‘0000’ para la hora y los minutos se ajustarán a ‘0000’.

Las solicitudes realizadas sin fromDate o toDate devolverán datos de uso por mes para el mes en curso e incluirán una referencia histórica de los dos meses anteriores.

Ten en cuenta: A partir del 1 de junio de 2019, puedes acceder a los últimos 13 meses calendario de datos de uso. Por ejemplo, si fuera el 10 de octubre, puedes acceder a los datos de uso hasta el 1 de septiembre del año anterior.
Ejemplo: 201810010000 devolverá datos a partir del 1 de octubre de 2018, incluyendo el 1 de octubre.
toDate (YYYYMMDDHHMM)Opcional. La marca de tiempo UTC más reciente hasta la cual se proporcionarán los datos de uso. La marca de tiempo tiene granularidad de día y no es inclusiva (es decir, 201703020000 no incluye datos del día 0302). Cuando se especifica un toDate para el día actual o un día futuro, los datos de uso se devolverán hasta el último día completo (UTC). Las solicitudes que incluyan valores distintos de ‘0000’ para la hora y los minutos se ajustarán a ‘0000’.

Una solicitud sin toDate tendrá como valor predeterminado el siguiente bucket (mañana para bucket=day y el próximo mes para bucket=month). Una solicitud realizada sin fromDate ni toDate tendrá como valor predeterminado bucket=month y mostrará datos para el mes en curso más los dos meses inmediatamente anteriores.

Ejemplo: 201703050000 devolverá datos hasta el 5 de marzo de 2017, sin incluir ningún dato del 5 de marzo.
Ejemplo de solicitud GET Esta solicitud devolverá datos con granularidad mensual desde el 1 de marzo de 2017 hasta el 5 de marzo de 2017, sin incluir ningún dato del 5 de marzo 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 datos

Las siguientes tablas describen las estructuras de datos a nivel raíz de los datos de uso devueltos por la Usage API. Para los fields con múltiples niveles de subcampos, haz clic en los enlaces proporcionados para ver detalles sobre los subcampos. Si deseas ver un ejemplo de una carga completa de la Usage API, visita esta página.
accountObjeto que representa la cuenta para la que se solicitaron los datos de uso.
bucketUnidad de tiempo para la que se proporcionan los datos de uso. Puede ser “day” o “month”.
fromDateLa marca de tiempo UTC más temprana para la que deseas obtener datos de uso (inclusive).
toDateLa marca de tiempo UTC más reciente para la que deseas obtener datos de uso (exclusive).
publishersIncluye tres objetos principales: Used, projected y products.