Botometer® checks the activity of a Twitter account and gives it a score based on to extent to which it matches accounts that use automation. Higher scores indicate activities that are more bot-like.
Endpoint: Check account
(/4/check_account
).
Reference: Mohsen Sayyadiharikandeh, Onur Varol, Kai-Cheng Yang, Alessandro Flammini, Filippo Menczer. “Detection of Novel Social Bots by Ensembles of Specialized Classifiers.” Proc. CIKM 2020. Preprint: Arxiv
This endpoint offers the V4 of Botometer, the same as botometer.org. The endpoint flow works generally like this:
To analyze an account, POST the required Twitter data as JSON to the /4/check_account
endpont. Your request must supply the x-rapidapi-key
header as demonstrated below.
The request object looks roughly like this (note the ellipses):
{
"user": {
"id": "1234567890",
"screen_name": "IUNetSci"
},
"timeline": [
{
"id": 1234567890,
"text": "@Botometer is so cool!",
"...": "..."
},
"..."
],
"mentions": [
{
"id": 9876543210,
"text": "@OSoME_IU is also cool!",
"...": "..."
},
"..."
]
}
This object has three main parts:
id
(or id_str
) and screen_name
properties are required, but you may submit the whole user object if you would like it returned to you in the response.count=200
and include_rts=true
parameters in your Twitter API request! Submit the most recent 200 statuses from the timeline, or the entire timeline if it contains fewer than 200 tweets.statuses
property of the Search API response. This is an array of Tweet objects. Note that your Twitter API search parameters should contain q=@...
in order to search for retweets and mentions of the target account, and also count=100
to get the max number of tweets we can in one call. Submit 100 tweets from the search, or all of the tweets if it contains less than 100 tweets.For testing purposes, you can download a full example payload as a gzipped JSON file.
A successful classification result looks like this:
{
"cap": {
"english": 0.8018818614025648,
"universal": 0.5557322218336633
},
"display_scores": {
"english": {
"astroturf": 0.0,
"fake_follower": 4.1,
"financial": 1.5,
"other": 4.7,
"overall": 4.7,
"self_declared": 3.2,
"spammer": 2.8
},
"universal": {
"astroturf": 0.3,
"fake_follower": 3.2,
"financial": 1.6,
"other": 3.8,
"overall": 3.8,
"self_declared": 3.7,
"spammer": 2.3
}
},
"raw_scores": {
"english": {
"astroturf": 0.0,
"fake_follower": 0.81,
"financial": 0.3,
"other": 0.94,
"overall": 0.94,
"self_declared": 0.63,
"spammer": 0.57
},
"universal": {
"astroturf": 0.06,
"fake_follower": 0.64,
"financial": 0.3133333333333333,
"other": 0.76,
"overall": 0.76,
"self_declared": 0.74,
"spammer": 0.47
}
},
"user": {
"majority_lang": "en",
"user_data": {
"id_str": "11330",
"screen_name": "test_screen_name"
}
}
}
Meanings of the elements in the response:
Bot types:
fake_follower
: bots purchased to increase follower countsself_declared
: bots from botwiki.orgastroturf
: manually labeled political bots and accounts involved in follow trains that systematically delete contentspammer
: accounts labeled as spambots from several datasetsfinancial
: bots that post using cashtagsother
: miscellaneous other bots obtained from manual annotation, user feedback, etc.Endpoint: Check accounts in bulk
(/litev1/check_accounts_in_bulk
).
Reference: Yang, Kai-Cheng, Onur Varol, Pik-Mai Hui, and Filippo Menczer. “Scalable and generalizable social bot detection through data selection.” In Proceedings of the AAAI Conference on Artificial Intelligence, vol. 34, no. 01, pp. 1096-1103, 2020. DOI:10.1609/aaai.v34i01.5460
This endpoint offers the BotometerLite model. The endpoint flow works generally like this:
To analyze the accounts, POST the required data as JSON to the /litev1/check_accounts_in_bulk
endpont. Your request must supply the x-rapidapi-key
header as demonstrated below.
If you have a collection of tweets from Twitter, the request object looks roughly like this:
[tweet1, tweet2, ...]
where tweet1, tweet2, … are the tweet objects you collected from Twitter without modification.
The list should contain no more than 100 tweets.
If you only have a collection of user objects (i.e. you collected them using the Twitter user lookup endpoint), the request object should look like this:
[
{
"created_at": "Wed Jun 05 21:42:20 +0000 2019",
"user": {
"id": 1234,
"screen_name": "test_user_1",
"....": "...."
}
},
{
"created_at": "Wed Aug 04 21:42:20 +0000 2020",
"user": {
"id": 12345,
"screen_name": "test_user_2",
"....": "...."
}
},
....
]
Notes:
created_at
field is required and should be the time stamp of when the user object was collected.user
object is required and should be the profile of a target account.[
{"botscore": 0.65, "tweet_id": "235135", "user_id": 1234},
{"botscore": 0.29, "tweet_id": "235134", "user_id": 12345}
]
For each tweet posted to the API, a corresponding object with the user_id, tweet_id, and bot score will be returned unless some errors occurred.
Note that if you follow the second example above where only the user objects are posted, the tweet_ids in the response will be set to null.
The Botometer-V4 endpoint is available in all plans.
Users are free to switch between the plans at will without having to change the endpoint in their code.
The BotometerLite endpoint is only available through the ULTRA plan, which provides a rate limit of 200 requests per day and allows the users to exceed the quota for $1/100 requests.
Note that each request allows checking up to 100 accounts.
For answers to questions about the Botometer service in general, please refer to our website’s FAQ.
You can simplify the usage of the Botometer Pro API with our botometer-python client library.
To check higher volumes of accounts, you may also want to use app-only authentication with the Twitter API. For complete info, see this wiki page on our GitHub repo.
When adding a paid API option, Mashape requires all users – even free users – to provide a credit card. Since we value the ability for our users to use our free service without entering their CC info, we’re forced to have two separate APIs.
You can easily use the Pro API with our botometer-python client library by specifying botometer_api_url
in the constructor:
botometer_api_url = 'https://botometer-pro.p.mashape.com'
bom = botometer.Botometer(botometer_api_url=botometer_api_url,
wait_on_ratelimit=True,
mashape_key=mashape_key,
**twitter_app_auth)
In order to make use of the higher ratelimits allowed with the paid tier of the Pro API, you probably also want to use app-only authentication for the Twitter API. For complete info, see this wiki page on our GitHub.
Endpoint: Check account
(/4/check_account
).
Reference: Mohsen Sayyadiharikandeh, Onur Varol, Kai-Cheng Yang, Alessandro Flammini, Filippo Menczer. “Detection of Novel Social Bots by Ensembles of Specialized Classifiers.” Proc. CIKM 2020. Preprint: Arxiv
This endpoint offers the V4 of Botometer, the same as botometer.org. The endpoint flow works generally like this:
To analyze an account, POST the required Twitter data as JSON to the /4/check_account
endpont. Your request must supply the x-rapidapi-key
header as demonstrated below.
The request object looks roughly like this (note the ellipses):
{
"user": {
"id": "1234567890",
"screen_name": "IUNetSci"
},
"timeline": [
{
"id": 1234567890,
"text": "@Botometer is so cool!",
"...": "..."
},
"..."
],
"mentions": [
{
"id": 9876543210,
"text": "@OSoME_IU is also cool!",
"...": "..."
},
"..."
]
}
This object has three main parts:
id
(or id_str
) and screen_name
properties are required, but you may submit the whole user object if you would like it returned to you in the response.count=200
and include_rts=true
parameters in your Twitter API request! Submit the most recent 200 statuses from the timeline, or the entire timeline if it contains fewer than 200 tweets.statuses
property of the Search API response. This is an array of Tweet objects. Note that your Twitter API search parameters should contain q=@...
in order to search for retweets and mentions of the target account, and also count=100
to get the max number of tweets we can in one call. Submit 100 tweets from the search, or all of the tweets if it contains less than 100 tweets.A successful classification result looks like this:
{
"cap": {
"english": 0.8018818614025648,
"universal": 0.5557322218336633
},
"display_scores": {
"english": {
"astroturf": 0.0,
"fake_follower": 4.1,
"financial": 1.5,
"other": 4.7,
"overall": 4.7,
"self_declared": 3.2,
"spammer": 2.8
},
"universal": {
"astroturf": 0.3,
"fake_follower": 3.2,
"financial": 1.6,
"other": 3.8,
"overall": 3.8,
"self_declared": 3.7,
"spammer": 2.3
}
},
"raw_scores": {
"english": {
"astroturf": 0.0,
"fake_follower": 0.81,
"financial": 0.3,
"other": 0.94,
"overall": 0.94,
"self_declared": 0.63,
"spammer": 0.57
},
"universal": {
"astroturf": 0.06,
"fake_follower": 0.64,
"financial": 0.3133333333333333,
"other": 0.76,
"overall": 0.76,
"self_declared": 0.74,
"spammer": 0.47
}
},
"user": {
"majority_lang": "en",
"user_data": {
"id_str": "11330",
"screen_name": "test_screen_name"
}
}
}
Meanings of the elements in the response:
Bot types:
fake_follower
: bots purchased to increase follower countsself_declared
: bots from botwiki.orgastroturf
: manually labeled political bots and accounts involved in follow trains that systematically delete contentspammer
: accounts labeled as spambots from several datasetsfinancial
: bots that post using cashtagsother
: miscellaneous other bots obtained from manual annotation, user feedback, etc.Endpoint: Check accounts in bulk
(/litev1/check_accounts_in_bulk
).
Reference: Yang, Kai-Cheng, Onur Varol, Pik-Mai Hui, and Filippo Menczer. “Scalable and generalizable social bot detection through data selection.” In Proceedings of the AAAI Conference on Artificial Intelligence, vol. 34, no. 01, pp. 1096-1103, 2020. DOI:10.1609/aaai.v34i01.5460
This endpoint offers the BotometerLite model. The endpoint flow works generally like this:
To analyze the accounts, POST the required data as JSON to the /litev1/check_accounts_in_bulk
endpont. Your request must supply the x-rapidapi-key
header as demonstrated below.
If you have a collection of tweets from Twitter, the request object looks roughly like this:
[tweet1, tweet2, ...]
where tweet1, tweet2, … are the tweet objects you collected from Twitter without modification.
The list should contain no more than 100 tweets.
If you only have a collection of user objects (i.e. you collected them using the Twitter user lookup endpoint), the request object should look like this:
[
{
"created_at": "Wed Jun 05 21:42:20 +0000 2019",
"user": {
"id": 1234,
"screen_name": "test_user_1",
"....": "...."
}
},
{
"created_at": "Wed Aug 04 21:42:20 +0000 2020",
"user": {
"id": 12345,
"screen_name": "test_user_2",
"....": "...."
}
},
....
]
Notes:
created_at
field is required and should be the time stamp of when the user object was collected.user
object is required and should be the profile of a target account.[
{"botscore": 0.65, "tweet_id": "235135", "user_id": 1234},
{"botscore": 0.29, "tweet_id": "235134", "user_id": 12345}
]
For each tweet posted to the API, a corresponding object with the user_id, tweet_id, and bot score will be returned unless some errors occurred.
Note that if you follow the second example above where only the user objects are posted, the tweet_ids in the response will be set to null.
The Botometer-V4 endpoint is available in all plans.
Users are free to switch between the plans at will without having to change the endpoint in their code.
The BotometerLite endpoint is only available through the ULTRA plan, which provides a rate limit of 200 requests per day and allows the users to exceed the quota for $1/100 requests.
Note that each request allows checking up to 100 accounts.
For answers to questions about the Botometer service in general, please refer to our website’s FAQ.
You can simplify the usage of the Botometer Pro API with our botometer-python client library.
To check higher volumes of accounts, you may also want to use app-only authentication with the Twitter API. For complete info, see this wiki page on our GitHub repo.
You can easily use the Pro API with our botometer-python client library by specifying botometer_api_url
in the constructor:
botometer_api_url = 'https://botometer-pro.p.mashape.com'
bom = botometer.Botometer(botometer_api_url=botometer_api_url,
wait_on_ratelimit=True,
mashape_key=mashape_key,
**twitter_app_auth)
In order to make use of the higher ratelimits allowed with the paid tier of the Pro API, you probably also want to use app-only authentication for the Twitter API. For complete info, see this wiki page on our GitHub.