code, howto

Collecting Tweets using Google Scripts (Part 1)

Requirements:

*In order to create apps on your Twitter account, you need to verify it using a mobile phone number. For that, you can use your own phone number or, if you have a Google account, create one using Google Voice.

Creating your Twitter App

Naming your App

After logging into your Twitter account, proceed to apps.twitter.com. This is where you will register your app, get your API information, and control how your application works.

Twitter_NewApp

Click on the “Create New App” button to start the process of creating a new app and registering it with Twitter.

Screen Shot 2015-03-08 at 9.36.35 PM

 

For each required field, “Name”, “Description” and “Website”, make sure you fill out the information.

Note, too, that the “Name” will be how this application is known to other services. While you can using something simple like “TestingApp” for this example, it might be worthwhile to find a name you like and is not already in use for more advanced projects.

Be sure to fill in the Callback URL as “https://scripts.google.com”. Google Scripts will be making these requests for us and we need to make sure Twitter knows that.

Twitter_Agree

 

Before you can finalize creating a Twitter application, you must agree to the Developer Agreement.

Take the time right now to read through it and become aware of how Twitter expects an application to act and what rights you have as a developer through this agreement.

Once done, click on “Create your Twitter application”.

Twitter_AppScreen

 

Click on the “Keys and Access Tokens” tab.

Getting your Consumer Key and Secret

The “Keys and Access Tokens” tab contains your Consumer Key, Consumer Secret, and other private information. As noted in its description, none of those details should ever be public.

Twitter_CustomerScret

For this project, you will only need your Consumer Key and Secret. (By default, Twitter uses a “Read-only” configuration, meaning you can only read tweets and not write them. However, should you want to change this in the future, you can do so from the “Permissions” tab.)

Configuring a Google Spreadsheet

Once logged in to your Google account, access Google Drive.

Screen Shot 2015-03-08 at 8.11.15 PM

From the “New” menu, select “Google Sheets”.

Screen Shot 2015-03-08 at 8.11.48 PM

Click on the Untitled Spreadsheet at the top left-hand corner. Name this file. (For this example, I’ve named it “TwitterApp.”)

Screen Shot 2015-03-08 at 8.11.58 PM

Once saved, access “Script editor…” from the Tools menu. This will open a new tab.

Screen Shot 2015-03-08 at 8.13.51 PM

From the options presented, choose “Blank Project”.

Screen Shot 2015-03-08 at 8.14.39 PM

 

From the File menu, choose “Save”.

Screen Shot 2015-03-08 at 8.14.56 PM

 

Name this project. (For this example, I’ve named it “TwitterAppScript.”)

Writing code in Google Scripts

Screen Shot 2015-03-08 at 8.41.33 PM

When you start a Blank Project in Google Scripts, it will create a single function for you called myFunction. However, we won’t be needing that function for this project, so delete it for the moment.

In that empty space, copy the following code:

[gist https://gist.github.com/videlais/2daf3e3940a632e14c76]

Examining the Code

The onOpen function

[gist https://gist.github.com/videlais/fea884a8393fc8f8df86]

Built into Google Scripts in an understanding of certain named functions. Among those is the one above, onOpen. It runs every time the document or spreadsheet it is attached to is opened.

For this example, we are adding an extra menu (TwitterApp Menu) along with a single option (“Get tweets”) attached to a function.

The readTweets function

[gist https://gist.github.com/videlais/202c9cfb6ffbedbca29b]

While Google Scripts does come with the functionality to call external APIs and fetch content from web services, we have to give it explicit instructions for how to do that.

Because we also want to have control over both what it looks for in terms of hashtags (or other search terms) and how many tweets are received, we also need to enter those configuration options.

In order to use this code, you WILL NEED to enter your Consumer Key and Secret you got from creating a Twitter App earlier in this post.

The saveTweets function

[gist https://gist.github.com/videlais/98b2e40785d8c44455ec]

The last function we have receives the tweets retrieved from the readTweets function and then parses them. Because tweets are encoded as JSON, both tweets and users are two different objects: a result from Twitter can have statuses and each of those statuses, in turn, have their own user objects. (Hence why we can configure to look for different things with each of them.)

Testing the Configuration

 

Screen Shot 2015-03-08 at 9.14.40 PM

 

Now, we will run the script. Click on the “Run” button. (Alternatively, you can run a function directly from the Run -> {Function Name} menu.)

Screen Shot 2015-03-08 at 9.16.18 PM

The first time you run the script, it will require you to agree to give it permission to call an external service. Click “Continue” to agree.

Screen Shot 2015-03-08 at 9.17.25 PM

The window will list what you are about to agree the Google Script to do (manage spreadsheets and connect to an external service). Click “Accept” to agree.

Screen Shot 2015-03-08 at 9.35.27 PM

Because we set a Callback URL in our Setting for creating the Twitter App, Google Scripts will let us know that a redirect was in progress. Click on the link to Twitter.

Screen Shot 2015-03-08 at 9.35.50 PM

As the final step, we need to Authorize the app we created to act through Google Scripts on behalf of us on Twitter.

Seeing the Results

Screen Shot 2015-03-08 at 9.48.55 PM

Once you have authorized your Twitter application and agreed to let Google Scripts act on your behalf, you should see the results in the spreadsheet itself. Starting from the top cell (a1) and running from the set count or as many as found, the results will be in the first three columns.

In the above image, you might have noticed that have I have blurred the results I found from my example. The reasons for this has to do with the responsibility of having access to this data. Just because the results were from public accounts does not mean they are Public and you are free to do whatever you want with the data. Most users have some expectation of privacy when using a social networking platform like Twitter, even with public accounts. Don’t abuse other users’ trust and unnecessarily expose their data.

Using the Menu

Screen Shot 2015-03-08 at 10.07.05 PM

Since the code written to create a new menu was added after the file was opened the first time, you will have to close it and then re-open it to access it.

Do that now.

Now, you should see the “TwitterApp Menu” menu and, after clicking on it, the “Get tweets” option. Clicking on this will run the readTweets function and collect tweets using the configuration rules within that function.