Usage API

Die Usage API ist eine kostenlose REST-API, die Ihrem Enterprise-Konto programmgesteuerten Zugriff und Einblick in die Nutzung von Aktivitäten über alle Produkte hinweg ermöglicht.

​

Nutzungs-API | Twitter API

​

Übersicht

Enterprise

Dies ist das wichtigste und beste Tool, um die Nutzung der verschiedenen APIs in Ihrem Konto zu überwachen und zu verwalten.

Wichtiger Hinweis:

Die von der Usage API zurückgegebenen Nutzungszahlen können aufgrund von Testphasen und anderen Abrechnungsanpassungen von den Werten auf einer Rechnung abweichen. Alle Zahlen basieren auf deduplizierten Aktivitäten innerhalb eines jeweiligen Tages (in UTC).

​

Funktionen

• Programmgesteuertes Abrufen von Nutzungsdaten, die in der Benutzeroberfläche von console.gnip.com verfügbar sind
• Nutzungsdaten auf Stream-Ebene – zusätzlich zur Produktebene werden Nutzungsdaten auf Stream-Ebene (z. B. Dev und Prod) bereitgestellt
• Granulare und aussagekräftige Daten – Suchanfragen („requests“) werden nach den Produkten Full-Archive und 30‑Day Search aufgeschlüsselt
• Historische PowerTrack‑„days“ und „jobs“ 

​

Unterstützte APIs

Nachfolgend finden Sie eine Liste der APIs, die derzeit von der Usage-API unterstützt werden:

• PowerTrack API enterprise
• 30-Day Search API enterprise
• Full-Archive Search API enterprise
• Historical PowerTrack enterprise

​

Einschränkungen

• Die Usage API ermöglicht den Zugriff auf Nutzungsdaten seit dem 1. Mai 2018. Ab dem 1. Juli 2019 ermöglicht die Usage API den Zugriff auf Nutzungsdaten für die zurückliegenden 13 Kalendermonate.

• Sie können auf Nutzungsdaten in Dreimonatsintervallen zugreifen, die mit einem fromDate und einem toDate definiert sind.

Siehe unten eine Anfrage & Antwort:

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"
}

​

Beispiel-Payload

Nachfolgend finden Sie ein Beispiel der 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
              }
            }
          ]
        }
      ]
    }
  ]
}

​

API-Referenz

​

get-usage

​

Methoden

Methode	Beschreibung
GET /metrics/usage/accounts/.json	Nutzungsdaten abrufen

Dabei gilt:

• :account_name ist der (Groß-/Kleinschreibung beachtende) Name, der Ihrem Konto zugeordnet ist, wie auf console.gnip.com angezeigt

​

Authentifizierung und Rate Limit

Authentifizierung

Alle Anfragen an die Usage API erfordern die HTTP-Basic-Authentifizierung. Verwenden Sie dazu beliebige E‑Mail-/Passwort-Anmeldedaten, die für Ihr Konto aktiviert sind, um sich unter console.gnip.com anzumelden oder eine Verbindung zu einem beliebigen Gnip-Stream herzustellen.

Rate Limit

Die Usage-API erzwingt eine Rate Limit von zwei Anfragen pro Minute.

​

Best Practices & Einschränkungen

Datenverfügbarkeit

Nutzungsdaten basieren auf deduplizierten Aktivitäten aus dem letzten vollständigen Zeitraum (UTC), in dem data verarbeitet wurde. data wird in der Regel minutengenau verarbeitet und aktualisiert, außer wenn Gnip Systeme bereitstellt.

• Die Usage API ermöglicht den Zugriff auf Nutzungsdaten seit dem 1. Mai 2018. Ab dem 1. Juli 2019 ermöglicht die Usage API den Zugriff auf Nutzungsdaten der zurückliegenden 13 Kalendermonate.

• Sie können auf Nutzungsdaten in Dreimonatsintervallen zugreifen, definiert mit fromDate und toDate.

​

Anfordern und Empfangen von Daten

Die Usage API funktioniert, indem sie eine HTTP-GET-Anfrage mit HTTP-BASIC-AUTH-Zugangsdaten an das API-endpoint für Ihr Konto sendet.

