A Python API for Botometer by OSoMe
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


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 Mashape Market.


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.


From your command shell, run

pip install botometer

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

import botometer

mashape_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
twitter_app_auth = {
    'consumer_key': 'xxxxxxxx',
    'consumer_secret': 'xxxxxxxxxx',
    'access_token': 'xxxxxxxxx',
    'access_token_secret': 'xxxxxxxxxxx',
bom = botometer.Botometer(wait_on_ratelimit=True,

# 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`


  "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, consule the API Overview on Mashape.

Install instructions

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

$ pip install botometer


Python dependencies

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

pip install requests tweepy

Mashape Market API key

Our API is served via Mashape Market. You must sign up for a free account in order to obtain a Mashape secret key. The easiest way to get your secret key is to visit our API endpoint page and look in the "Request Example" as shown below: Screenshot of Mashape "Request example"

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: Screenshot of app "Keys and Access Tokens"


  • 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