You can access tweets with the Twitter API using a few different methods. For this project, the recent search method is used. This involves creating a hyperlink that contains the search parameters to filter the tweets that you're getting.

Twitter has documentation on the available parameters that you can use with v2 of the API:

The goal for this project is to see the most recent tweets that contain a hashtag (#partyparrot) that are sent to a specific user. This means that your hyperlink query will look like this:

  • ' to:blitzcitydiy'

Notice that there is a space between the hashtag and to: queries. If you want to add more options to your query, they just need to be separated by a space.

This URL is going to be used in the CircuitPython code as the data source for the JSON feed. You'll access that feed in order to pull data to trigger your sprite animation.

Introducing the Twitter API To Your CircuitPython Code

After all of the setup comes the fun part: bringing the Twitter API information into the CircuitPython code. 

First, bear is created as a variable to hold your Bearer token. This is needed to access the API. It's imported from your file.

Then DATA_SOURCE is setup to hold your query URL and DATA_LOCATION is setup to list your JSON path information, which will be important in the main loop.

A MatrixPortal object is created using the adafruit_matrixportal library. This allows your MatrixPortal M4 to connect to the internet and then access your query URL to pull down your desired data via the filtered JSON path.

bear = secrets['bearer_token']

DATA_SOURCE = (' to:blitzcitydiy')
DATA_LOCATION = ["meta", "newest_id"]

matrixportal = MatrixPortal(

The Twitter API requires a Bearer token to authorize access to the query URL. This is sent as a header along with the request made with the adafruit_matrixportal library. You can setup headers using matrixportal.set_headers().

After the header is created, a few states are setup for use in the loop. Their functions are commented below.

matrixportal.set_headers({'Authorization': 'Bearer ' + bear})

last_value = 0 #  checks last tweet's ID
check = 0 #  time.monotonic() holder
parrot = False #  state to track if an animation is currently running
party = 0 #  time.monotonic() holder
p = 0 #  index for tilegrid
party_count = 0 #  count for animation cycles

In the loop, the code is running matrixportal.fetch() to check and see if a new tweet has been sent that matches the query parameters.

This data stream is stored as value and holds the JSON path information. In this case, it's the most recent tweet's ID number.

This ID number is compared to the previous tweet's ID number, which is stored in last_value. If they are not a match, then this means that a new tweet with matching parameters has been received and the parrot state is updated to True.

while True:
    if (check + 30) < time.monotonic():
        value = matrixportal.fetch()
        print("Response is", value)
        check = time.monotonic()
        if last_value != value:
            print("new party!")
            last_value = value
            parrot = True
            print("no new party... :(")

When party is True, the party parrot begins animating on the LED matrix. The entire animation cycle is played 16 times and is tracked with party_count. After 16 cycles, the animation stops and all of the states are reset to await the next tweet.

if parrot:
        if (party + 0.1) < time.monotonic():
            parrot_grid[0] = p
            p += 1
            party = time.monotonic()
            if p > 9:
                p = 0
                party_count += 1
                print("party parrot", party_count)
            if party_count > 15:
                parrot = False
                party_count = 0
                p = 0
                parrot_grid[0] = 10
                print("the party is over")


You shouldn't feel limited by the parameters of this party project though. You can setup custom queries looking at a wide variety of filters for Twitter, whether it be hashtags, emoji usage, retweets, etc.

You can also include any sprite animation that you want. Perhaps you want a different animation for different Twitter notifications. There are definitely many ways that you could customize this project for your own needs.

This guide was first published on Oct 06, 2020. It was last updated on Jun 15, 2024.

This page (Getting and Parsing Tweets) was last updated on Mar 08, 2024.

Text editor powered by tinymce.