Historische Posts über den v2 Full-Archive-Suche-endpoint abrufen

​

Einführung

Die Search Posts endpoints in der v2-Welt ermöglichen es Ihnen, Posts zu Themen von Interesse zu erhalten, basierend auf einer von Ihnen erstellten query. Mit v2 Search Posts stehen zwei verschiedene endpoints zur Verfügung: recent search, die allen Entwicklern mit einem genehmigten Konto zur Verfügung steht und Posts bis zu sieben Tage alt durchsuchen kann, und full-archive search, die nur für Forscher verfügbar ist, die für den Academic Research product track zugelassen sind, und die das gesamte Archiv von Posts bis zurück bis März 2006 durchsuchen kann.

Unser vollständiges Suchangebot finden Sie auf unserer search overview page.

Diese Search Posts endpoints decken einen der häufigsten Anwendungsfälle für akademische Forscher ab, die sie für Langzeitstudien oder zur Analyse eines früheren Themas oder Ereignisses nutzen könnten.

Dieses Tutorial bietet eine Schritt-für-Schritt-Anleitung für Forscher, die das full-archive search endpoint verwenden möchten, um die vollständige Historie öffentlicher X data zu durchsuchen. Es zeigt außerdem verschiedene Möglichkeiten zum Erstellen eines Datensatzes, etwa durch Abrufen geotaggter Posts, sowie das Paging durch die verfügbaren Posts für eine query.

​

Voraussetzungen

Derzeit ist dieses endpoint nur im Rahmen des Academic Research-Produkttarifs verfügbar. Um dieses endpoint zu verwenden, müssen Sie einen Zugriff beantragen. Erfahren Sie mehr über die Antragstellung und Anforderungen für diesen Tarif.

​

Eine App mit dem Academic Project verbinden

Sobald Sie für die Nutzung des Academic Research-Produkttracks zugelassen sind, sehen Sie Ihr Academic Project im Entwicklerportal. Klicken Sie im Abschnitt „Projects and Apps“ auf „Add App“, um Ihre X App mit dem Project zu verbinden.

Anschließend können Sie entweder eine vorhandene App auswählen und sie mit Ihrem Project verbinden (wie unten gezeigt).

Oder Sie können eine neue App erstellen, ihr einen Namen geben und auf „Complete“ klicken, um eine neue App mit Ihrem Academic Project zu verbinden.

Dadurch erhalten Sie Ihre API Keys und Bearer Token, die Sie dann verwenden können, um sich mit dem Full-Archive Search endpoint zu verbinden.

Bitte beachten

Die Keys im obigen Screenshot sind ausgeblendet, aber in Ihrem eigenen Entwicklerportal können Sie die tatsächlichen Werte für die API Key, API Secret Key und Bearer Token sehen. Speichern Sie diese Keys und den Bearer Token, da Sie diese für Aufrufe des Full-Archive Search endpoint benötigen.

​

Verbindung mit dem Full-Archive-Such-endpoint

Der cURL-Befehl unten zeigt, wie Sie historische Posts vom @XDevelopers Handle abrufen können. Ersetzen Sie $BEARER_TOKEN durch Ihr eigenes Bearer Token, fügen Sie die vollständige Anfrage in Ihr Terminal ein und drücken Sie die Eingabetaste.

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'

Sie sehen die JSON-Antwort.

Standardmäßig werden nur die 10 neuesten Posts zurückgegeben. Wenn Sie mehr als 10 Posts pro Anfrage benötigen, können Sie den Parameter max_results verwenden und ihn, wie unten gezeigt, auf maximal 500 Posts pro Anfrage setzen:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Abfragen erstellen

Wie in den obigen Beispielaufrufen zu sehen, können Sie mit dem Parameter query die data festlegen, nach denen Sie suchen möchten. Wenn Sie beispielsweise alle Posts abrufen möchten, die das Wort covid oder das Wort coronavirus enthalten, können Sie den Operator OR in Klammern verwenden; Ihre Abfrage könnte dann (covid OR coronavirus) lauten, und Ihr API-Aufruf würde folgendermaßen aussehen:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Ähnlich gilt: Wenn Sie alle Posts abrufen möchten, die das Wort covid19 enthalten und keine Retweets sind, können Sie den Operator is:retweet mit dem logischen NICHT (dargestellt durch -) verwenden. Ihre query kann also covid19 -is:retweet lauten und Ihr API-Aufruf ist:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Siehe diese Anleitung mit einer vollständigen Liste der Operatoren, die im Full-Archive-Such-endpoint unterstützt werden.

