Interface to Twitter's Engagement API
Switch branches/tags
Nothing to show
Clone or download
Permalink
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
README.md Update README Jul 24, 2017
license Create license Sep 19, 2016
setup.py pipy 0.2 Jul 24, 2017
tweet_engagements.py remove Audience API interface Jul 6, 2017

README.md

Overview

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.

Installation

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

Credentials

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
engagement:
    consumer_key: --
    consumer_secret: --
    token: --
    token_secret: --
    url: https://data-api.twitter.com/insights/engagement

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 tweet_engagements.py. 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.