service-analysis/README.md

   1 # Sentiment Service
   2
   3 ## API
   4 Provides a REST-API to get the average sentiment of a given list of texts.
   5 The service uses the sentiment analysis service indico.
   6
   7 `GET`: `/` Displays the expected input for a POST
   8
   9 `GET`: `/health` Returns HTTP Status 200 if service is running
  10
  11 `POST`: `/` Calculates the average sentiment for a given list of texts using the online sentiment analysis tool indico (https://www.indico.io).
  12 - param: Term[ ] as Content-Tye: `application/json`
  13 example body of request:
  14 ```json
  15 [
  16         {
  17                 'text': 'sample text 1',
  18         },
  19         {
  20                 'text': 'sample text 2',
  21         },
  22         {
  23                 'text': 'sample text 3',
  24         }
  25 ]
  26 ```
  27 `POST`: `/offline_analysis` Calculates the average sentiment for a given list of texts using TextBlob (https://textblob.readthedocs.io)
  28 - param:  Term[ ] as Content-Tye: `application/json`
  29 example body of request:
  30 ```json
  31 [
  32         {
  33                 'text': 'sample text 1',
  34         },
  35         {
  36                 'text': 'sample text 2',
  37         },
  38         {
  39                 'text': 'sample text 3',
  40         }
  41 ]
  42 ```
  43 JSON string may contain more value-key pairs than 'text', but 'text' is needed for the sentiment analysis. Everything else will be ignored.
  44 For more examples see curl commands in local -> commands.
  45
  46 ## API errors
  47 - `409`: input string does not meet specifications
  48 - `503`: indico sentiment analysis not available
  49
  50 ## external services
  51 This sentiment analysis service uses the online sentiment analysis indico (https://www.indico.io).
  52 The indico api key can be set in the file `analysis.env`. The current key does work, however excessive use of this service will require you to provide your own key, since the amount of requests for this key is limited.
  53 In case of an 503 error, you can use the `/offline_analysis`.
  54
  55 ## run with docker
  56 - `docker image build -t service-analysis .`
  57 - `docker container run --env-file=analysis.env -d -p YOUR_PORT:8081 service-analysis:latest`
  58
  59 ## run local
  60 ### requirements
  61 - python 3.7
  62 - pip:
  63     - indicoio
  64     - flask
  65     - flask_restful
  66     - textblob
  67 ### commands
  68 - `python3.7 sentiment_analysis.py` to start the service
  69
  70 ## examples
  71 - positive online sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081 -d '[{"text":"happy birthday, i love you"}]'`
  72 - negative online sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081 -d '[{"text":"i hate you, please die"}]'`
  73 - positive offline sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081/offline_analysis -d '[{"text":"happy birthday, i love you"}]'`
  74 - negative offline sentiment test example: `curl -v -H 'content-type: application/json' -X POST http://localhost:8081/offline_analysis -d '[{"text":"i hate you, please die"}]'`
  75 - health check example: `curl -v -X GET http://localhost:8081/health`
  76 - invalid input example (error: 409): `curl -v -H 'content-type: application/json' -X POST http://localhost:8081 -d '[]'`