API Reference

This part of the documentation covers all the interfaces of twinl.

Main interface

All of the twinls’ functionality can be accessed by the following functions and classes.

twixl.collections.twinl.search(query, start_time=None, end_time=None, max_results=None, api=None, callback=None)[source]

Sends a TwiXL search query.

Parameters

query (Query) – A TwiXL query object that describes the search query.
start_time (Optional[datetime]) – The oldest UTC timestamp from which the Tweets will be provided.
end_time (Optional[datetime]) – The newest UTC timestamp from which the Tweets will be provided.
(Optional) (callback) – The maximum number of search results in query output. By default, all search results will be stored in the query output.
(Optional) – An initialized twixl Api object. If not provided, an object will be initialized.
(Optional) – Callback function taking a QueryStatus object.

Returns

SearchReuslts object

Return type

twinl.SearchResults

Usage:

>>> from twixl.collections import twinl
>>> query = (
>>>   twinl.Query().
>>>       and_(keywords=["example", "query"])
>>> )
>>> search_results = twinl.search(
>>>   query=query,
>>>   start_time=datetime(2022, 1, 1, 0, 0),
>>>   end_time=datetime(2022, 1, 1, 23, 59, 59),
>>>   max_results=100,
>>>   callback=twinl.print_callback
>>> )
Query status: RUNNING (0 Bytes scanned)
Query status: DOWNLOADING_RESULTS (1 GB scanned)
>>> SearchResults
SearchResults(...)

twixl.collections.twinl.word_frequency(date, min_length_words=1, max_results=None, frequency_limit=None, api=None, callback=None)[source]

Sends a word_frequency request to the TwiXL API for the specified date.

Parameters

date (datetime) – The date for which the word-frequency should be returned.
min_length_words (int) – The minimum word length of the words in the word-frequency list. The default minimum word length is ‘1’.
(Optional) (api) – The maximum number of search results in query output. By default, all search results will be stored in the query output.
(Optional) – The minimum occurence rate of the words in the word-frequency list. The default limit is ‘1’.
(Optional) – An initialized twixl Api object. If not provided, an object will be initialized.

Returns

WordFrequencyResults object

Return type

twinl.WordFrequencyResults

Usage:

>>> from twixl.collections import twinl
>>> word_frequencies = twinl.word_frequency(
>>>   date=datetime(2022, 1, 1),
>>>   min_length_words=2,
>>>   callback=twinl.print_callback
>>> )
Query status: RUNNING (0 Bytes scanned)
Query status: DOWNLOADING_RESULTS (1.0 GB scanned)
>>> word_frequencies.to_pandas()
  word        frequency
0 example     100
1 words       50

twixl.collections.twinl.tweet_metrics(api=None)[source]

Sends a get metrics request to the TwiXL Api and returns the results.

Parameters: (Optional) (api) – An initialized twixl Api object. If not provided, an object will be initialized.
Returns: TweetMetrics object
Return type: twinl.TweetMetrics

Usage:

>>> from twixl.collections import twinl
>>> metrics = twinl.tweet_metrics()
>>> merics.to_pandas()

class twixl.collections.twinl.Query[source]

A TwiXL query object to define a search query.

and_(keywords, regex=False)[source]

Add an AND query statement to the TwiXL.Query object.

Parameters

keywords (List[str]) – A list of keywords/regular expressions that you wish to find in the Twitter text.
(Optional) (regex) – if True, the list of keywords are a list of regular expressions. Defaults to False, the list of keywords are plain text words.

Returns

Query object

Return type

twinl.Query

Usage:

>>> from twixl.collections import Query
>>> Query().and_(['twi', 'xl'])

or_(keywords, regex=False)[source]

Add an OR query statement to the TwiXL.Query object.

Parameters

keywords (List[str]) – A list of keywords/regular expressions that you wish to find in the Twitter text.
regex (bool) – (Optional, boolean) if True, the list of keywords are a list of regular expressions. Defaults to False, the list of keywords are plain text words.

Returns

Query object

Return type

twinl.Query

Usage:

>>> from twixl.collections import Query
>>> Query().or_(['twi', 'xl'])

print()[source]

Print query in JSON format.

Return type: None

to_dict()[source]

Returns the TwiXL query as a dict.

Returns: Query object as dictionary.
Return type: dict

twixl.collections.twinl.API(api_endpoint, api_key)[source]

Plotting functons

This section of the documentation covers all the plotting functions.

twixl.collections.twinl.plotting.plot_tweet_frequencies(search_results, num_xticks=5, title='Number of tweets per day')[source]

Plot the TwiXL Query result in a frequency plot.

Parameters

search_results (SearchResults) – Twinl search results.
num_xticks (int) –
(Optional) (title) – The figure title.

Return type

Tuple[Figure, Axes]

Returns

Tweet frequency figure.

Usage:

>>> from twixl.collections import twinl
>>> twinl.plotting.plot_tweet_frequencies(
>>>   search_results,
>>>   title="Number of 'Elfstedentocht' tweets per day"
>>> )
(<Figure>, <AxesSubplot>)

twixl.collections.twinl.plotting.plot_word_cloud(word_frequency_results, width=800, height=400, max_words=200, stopwords=None, background_color='white', min_word_length=0)[source]

Plots the word-frequency list as a wordcloud.

Parameters

word_frequency_results (WordFrequencyResults) – Word frequency results.
width (int) – Width of the canvas.
height (int) – Height of the canvas.
max_words (int) – The maximum number of words in the wordcloud.
stopwords (Optional[List[str]]) – A list of stopwords that should be filtered from the wordcloud.
background_color (str) – Background color for the word cloud image.
min_word_length (int) – Minimum number of letters a word must have to be included.

Return type

Figure

Returns

Word cloud plot

Usage:

>>> from twixl.collections import twinl
>>> twinl.plotting.plot_word_cloud(
>>>   word_frequencies,
>>>   stopwords=stopwords,
>>>   max_words=100,
>>>   min_word_length=4
>>> );
<matplotlib.image.AxesImage>

twixl.collections.twinl.plotting.plot_circular_bars(word_frequency_results, stopwords=None, group_size=5)[source]

Plots the word-frequency list as a circular bar plot.

Parameters

stopwords (Optional[List[str]]) – A list of stopwords that should be filtered from the wordcloud.
group_size (int) – The number of bars per hour.

Usage:

>>> from twixl.collections import twinl
>>> twinl.plotting.plot_circular_bars(
>>>   word_frequencies,
>>>   stopwords=stopwords,
>>>   group_size=3
>>> );
(<Figure>, <PolarAxesSubplot>)

Return type: Tuple[Figure, Axes]

Exceptions

This section of the documentation covers all the exceptions.

exception twixl.collections.twinl.exceptions.QueryFailed(message='query has failed')[source]: The query failed.

exception twixl.collections.twinl.exceptions.QueryCanceled(message='query was canceled')[source]: The query is canceled.

exception twixl.collections.twinl.exceptions.QueryTimeout(timeout)[source]: The query timed out.

Lower-Level Classes

class twixl.collections.twinl.SearchResults(tweets)[source]

class twixl.collections.twinl.WordFrequencyResults(words)[source]

class twixl.collections.twinl.TweetMetrics(metrics)[source]