​

Verwenden der Parameter start_time und end_time, um historische Posts abzurufen

Bei Verwendung des Full-Archive-Such-endpoints werden standardmäßig Posts der letzten 30 Tage zurückgegeben. Wenn Sie Posts abrufen möchten, die älter als 30 Tage sind, können Sie die Parameter start_time und end_time in Ihrem API-Aufruf verwenden. Diese Parameter müssen im gültigen Datum‑Uhrzeit-Format gemäß RFC3339 vorliegen, zum Beispiel 2020-12-21T13:00:00.00Z. Wenn Sie also alle Posts vom XDevelopers-Konto für den Monat Dezember 2020 abrufen möchten, lautet Ihr API-Aufruf:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Abrufen historischer, mit Geotags versehener Posts

Mit Geotags versehene Posts sind Posts, denen geografische Informationen wie Stadt, Bundesland und Land zugeordnet sind.

​

Verwendung des Operators has:geo

Wenn Sie Posts abrufen möchten, die Geodaten enthalten, können Sie den Operator has:geo verwenden. Beispielsweise ruft die folgende cURL-Anfrage nur die Posts vom Handle @XDevelopers ab, die Geodaten enthalten:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

​

Verwenden des place_country-Operators

Ebenso können Sie Posts mit Geodaten auf ein bestimmtes Land beschränken, indem Sie den place_country-Operator verwenden. Der folgende cURL-Befehl ruft alle Posts vom Handle @XDevelopers aus den Vereinigten Staaten ab:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--header 'Authorization: Bearer XXXXX'

Das Land wird oben mithilfe des ISO-Alpha-2-Codes angegeben. Gültige ISO-Codes finden Sie hier.

​

Abrufen von mehr als 500 historischen Posts mit dem next_token

Wie oben erwähnt, können Sie standardmäßig pro Anfrage an das Full-Archive-Such-endpoint nur bis zu 500 Posts abrufen. Wenn für Ihre Abfrage mehr als 500 Posts verfügbar sind, enthält Ihre JSON-Antwort ein next_token, das Sie an Ihren API-Aufruf anhängen können, um die nächsten verfügbaren Posts für diese Abfrage zu erhalten. Dieses next_token ist im meta-Objekt Ihrer JSON-Antwort enthalten und sieht in etwa so aus:

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

Daher verwenden Sie, um die nächsten verfügbaren Posts abzurufen, den Wert next_token aus diesem meta- Objekt und übergeben diesen Wert als next_token in Ihrem API-Aufruf an das full-archive search endpoint wie unten gezeigt (Sie verwenden Ihr eigenes Bearer Token und den Wert für den Next Token, den Sie bei Ihrem vorherigen API-Aufruf erhalten haben).

curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'

Auf diese Weise können Sie fortlaufend prüfen, ob ein next_token verfügbar ist, und wenn Sie Ihre gewünschte Anzahl von Posts noch nicht erreicht haben, können Sie das Full-Archive-endpoint weiterhin mit dem neuen next_token für jede Anfrage aufrufen. Beachten Sie, dass das Full-Archive-Such-endpoint auf Ihr gesamtes Post cap angerechnet wird, also auf die Anzahl der Posts pro Monat, die Sie über die X API pro Project erhalten können. Achten Sie daher beim Paging durch die Ergebnisse auf Ihre Code-Logik, um sicherzustellen, dass Sie nicht unbeabsichtigt Ihr Post cap ausschöpfen.

Nachfolgend finden Sie einige Ressourcen, die Ihnen bei der Verwendung des Full-Archive-Such-endpoints helfen können. Wir freuen uns über Ihr Feedback. Kontaktieren Sie uns unter @XDevelopers oder in unseren community forums mit Fragen zu diesem endpoint.

​

Zusätzliche Ressourcen

• API-Referenz zum Full-Archive-Search-endpoint
• Grundlagen zum Erstellen einer Suchabfrage