Passer au contenu principal

​
API d’utilisation | Twitter API

​
Présentation

Enterprise Il s’agit de l’outil le plus important et le plus performant pour surveiller et gérer l’utilisation des différentes API associées à votre compte. Avertissement important : Les volumes d’utilisation renvoyés par l’API Usage peuvent ne pas correspondre à ceux d’une facture en raison des périodes d’essai et d’autres ajustements de facturation. Tous les chiffres sont basés sur des activités dédupliquées consommées au cours d’une journée donnée (en UTC).

​
Fonctionnalités

  • Récupération par programmation des données d’usage disponibles dans l’interface console.gnip.com
  • Données d’usage au niveau du stream - fournit des données d’usage au niveau du stream (p. ex. dev et prod) en plus du niveau du produit
  • Données granulaires et descriptives - les “requêtes” de recherche sont ventilées entre les produits Full-Archive et 30-Day Search
  • “Days” et “jobs” Historical PowerTrack 

​
API prises en charge

Ci-dessous figure la liste des API actuellement prises en charge par l’API Usage :
  • PowerTrack API enterprise
  • 30-Day Search API enterprise
  • Full-Archive Search API enterprise
  • Historical PowerTrack enterprise

​
Limites

  • L’API Usage vous permet d’accéder aux données d’utilisation depuis le 1er mai 2018. À partir du 1er juillet 2019, l’API Usage permet d’accéder aux données d’utilisation des 13 derniers mois calendaires
  • Vous pouvez accéder aux données d’utilisation par tranches de trois mois définies avec un fromDate et un toDate
Voir ci-dessous un exemple de requête et de réponse : 
curl -u<nom_utilisateur>:<mot_de_passe> \
"https://gnip-api.x.com/metrics/usage/accounts/<nom-compte>.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"
}

​
Exemple de payload

Ci-dessous, un exemple de 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
              }
            }
          ]
        }
      ]
    }
  ]
}

​
Référence API

​
get-usage

​
Méthodes

MéthodeDescription
GET /metrics/usage/accounts/.jsonRécupérer les données d’utilisation
Où :
  • :account_name est le nom (respectant la casse) associé à votre compte, tel qu’affiché sur console.gnip.com

​
Authentification et limite de taux

Authentification
Toutes les requêtes adressées à l’API Usage nécessitent une authentification HTTP Basic, en utilisant l’une des paires e‑mail/mot de passe activées sur votre compte pour vous connecter à console.gnip.com ou à tout stream Gnip.
Limite de taux
L’API Usage impose une limite de taux de deux requêtes par minute.

​
Bonnes pratiques et limitations

Disponibilité des données
Les données d’utilisation sont basées sur des activités dédupliquées, prises en compte jusqu’à la dernière période complète (UTC) de traitement. Elles sont généralement traitées et mises à jour à la minute près, sauf lors des déploiements de systèmes par Gnip.
  • L’API Usage permet d’accéder aux données d’utilisation depuis le 1er mai 2018. À compter du 1er juillet 2019, l’API Usage permet d’accéder aux données des 13 derniers mois calendaires.
  • Vous pouvez accéder aux données d’utilisation par intervalles de trois mois, définis avec les paramètres fromDate et toDate

​
Requête et réception de données

L’API Usage fonctionne en envoyant une requête HTTP GET, avec des informations d’identification HTTP Basic Auth, à l’endpoint de l’API de votre compte.
Requête GET :
Effectuez une requête GET vers l’endpoint suivant avec vos informations d’identification utilisateur et le nom de votre compte : https://gnip-api.x.com/metrics/usage/accounts/:account&#95;name.json Paramètres supplémentaires
bucketOptionnel. Unité de temps pour laquelle les données d’utilisation seront fournies. Les données d’utilisation peuvent être renvoyées avec une granularité quotidienne ou mensuelle.

Les requêtes effectuées sans bucket spécifié renverront une granularité mensuelle.

Options : ‘month’ ou ‘day’
fromDate (YYYYMMDDHHMM)Optionnel. Les données d’utilisation ne sont disponibles qu’à partir du 1er mai 2018. Horodatage UTC le plus ancien à partir duquel les données d’utilisation seront fournies. L’horodatage est à la granularité du jour et est inclusif (p. ex., 201805010000 inclut la journée 0501). Les requêtes contenant des valeurs autres que ‘0000’ pour l’heure et les minutes seront ramenées par défaut à ‘0000’.

Les requêtes effectuées sans fromDate ni toDate renverront des données d’utilisation par mois pour le mois en cours et incluront une référence historique pour les deux mois précédents.

Veuillez noter : à partir du 1er juin 2019, vous pouvez accéder aux 13 derniers mois calendaires de données d’utilisation. Par exemple, si nous sommes le 10 octobre, vous pouvez accéder aux données d’utilisation jusqu’au 1er septembre de l’année précédente.
Exemple : 201810010000 renverra des données à partir du 1er octobre 2018 inclus.
toDate (YYYYMMDDHHMM)Optionnel. Le dernier horodatage UTC jusqu’auquel les données d’utilisation seront fournies. L’horodatage est à la granularité du jour et n’est pas inclusif (p. ex., 201703020000 n’inclut pas les données pour la journée 0302). Lorsqu’un toDate est spécifié pour le jour en cours ou un jour futur, les données d’utilisation seront renvoyées jusqu’au dernier jour complet (UTC). Les requêtes contenant des valeurs autres que ‘0000’ pour l’heure et les minutes seront ramenées par défaut à ‘0000’.

Une requête sans toDate prendra par défaut le bucket suivant (demain pour bucket=day et le mois prochain pour bucket=month). Une requête sans fromDate ni toDate prendra par défaut bucket=month et affichera les données pour le mois en cours plus les deux mois immédiatement précédents.

Exemple : 201703050000 renverra des données jusqu’au 5 mars 2017, sans inclure aucune donnée du 5 mars.
Exemple de requête GET Cette requête renverra des données avec une granularité mensuelle du 1er mars 2017 au 5 mars 2017, sans inclure aucune donnée du 5 mars 2017. curl -u “https://gnip-api.x.com/metrics/usage/accounts/:account&#95;name.json?bucket=month&amp;fromdate=201403010000&amp;toDate=201403150000”

​
Format des données

Les tableaux suivants décrivent les structures de données au niveau racine pour les données d’utilisation renvoyées par l’API Usage. Pour les fields comportant plusieurs niveaux de sous‑champs, cliquez sur les liens fournis pour afficher les détails des sous‑champs. Si vous souhaitez voir un exemple d’un payload complet de l’API Usage, veuillez consulter cette page.
accountObjet représentant le compte pour lequel les données d’utilisation ont été demandées.
bucketUnité de temps pour laquelle les données d’utilisation sont fournies. Peut être « day » ou « month ».
fromDateL’horodatage UTC le plus ancien pour lequel vous souhaitez récupérer des données d’utilisation (inclus).
toDateL’horodatage UTC le plus récent pour lequel vous souhaitez récupérer des données d’utilisation (exclus).
publishersContient trois objets principaux : Used, projected et products.
⌘I