twitterapi.tweets.full_search module

full_seach.py: Implementation of Twitter Full-archive search endpoint.

“The v2 full-archive search endpoint is only available to Projects with Academic Research access. The endpoint allows you to programmatically access public Tweets from the complete archive dating back to the first Tweet in March 2006, based on your search query.” (Source: https://developer.twitter.com/en/docs/twitter-api/tweets/search/introduction)

Find the Open API Spec under: https://api.twitter.com/2/openapi.json

Examples

Get Tweets from full search:

import os
import json
os.environ["BEARER_TOKEN"] = "xxxxxxxxxxx"
from datetime import datetime
from sparta.twitterapi.tweets.full_search import get_full_search

query = '(#test OR @projekt_sparta) -is:retweet'
starttime = datetime(2021, 6, 1, 0, 0)
endtime = datetime(2021, 10, 4, 0, 0)

async for tweet_response in get_full_search(query=query, start_time=starttime, end_time=endtime):
    print(json.dumps(tweet_response.tweet))
    print(json.dumps(tweet_response.includes))

Get estimated number for full search query:

import os
os.environ["BEARER_TOKEN"] = "xxxxxxxxxxx"
from datetime import datetime
from sparta.twitterapi.tweets.full_search import get_full_search_count

query = '(#test OR @projekt_sparta) -is:retweet'
starttime = datetime(2021, 6, 1, 0, 0)
endtime = datetime(2021, 10, 4, 0, 0)

count = sum(
    [count.tweet_count async for count in get_full_search_count(query=query, start_time=starttime, end_time=endtime, granularity="day")]
)

async sparta.twitterapi.tweets.full_search.get_full_search(query: str, start_time: datetime | None = None, end_time: datetime | None = None, since_id: str | None = None, until_id: str | None = None, sort_order: str | None = None) → AsyncGenerator[TweetResponse, None]

Asynchronously retrieves tweets that match a specified search query.

This function queries the Twitter API to find tweets matching the given search criteria. It handles rate limiting using an internal instance of RateLimiter, automatically pausing requests if the rate limit is exceeded.

Parameters:

query (str) – The search query for matching Tweets. Refer to Twitter API documentation for details on query format and limitations.
start_time (datetime, optional) – The oldest UTC timestamp from which tweets will be provided. Inclusive and in second granularity.
end_time (datetime, optional) – The newest UTC timestamp to which tweets will be provided. Exclusive and in second granularity.
since_id (str, optional) – Returns results with a Tweet ID greater than this ID.
until_id (str, optional) – Returns results with a Tweet ID less than this ID.
sort_order (str, optional) – The order in which to return results (e.g., ‘recency’ or ‘relevancy’).

Yields:

TweetResponse – An object representing the tweet data for each tweet that matches the query.

Raises:

Exception – If an HTTP error occurs that prevents retrieving the tweets or if the query parameters are invalid.

Note

The function automatically handles pagination of results using the ‘next_token’ provided by Twitter’s API response.

async sparta.twitterapi.tweets.full_search.get_full_search_count(query: str, start_time: datetime | None = None, end_time: datetime | None = None, since_id: str | None = None, until_id: str | None = None, granularity: str = 'hour') → AsyncGenerator[SearchCount, None]

Asynchronously retrieves the count of tweets matching a specified search query, aggregated according to a specified granularity (e.g., hourly).

This function queries the Twitter API to count tweets matching the given search criteria and aggregates the counts based on the specified granularity. It handles rate limiting using an internal instance of RateLimiter, automatically pausing requests if the rate limit is exceeded.

Parameters:

query (str) – The search query for matching Tweets. Refer to Twitter API documentation for query format and limitations.
start_time (datetime, optional) – The oldest UTC timestamp from which tweet counts will be provided. Inclusive and in second granularity.
end_time (datetime, optional) – The newest UTC timestamp to which tweet counts will be provided. Exclusive and in second granularity.
since_id (str, optional) – Returns results with a Tweet ID greater than this ID.
until_id (str, optional) – Returns results with a Tweet ID less than this ID.
granularity (str, optional) – The granularity for the search counts results (‘minute’, ‘hour’, or ‘day’). Defaults to ‘hour’.

Yields:

SearchCount – An object representing the tweet count data for each interval according to the specified granularity.

Raises:

Exception – If an invalid granularity is specified or if an HTTP error occurs that prevents retrieving the tweet counts.

Note

The function automatically handles pagination of results using the ‘next_token’ provided by Twitter’s API response.