• Introduction
  • How it works
• User Interface
• Prepare the environment
• Access to the service
  • Access through User Interface
  • Access through API
    • Analyze the sentiment of one or more topics
    • Ignore neutral values
    • Analyze recent Tweets (last hour)
    • Combine keywords
    • Use Twitter operators

Introduction

JA-Sentiment-Analyzer (JASA), is a Just Another project which aims to provide a simple service to quickly know the sentiment of a particular topic or several topics related to each other.

How it works

JASA is a server that provides REST APIs for its integration written through the Python language. More precisely, with the help of the FastAPI framework, JASA allows queries to be made through the API provided by Twitter.

Once the Tweets related to the query made are obtained, JASA will express a sentiment value as an output of the process. The sentiment value is generated by summing the sentiment of all Tweets related to the same topic in a proportional way to the number of retweets, replies, mentions and likes. Finally, the sentiment value for each individual Tweet is assigned thanks to the cardiffnlp/tweeteval model also available through Huggingface.

User Interface

JA-Sentiment-Analyzer is present with a User Interface that allows you to easily perform queries quickly across the API layer.

Prepare the environment

First, download the repository.

git clone https://github.com/Just-Another-Organization/JA-Sentiment-Analyzer.git

Next, access the folder and create a .env file.

cd JA-Sentiment-Analyzer
touch .env

Edit the .env file by inserting the necessary environment variables. You must have Twitter access codes, to obtain these codes consult the Twitter developer documentation. An example of environment variables is as follows:

ENVIRONMENT=production # System environment stage
PORT=3000 # Port on which the service will be active
USE_USER_CONTEXT=False # Enable or disable the use of the Twitter user context
USE_APP_CONTEXT=True # Enable or disable the use of the Twitter application context
LABEL_30_DAY=YOUR_LABEL_30_DAY # The 30 Day Twitter label needed to access recent tweets
LABEL_FULL_ARCHIVE=YOUR_LABEL_FULL_ARCHIVE # The Full Archive Twitter label needed to access popular tweets
CONSUMER_KEY=YOUR_CONSUMER_KEY # Twitter Consumer Key
CONSUMER_KEY_SECRET=YOUR_CONSUMER_KEY_SECRET # Twitter Consumer Key Secret
BEARER_TOKEN=YOUR_BEARER_TOKEN # Twitter Bearer Token
ACCESS_TOKEN=YOUR_ACCESS_TOKEN # Twitter Access Token
ACCESS_TOKEN_SECRET=YOUR_ACCESS_TOKEN_SECRET # Twitter Access Token Secret
LOG_LEVEL=debug # Fastapi/starlette log level
ALLOWED_HOSTS=localhost,your.own.domain,your.other.domain # Allowed hosts, you can also set 0.0.0.0 to enable all hosts

Finally, start the whole JA-Sentiment-Analyzer system with the docker-compose utility.

docker-compose up --build -d # or "docker compose up --build -d" for newer docker version

Note that the startup process may take a few minutes depending on your connection speed

Access to the service

Access through User Interface

Once initialization is complete, you can access the User Interface at http://{{YOUR_DOMAIN}}:{{YOUR_PORT}}/engine.

Access through API

Finally, JASA provides the `/api/analyze-keywords` endpoint to allow the integration of the system with others. The call is of type `GET` and it is possible to define the behaviour of the system through parameters:

• `keywords` (Required) (String Array) - Defines an array of keywords divided by a comma;
• `ignore_neutral` (Boolean) - If set to `True` allows to force sentiment to only `POSITIVE` and `NEGATIVE` values ignoring neutral values;
• `interval` (String) - If set it will search for recent Tweets. Possible values are of the type `1m` `4h` `12d` `3w` `1M` and cannot exceed 30 days.
• `combine` (Boolean) - If set to `True` allows you to combine all `keywords` into a single query. This allows for Twitter-supported query operators, see the official Twitter documentation for more information.

Analyze the sentiment of one or more topics

curl -X GET 'YOUR_DOMAIN:YOUR_PORT/api/analyze-keywords?keywords=Bitcoin,Covid,Cryptocurrencies'

{
   "result":{
      "Bitcoin": "POSITIVE",
      "Covid": "NEGATIVE",
      "Cryptocurrencies": "NEUTRAL"
   }
}

Ignore neutral values

curl -X GET 'YOUR_DOMAIN:YOUR_PORT/api/analyze-keywords?keywords=Bitcoin,Covid,Cryptocurrencies&ignore_neutral=True'

{
   "result":{
      "Bitcoin":"POSITIVE",
      "Covid":"NEGATIVE",
      "Cryptocurrencies":"POSITIVE" # Positive due to the greater optimism compared to pessimism
   }
}

Analyze recent Tweets (last hour)

curl -X GET 'YOUR_DOMAIN:YOUR_PORT/api/analyze-keywords?keywords=Bitcoin,Covid,Cryptocurrencies&interval=1h'

{
   "result":{
      "Bitcoin": "NEGATIVE",
      "Covid": "NEGATIVE",
      "Cryptocurrencies": "NEGATIVE"
   }
}

Combine keywords

curl -X GET 'YOUR_DOMAIN:YOUR_PORT/api/analyze-keywords?keywords=Bitcoin,Cryptocurrencies&combine=True'

{
   "result":{
      "Bitcoin Cryptocurrencies": "NEUTRAL" # Analyze Tweets with both 'Bitcoin' and 'Cryptocurrencies' keywords
   }
}

Use Twitter operators

curl -X GET 'YOUR_DOMAIN:YOUR_PORT/api/analyze-keywords?keywords=Bitcoin,@elonmusk&combine=True'

{
   "result":{
      "Bitcoin @elonmusk": "NEUTRAL" # Analyze Tweets with 'Bitcoin' keyword related to '@elonmusk' user
   }
}

curl -X GET 'YOUR_DOMAIN:YOUR_PORT/api/analyze-keywords?keywords=Bitcoin,place:new%20york%20city&combine=True'

{
   "result": {
      "Bitcoin place: new york city": "POSITIVE" # Analyze Tweets with 'Bitcoin' keyword from New York City
   }
}