PowerTrack Video Walkthrough
posted on 16 April 2014 by Leah Barren
If you are getting ready to use PowerTrack for the first time, the following video provides an overview of what you need to know, and how to get connected quickly.
This document provides a step-by-step introduction to realtime PowerTrack streams from Gnip, and offers simple examples of how to get started, including:
- Step 1 - Add Rules to your Stream
- Step 2 - Connect to the Data Stream
For the purposes of this walkthrough, we will be using a Twitter PowerTrack stream. Where there are differences in functionality with other streams, they will be noted.
When your Gnip premium account is activated, you will receive an account activation email to create your password and log in. Once this is complete, you will arrive on the main console dashboard. Once you are logged in, you will first want to get connected to the data stream and watch some data flow in.
To connect to your data stream, you must first add at least one rule to define which Tweets will be sent through your connection.
There are two ways to add rules - via the User Interface, and via the API. The User Interface offers limited support and is intended as an introductory tool. Production-level integrations should use the API for rule management.
In PowerTrack streams, the rules you use should conform to the syntax described here.
Adding Rules via the user interface
On the main dashboard of your console, find the stream you would like to add rules to and click “Rules” from this page, or click into the stream.
Navigate to the “Rules” page for your stream and begin adding rules via the user interface. Here, you can simply type rules into the blank text box, one rule per line. To begin, you may want to try a few simple keywords. These will match results containing the specified keywords in a case-insensitive manner. For full details on rule matching functionality, see the PowerTrack documentation.
After adding your test rules, click “Update” at the bottom of the screen.
Adding Rules via the API
On your dashboard, navigate to the API Help page for your PowerTrack stream and scroll down to the bottom of the page.
There, you’ll see example curl commands for adding and deleting a test rule programmatically, and retrieving the current rule set. The URL contained within these curl commands is the specific Rules API URL you will use for this stream. Note that each stream has a different Rules API endpoint URL.
Copy the example curl command provided for “Adding Rules,” paste it into a command prompt, and execute it, entering your password when prompted. This uses the HTTP POST method.
See the full PowerTrack documentation for details on using the RulesAPI.
Navigate back to the stream’s Overview page, this will display a window containing the data stream's URL endpoint, as well as a sample curl command to use to test the stream connection.
To test the connection, simply copy the curl command shown, paste it into a command line terminal, and hit return. You will be prompted for your account password. Enter it and hit return again. This will initiate the connection. If it returns a “200 OK” response, you were successful and Tweets will begin flowing into your console window as shown in the screenshot shown below. The tweets (the beginning of the data stream is shown at the bottom of the screenshot) will continue flowing in as long as the connection remains alive.
If you receive errors, you may need to update to the latest version of curl.
The payloads of this stream and other premium streams are provided in Gnip’s JSON Activity Streams format as described in the data formats of the respective publishers. The Activity Streams format provides normalization across publishers, as well as access to additional data enrichments Gnip provides. In some cases, the publisher’s original format may be available without modification by Gnip. To switch the format of your stream, navigate to the Edit page for your stream and choose the radio button with the format you would like to use.
When you have pulled in some data in Activity Streams format, be sure to note the “Matching Rules” portion of the payload – this indicates the rule or rules that matched this specific activity.