GET-Anfrage:

Senden Sie eine GET-Anfrage an den folgenden endpoint mit Ihren Benutzeranmeldedaten und Ihrem Kontonamen:

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

Zusätzliche Parameter

bucket	Optional. Die Zeiteinheit, für die Nutzungsdaten bereitgestellt werden. Nutzungsdaten können mit täglicher oder monatlicher Granularität zurückgegeben werden. Anfragen ohne angegebenes bucket liefern eine monatliche Granularität. Optionen: ‘month’ oder ‘day’
fromDate (YYYYMMDDHHMM)	Optional. Nutzungsdaten sind erst ab dem 1. Mai 2018 verfügbar. Der älteste UTC-Zeitstempel, ab dem die Nutzungsdaten bereitgestellt werden. Der Zeitstempel hat Tagesgranularität und ist inklusiv (d. h. 201805010000 umfasst den Tag 0501). Anfragen, die andere Werte als ‘0000’ für Stunden- und Minutengranularität enthalten, werden auf ‘0000’ zurückgesetzt. Anfragen ohne fromDate oder toDate geben Nutzungsdaten monatsweise für den aktuellen Monat zurück und enthalten eine historische Referenz für die vergangenen zwei Monate. Bitte beachten: Ab dem 1. Juni 2019 können Sie auf die vergangenen 13 Kalendermonate an Nutzungsdaten zugreifen. Wenn es beispielsweise der 10. Oktober ist, können Sie auf Nutzungsdaten bis zum 1. September des Vorjahres zugreifen. Beispiel: 201810010000 gibt Daten ab dem 1. Oktober 2018 zurück, einschließlich des 1. Oktober.
toDate (YYYYMMDDHHMM)	Optional. Der neueste UTC-Zeitstempel, bis zu dem die Nutzungsdaten bereitgestellt werden. Der Zeitstempel hat Tagesgranularität und ist nicht inklusiv (d. h. 201703020000 enthält keine Daten für den Tag 0302). Wenn ein toDate für den aktuellen Tag oder einen zukünftigen Tag angegeben wird, werden Nutzungsdaten bis zum letzten vollen Tag (UTC) zurückgegeben. Anfragen, die andere Werte als ‘0000’ für Stunden- und Minutengranularität enthalten, werden auf ‘0000’ zurückgesetzt. Eine Anfrage ohne toDate verwendet standardmäßig den nächsten bucket (morgen für bucket=day und nächsten Monat für bucket=month). Eine Anfrage ohne fromDate und toDate verwendet standardmäßig bucket=month und zeigt Daten für den aktuellen Monat sowie die zwei unmittelbar vorangegangenen Monate. Beispiel: 201703050000 gibt Daten bis zum 5. März 2017 zurück, ohne Daten vom 5. März.

Beispiel einer GET-Anfrage

Diese Anfrage gibt Daten mit monatlicher Granularität vom 1. März 2017 bis zum 5. März 2017 zurück, ohne Daten vom 5. März 2017.

curl -u “https://gnip-api.x.com/metrics/usage/accounts/:account_name.json?bucket=month&fromdate=201403010000&toDate=201403150000”

​

Datenformat

Die folgenden Tabellen beschreiben die Datenstrukturen auf Root-Ebene für Nutzungsdaten, die von der Usage API zurückgegeben werden. Für Felder mit mehreren Ebenen von Unterfeldern klicken Sie auf die bereitgestellten Links, um Details zu den Unterfeldern anzuzeigen.

Wenn Sie ein Beispiel einer vollständigen Usage API-Payload sehen möchten, besuchen Sie bitte diese Seite.

account	Ein Objekt, das das Konto repräsentiert, für das Nutzungsdaten angefordert wurden.
bucket	Die Zeiteinheit, für die Nutzungsdaten bereitgestellt werden. Kann entweder „day“ oder „month“ sein.
fromDate	Der früheste UTC-Zeitstempel, für den Sie Nutzungsdaten abrufen möchten (einschließlich).
toDate	Der späteste UTC-Zeitstempel, für den Sie Nutzungsdaten abrufen möchten (ausschließlich).
publishers	Enthält drei primäre Objekte: Used, projected und products.