Botometer Python API

A Python API for Botometer by OSoMe. Previously known as botornot-python.

Behind the scenes, this uses the Botometer's HTTP endpoint, available via RapidAPI.

RapidAPI usage/account related questions should be posted on RapidAPI discussion.

[Change Note]

May, 2020

We have made some changes to our API, please read the annoucnment for details. Due to the API change, the old botometer-python package might stop to work and produce 404 errors. Please upgrade it in your local environment to the least version.

Sep, 2019

Mashape has renamed itself to RapidAPI. The old mashape.com based URL and HTTP headers were deprecated in Sep 1st, 2019. So please upgrade botometer-python package in your local environment to the least version for the change.

Help

You probably want to have a look at Troubleshooting & FAQ in the wiki. Please feel free to suggest and/or contribute improvements to that page.

Quickstart

From your command shell, run

pip install botometer

then in a Python shell or script, enter something like this:

import botometer

rapidapi_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # now it's called rapidapi key
twitter_app_auth = {
    'consumer_key': 'xxxxxxxx',
    'consumer_secret': 'xxxxxxxxxx',
    'access_token': 'xxxxxxxxx',
    'access_token_secret': 'xxxxxxxxxxx',
  }
bom = botometer.Botometer(wait_on_ratelimit=True,
                          rapidapi_key=rapidapi_key,
                          **twitter_app_auth)

# Check a single account by screen name
result = bom.check_account('@clayadavis')

# Check a single account by id
result = bom.check_account(1548959833)

# Check a sequence of accounts
accounts = ['@clayadavis', '@onurvarol', '@jabawack']
for screen_name, result in bom.check_accounts_in(accounts):
    # Do stuff with `screen_name` and `result`

Result:

{
  "cap": {
    "english": 0.0011785984309163565,
    "universal": 0.0016912294273666159
  },
  "categories": {
    "content": 0.058082395351262375,
    "friend": 0.044435259626385865,
    "network": 0.07064549990637549,
    "sentiment": 0.07214003430676995,
    "temporal": 0.07924665710801207,
    "user": 0.027817972609638725
  },
  "display_scores": {
    "content": 0.3,
    "english": 0.1,
    "friend": 0.2,
    "network": 0.4,
    "sentiment": 0.4,
    "temporal": 0.4,
    "universal": 0.1,
    "user": 0.1
  },
  "scores": {
    "english": 0.0215615093045025,
    "universal": 0.0254864249403189
  },
  "user": {
    "id_str": "1548959833",
    "screen_name": "clayadavis",
    "...": "..."
  }
}

For more information on this response object, consult the API Overview on RapidAPI.

Install instructions

This package is on PyPI so you can install it with pip:

$ pip install botometer

Dependencies

Python dependencies

Both of these dependencies are available via pip, so you can install both at once with

pip install requests tweepy

RapidAPI key

Our API is served via RapidAPI. You must sign up for a free account in order to obtain a RapidAPI secret key. The easiest way to get your secret key is to visit our API endpoint page and look in the endpoint's header parametsrs for the "X-RapidAPI-Key" as shown below:

Twitter app

In order to access Twitter's API, one needs to have/create a Twitter app. Once you've created an app, the authentication info can be found in the "Keys and Access Tokens" tab of the app's properties:

Authentication

By default, Botometer uses user authentication when interacting with Twitter's API as it is the least restrictive and the ratelimit matches with Botometer's Pro plan: 180 requests per 15-minute window. One can instead use Twitter's application authentication in order to take advantage of the higher ratelimit that matches our Ultra plan: 450 requests per 15-minute window. Do note the differences between user and app-only authentication found under the header "Twitter API Authentication Model" in Twitter's docs on authentication.

To use app-only auth, just omit the access_token and access_token_secret in the Botometer constructor.

import botometer

rapidapi_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # now it's called rapidapi key
twitter_app_auth = {
    'consumer_key': 'xxxxxxxx',
    'consumer_secret': 'xxxxxxxxxx'
  }
bom = botometer.Botometer(wait_on_ratelimit=True,
                          rapidapi_key=rapidapi_key,
                          **twitter_app_auth)

References

Yang, Kai‐Cheng, Onur Varol, Clayton A. Davis, Emilio Ferrara, Alessandro Flammini, and Filippo Menczer. "Arming the public with artificial intelligence to counter social bots." Human Behavior and Emerging Technologies 1, no. 1 (2019): 48-61. DOI, ArXiv
Varol, Onur, Emilio Ferrara, Clayton A. Davis, Filippo Menczer, and Alessandro Flammini. "Online Human-Bot Interactions: Detection, Estimation, and Characterization." ICWSM (2017). AAAI, ArXiv
Davis, C. A., Varol, O., Ferrara, E., Flammini, A., & Menczer, F. (2016, April). "BotOrNot: A system to evaluate social bots". In Proceedings of the 25th International Conference Companion on World Wide Web (pp. 273-274). International World Wide Web Conferences Steering Committee. ArXiv, ACM Library
Varol O., Davis C., Menczer, F., Flammini, A. "Feature Engineering for Social Bot Detection", Feature Engineering for Machine Learning and Data Analytics Google Books
Ferrara, Emilio, Onur Varol, Clayton Davis, Filippo Menczer, and Alessandro Flammini. "The rise of social bots." Communications of the ACM 59, no. 7 (2016): 96-104. ArXiv, ACM Library

binghe2727 / botometer-python