Usage API

Usage API est une API REST gratuite qui fournit un accès programmatique et une visibilité sur la consommation d’activité liée aux produits de votre compte entreprise.

​

API d’usage | API Twitter

​

Vue d’ensemble

Enterprise

C’est l’outil le plus important et le meilleur pour vous aider à surveiller et à gérer l’utilisation des différentes API associées à votre compte.

Avertissement important :

Les compteurs d’utilisation renvoyés par l’API Usage peuvent ne pas correspondre à ceux figurant sur 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’utilisation accessibles dans l’interface console.gnip.com
• Données d’utilisation au niveau du flux : fournit des données d’utilisation au niveau du flux (par exemple dev et prod) en plus du niveau produit
• Données granulaires et descriptives : les « requests » de recherche sont ventilées par produits Full-Archive et 30-Day Search 
• « days » et « jobs » Historical PowerTrack 

​

API prises en charge

Voici 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

​

Limitations

• L’API Usage vous permet d’accéder aux données d’utilisation depuis le 1er mai 2018. Depuis le 1er juillet 2019, l’API Usage vous permet d’accéder aux données d’utilisation pour les 13 derniers mois civils

• Vous pouvez accéder aux données d’utilisation par intervalles de trois mois définis par un fromDate et un toDate

Voir ci-dessous un exemple de requête et de réponse :

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": "API Search (archives complètes)",
          "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": "API Search (archives complètes)",
              "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": "API Search (archives complètes)",
              "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

Voici 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 de l’API

​

get-usage

​

Méthodes

Méthode	Description
GET /metrics/usage/accounts/.json	Récupérer les données d’utilisation

Où :

• :account_name correspond au nom associé à votre compte, pour lequel la casse est prise en compte, tel qu’il apparaît dans console.gnip.com

​

Authentification et limites de débit

Authentification

Toutes les requêtes adressées à l’API Usage nécessitent une authentification HTTP Basic, en utilisant n’importe quelles informations d’identification (e‑mail/mot de passe) actives sur votre compte, que vous utilisez pour vous connecter à console.gnip.com ou à n’importe quel flux Gnip.

Limite de débit

L’API Usage applique une limite de débit de deux requêtes par minute.

​

Bonnes pratiques et limitations

Disponibilité des données

Les données d’utilisation sont basées sur les activités dédupliquées consommées jusqu’à la dernière période complète (UTC) pendant laquelle les données ont été traitées. Les données 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 vous permet d’accéder aux données d’utilisation depuis le 1er mai 2018. Après le 1er juillet 2019, l’API Usage vous permet d’accéder aux données d’utilisation pour les 13 derniers mois civils. 

• Vous avez la possibilité d’accéder aux données d’utilisation par intervalles de trois mois définis avec un fromDate et un toDate

​

Demande et réception des données

L’API Usage fonctionne en envoyant une requête HTTP GET avec des identifiants HTTP BASIC-AUTH au point de terminaison d’API de votre compte.

Requête GET :

Effectuez une requête GET vers l’endpoint suivant avec vos identifiants utilisateur et le nom de votre compte :

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

Paramètres supplémentaires

bucket	Facultatif. L’unité de temps pour laquelle les données d’usage seront fournies. Les données d’usage peuvent être renvoyées avec une granularité quotidienne ou mensuelle. Les requêtes effectuées sans bucket spécifié renverront des données avec une granularité mensuelle. Options : ‘month’ ou ‘day’
fromDate (YYYYMMDDHHMM)	Facultatif. Les données d’usage ne sont disponibles qu’à partir du 1er mai 2018. L’horodatage UTC le plus ancien à partir duquel les données d’usage seront fournies. L’horodatage est à la granularité jour et est inclusif (c’est‑à‑dire que 201805010000 inclut le jour 0501). Les requêtes qui contiennent des valeurs autres que ‘0000’ pour la granularité heure et minute seront réinitialisées à ‘0000’. Les requêtes effectuées sans fromDate ni toDate renverront les données d’usage par mois pour le mois en cours et incluront une référence historique pour les deux mois précédents. Remarque : À partir du 1er juin 2019, vous pouvez accéder aux données d’usage des 13 derniers mois calendaires. Par exemple, si nous sommes le 10 octobre, vous pouvez accéder aux données d’usage jusqu’au 1er septembre de l’année précédente. Exemple : 201810010000 renverra les données à partir du 1er octobre 2018 inclus.
toDate (YYYYMMDDHHMM)	Facultatif. L’horodatage UTC le plus récent jusqu’où les données d’usage seront fournies. L’horodatage est à la granularité jour et n’est pas inclusif (c’est‑à‑dire que 201703020000 n’inclut pas les données pour le jour 0302). Lorsqu’un toDate est spécifié pour le jour en cours ou un jour futur, les données d’usage seront renvoyées jusqu’au dernier jour complet (UTC). Les requêtes qui contiennent des valeurs autres que ‘0000’ pour la granularité heure et minute seront réinitialisées à ‘0000’. Une requête sans toDate prendra par défaut le bucket suivant (demain pour bucket=day et le mois suivant pour bucket=month). Une requête effectuée 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 les données jusqu’au 5 mars 2017, sans inclure aucune donnée du 5 mars.

Exemple de requête GET

Cette requête renverra les 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_name.json?bucket=month&fromdate=201403010000&toDate=201403150000”

​

Format des données

Les tableaux suivants décrivent les structures de données de niveau racine pour les données d’usage renvoyées par l’API Usage. Pour les champs 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 de charge utile complète de l’API Usage, veuillez consulter cette page.

account	Un objet représentant le compte pour lequel les données d’usage ont été demandées.
bucket	L’unité de temps pour laquelle les données d’usage sont fournies. Peut être « day » ou « month ».
fromDate	L’horodatage UTC le plus ancien à partir duquel vous souhaitez récupérer les données d’usage (inclus).
toDate	L’horodatage UTC le plus récent jusqu’auquel vous souhaitez récupérer les données d’usage (exclus).
publishers	Contient trois objets principaux : Used, projected et products.