Interface to Twitter's Engagement API
Switch branches/tags
Nothing to show
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
example Add simplified grouping config Jul 24, 2017
gnip_insights_interface remove Audience API interface Jul 6, 2017
.gitignore Initial commit Sep 6, 2016 Update README Jul 24, 2017
license Create license Sep 19, 2016 pipy 0.2 Jul 24, 2017 remove Audience API interface Jul 6, 2017


This repository contains a Python package that provides an interface to Twitter's Engagement API.
In addition to providing a straightforward interface to the API, this package implements extra aggregation features. An interface to the Audience API can be found on the audience_api branch.


You can pip-install the package:

$ pip install gnip_insights_interface

You can also install a local version from the cloned repository location.

[REPOSITORY] $ pip install -e . -U


This package expects to find a YAML credentials file called .twitter_api_creds in your home directory. This files must contain your Twitter Oauth credentials in the following format:

username: YOUR_USER_NAME
    consumer_key: --
    consumer_secret: --
    token: --
    token_secret: --

Engagement API Interface

We provide an interface for passing a set of Tweet IDs to the Twitter Engagement API, which provides engagement data such as impressions, favorites, and replies. A full list of the available engagement types, their names, and the ways that they can be grouped is available in the API documentation.

We construct the API interface in a python module called engagement_api, which is part of the gnip_insights_interface package. We provide a script for command-line interface called The script provides direct access the the three endpoint of the API: total counts (-T), 28 hour summary (-D, for "day"), as well as an aggregating function (-H) which combines the data from results over an arbitrary time range. See the help option.

Custom groupings and engagements types are set with a YAML configuration file specified with the -c option. See example config in the example directory in the repository.