pytangle 0.0.2

A python wrapper for crowdtangle API endpoints

pytangle

A python wrapper for crowdtangle

In this repository

• pytangle.py: main file with examples
• pytangle/api.py: object oriented interface to the api
• pytangle/connectivity.py: uses requests to forward calls to the api endpoints. performs rate limiting and network-related error handling.
• pytangle/endpoints.py: objects detailing the crowdtangle API endpoints
• pytangle/utils.py: common utility procedures
• pytangle_config_sample.json: sample configuration file. pytangle uses this file to load your API token and to set logging preferences. Copy pytangle_config_sample.json into a file named pytangle_config.json before customizing it. You most likely want to edit at least your API token. See the later section for further customizations.

Quickstart

1. Install the package: pip3 install pytangle
2. Create a file named pytangle_config.json in the folder from where you will call pytangle, and paste:

{
  "token": "YOUR_CROWDTANGLE_TOKEN"
}

3. Check that everything works:

from pytangle.api import API
api = API() # or "api = API(token=YOUR_CROWDTANGLE_TOKEN)" 
            # if you did not create pytangle_config.json

# fetch lists in the current dashboard
for a_list in api.lists():
   print(a_list)

Installation

The quickest way to download and install is:

pip3 install pytangle

Otherwise, download the code, move into the directory, and install from the local file, e.g.:

git clone https://github.com/hide-ous/pytangle.git 
cd pytangle
pip3 install . 

To install only the dependencies, and use the library without installing, run:

pip3 install -r requirements.txt

Python 3.5 and up. Tested on 3.7.

Examples

It is easy to use the API. Just create an API instance, and start querying way. If you have customized pytangle_config.json the API instance will automatically load your API token, otherwise you can assign explicitly via code. Rate limiting and pagination are handled for you.

from pytangle.api import API
api = API()
# use the following line instead if you do not want to set up a configuration file
# api = API(token="YOUR_TOKEN") 

All query methods return an iterator, one result object (i.e. one post, account, ...) at a time. For example, to fetch the lists linked to the current dashboard:

from pytangle.api import API
api = API()
# fetch all lists linked to the current dashboard
for a_list in api.lists():
    print(a_list)

The same applies to other types of objects, like posts:

from pytangle.api import API
api = API()

# get the 5 top overperforming posts
for a_post in api.posts(count=5):
    print(a_post)

If you want information about a specific post, you can query it via either its facebook id or its crowdtangle id, by specifying the endpoint (platform or ct respectively). For differences see the official wiki.

from pytangle.api import API
api = API()

# get information about a specific post
post_id = "1515871602074952_5362226790772728"
for a_post in api.post(id=post_id, endpoint='platform'):
    print(a_post)

Get the leaderboard for the current dashboard:

from pytangle.api import API
api = API()

# get the first 5 entries in the leaderboard for the current dashboard
for a_leaderboard in api.leaderboard(count=5):
    print(a_leaderboard)

Get the top 5 posts sharing a link (like in the crowdtangle chrome extension):

from pytangle.api import API
api = API()

# get the top 5 sharers of a link
an_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
for a_post in api.links(count=5, link=an_url):
    print(a_post)

Get details about a specific account in a list:

from pytangle.api import API
api = API()

# get information on an account
list_id = 12345 # the id of one of your lists
for an_account in api.accounts_in_list(count=5, listId=list_id):
    print(an_account)

Get all posts from a list in a specific date range (you can find which lists are in your dashboard via api.lists():

from pytangle.api import API
api = API()

# get all posts from a list from Jan until June 2020
list_ids = [12345, ] # ids of the lists of interest
for n, a_post in enumerate(api.posts(listIds=list_ids,
                                     count=-1,
                                     batchSize=100,
                                     sortBy='date',
                                     startDate='2020-01-01',
                                     endDate='2020-06-30',
                                     timeframe=None,
                                     )):
    # do something with the post
    if not n % 1000:
        print(n)

Configuring pytangle

The configuration file pytangle_config.json is a simple json file, containing two main sections:

• token: is the API token associated with a dashboard within crowdtangle. If you have access to the API, you can locate your API token via your dashboard under Settings > API Access.
• logging: is a dictionary of items determining how pytangle should log. It follows the conventions in logging.dictConfig: for explanations on the various options see the official reference.

The default locations for pytangle_config.json are:

• at the root of the presently used module, or
• in the user's home.

An API instance will attempt to load the token from the configuration file, if a token is not explicitly passed. pytangle.py shows an example of how to initialize loggers using the configuration in pytangle_config.json. However, the API will not load the logging configuration by default.

pytangle_config_sample.json provides a reasonable starting point to customize pytangle: just copy the file in one of the default locations under the name pytangle_config.json, and edit (at least) your token.

Changelog

• 0.0.2
  • bugfix: pass token via code instead of configuration file
• 0.0.1 initial release