twitterapi.tweets.recent_search module

recent_search.py: Implementation of Twitter recent search endpoint.

“The recent search endpoint allows you to programmatically access filtered public Tweets posted over the last week, and is available to all developers who have a developer account and are using keys and tokens from an App within a Project.” (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 recent search:

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

query = '(#test OR @projekt_sparta) -is:retweet'
starttime = datetime(2022, 12, 21, 0, 0)
endtime = datetime(2022, 12, 24, 0, 0)

async for tweet_response in get_recent_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 recent search query:

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

query = '(#test OR @projekt_sparta) -is:retweet'
starttime = datetime(2022, 12, 21, 0, 0)
endtime = datetime(2022, 12, 24, 0, 0)

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

async sparta.twitterapi.tweets.recent_search.get_recent_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 from the last 7 days that match the specified query.

This function queries the Twitter API to find tweets matching the given search criteria within the last 7 days. It uses an internal instance of RateLimiter to handle rate limiting, automatically pausing requests if the rate limit is exceeded.

Parameters:

query (str) – The search query for matching Tweets. Refer to https://t.co/rulelength to identify the max query length. How to build a rule:
https – //developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/integrate/build-a-rule
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’). Defaults to None.

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.recent_search.get_recent_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 | None = None) → AsyncGenerator[SearchCount, None]

Asynchronously retrieves the count of tweets matching a specified search query from the last 7 days, aggregated according to a specified granularity.

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

Parameters:

query (str) – The search query for matching Tweets. Refer to https://t.co/rulelength to identify the max query length. How to build a rule:
https – //developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/integrate/build-a-rule
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 (e.g., ‘minute’, ‘hour’, or ‘day’).

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, if an HTTP error occurs that prevents retrieving the tweet counts, 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.