Botometer Pro

FREEMIUM
Por Observatory on Social Media | Atualizado 9 дней назад | Social
Popularidade

9.7 / 10

Latência

828ms

Nível de serviço

100%

Health Check

N/A

LEIA-ME

Announcement

We have added a new Botometer X endpoint to the API.
Please see the introduction below to learn more about it.

We are keeping the legacy endpoints (V4 and Lite).
Users with historical data can still use them.

API endpoints

Botometer X

Overview

Endpoint: Botometer X (/botometer-x/get_botscores_in_batch)

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

Unlike the legacy endpoints (V4 and Lite, see below) that fetched data from Twitter and calculated bot scores on the fly, Botometer X is in archival mode and relies on pre-calculated scores using BotometerLite model based on historical data collected before June 2023. This characteristic of Botometer X has some implications:

  1. No Twitter/X data is required: Botometer X endpoint does not require the API users to provide Twitter/X data. Only user ids and/or usernames are needed.
  2. Incomplete data: The historical data has a cutoff date of May 31, 2023 (when Twitter ended its free API). For accounts created after that date, Botometer X does not have any records; for accounts created before that date, Botometer X may or may not have records.
  3. Outdated results: Since Botometer X relies on historical data, the scores of some accounts are based on their characteristics from a long time ago and may not reflect their recent activities. For each score returned by Botometer X, there is a corresponding timestamp to provide users with context about when the score was calculated.
  4. Unknown bias: The sample of accounts in the data collection are not representative of all Twitter accounts and may have unknown biases. For example, active accounts may be more likely to be included. Researchers should use the results of Botometer X at their own discretion.

Request Object

To analyze an account, POST the required data as JSON the /botometer-x/get_botscores_in_batch endpoint.
Your request must supply the x-rapidapi-key header as well.

The request object should follow the following format:

{
	"user_ids": [9454392, 1336272389080957000],
	"usernames": ["@nimal0012", "hello0000777"]
}

You can provide just user_ids or usernames, or both.
For key user_ids, make sure the value is a list of user ids.
For key usernames, make sure the value is a list of usernames.
@ in usernames is optional.

Response Object

[
    {
        "bot_score": 0.41,
        "timestamp": "Tue, 01 Nov 2022 13:20:27 GMT",
        "user_id": "1567526735197143041",
        "username": "hello0000777"
    },
    {
        "bot_score": 0.81,
        "timestamp": "Wed, 12 Dec 2018 05:39:46 GMT",
        "user_id": "1047337718160744449",
        "username": "nimal0012"
    },
    {
        "bot_score": 0.62,
        "timestamp": "Sun, 11 Dec 2022 00:45:41 GMT",
        "user_id": "9454392",
        "username": "pasan"
    }
]

The response will be a list of JSON objects.
Meanings of the elements in the object:

  • bot_score: The bot score, a float number between 0 and 1 (note that we rescale the score to 1 to 5 on the Botometer X website)
  • timestamp: The time when the bot score was calculated
  • user_id: ID of the account
  • username: Username of the account

Rate limit

Each request allows checking up to 100 accounts.
If both user_ids and usernames are provided, the endpoint will prioritize user_ids.

Since Botometer X is in archival mode and the database in incomplete, the response might return fewer scores than requested (see above).

When querying usernames, the response might contain more scores than requested if there are multiple accounts that used the same username.
Users can use the user id and timestamp to distinguish these accounts.

If the request contains the id and username of the same account, the response will contain duplicate results.
It’s the responsibility of the user to deduplicate them.

The Botometer X endpoint is available in all plans.
Users can test the endpoint in the free plan with a 50 requests (50*100=5,000 accounts) per month limit.
Those wishing for higher rate limits can use the PRO or ULTRA plans.

The PRO plan allows the users to send 50 requests per day for free and exceed the quota for $1/100 requests.
Note that the PRO plan requires a valid credit card, which will help us reduce abusive behavior.

The ULTRA plan costs $50 per month, which allows users to send 250 queries per day. The overage is charged at $1/100 requests.

Using botometer-python

You can simplify the usage of Botometer X endpoint by using our botometer-python library.
For details, see https://github.com/osome-iu/botometer-python.

Botometer-V4 (legacy)

Overview

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:

  1. You use the Twitter REST & Search APIs to obtain user info and tweets from the account you want to analyze.
  2. You POST the Twitter data to this endpoint in JSON format.
  3. The API analyzes the data, scores it, and returns the results in JSON format.

Request Object

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:

  • User is derived from Twitter’s GET users/show REST endpoint using the target account’s screen name or ID. Only the 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.
  • Timeline is the array of Tweet objects obtained from Twitter’s GET statuses/user_timeline endpoint using the target account’s screen name or ID. Make sure to include the 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.
  • Mentions comes from Twitter’s Search API, specifically searching for the target account’s screen name and obtaining the 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.

Response Object

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:

  • user: Twitter user object (from the request) plus the language inferred from the majority of tweets
  • raw scores: bot scores in the [0,1] range, both English (using all features) and Universal (using only language-independent features); in each case we have the overall score and the sub-scores for each bot class (see below for subclass names and definitions)
  • display scores: same as raw scores, but in the [0,5] range
  • cap: Complete Automation Probability (CAP) is the conditional probability that accounts with a score equal to or greater than this are automated; based on inferred language

Bot types:

  • fake_follower: bots purchased to increase follower counts
  • self_declared: bots from botwiki.org
  • astroturf: manually labeled political bots and accounts involved in follow trains that systematically delete content
  • spammer: accounts labeled as spambots from several datasets
  • financial: bots that post using cashtags
  • other: miscellaneous other bots obtained from manual annotation, user feedback, etc.

Rate limit

The Botometer-V4 endpoint is available in all plans.

  • Our BASIC rate limit is set at 500 requests per day, per user. This plan is mainly for testing. If you desire a higher daily rate limit, faster response times, and/or the ability to exceed the daily rate limit, please subscribe to the PRO or ULTRA plans.
  • The PRO has no subscription fee. You will, however, need to enter a valid credit card. It provides a rate limit of 2,000 requests per day, and you go beyond the rate limit for $1/1k requests.
  • The ULTRA plan imposes a subscription fee of $50 per month. In return, it provides a rate limit of 17,280 requests per day, which reflects the Twitter Search API’s user-authenticated rate limit. The plan also enables users to exceed their daily quota for $1/1k requests. (Note that Twitter’s app-only authentication allows for a higher rate limit.)

Users are free to switch between the plans at will without having to change the endpoint in their code.

BotometerLite (legacy)

Overview

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:

  1. You use the Twitter Streaming, Search, or User lookup endpoints to obtain the tweets or user profiles from a set of accounts you want to analyze.
  2. You POST the data to this endpoint in JSON format.
  3. The API analyzes the accounts, scores them, and returns our results in JSON format.

Request Object

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:

  • The created_at field is required and should be the time stamp of when the user object was collected.
  • The user object is required and should be the profile of a target account.
  • The list should contain no more than 100 elements.

Response Object

[
    {"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.

Rate limit

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.

Seguidores: 241
Recursos:
Site do produto Termos de uso
API Creator:
Rapid account: Observatory On Social Media
Observatory on Social Media
OSoMe
Efetuar login para classificar API
Avaliação: 4.2 - Votos: 9