COURAGE_api

The advent of social media, the speed and interactions have surpassed our ability to monitor and understand their impact. This results in threats that are challenging to handle due to their range and variability over time, compounded by crucial ethical and practical issues, like preserving freedom of speech and allowing users to be collectively satisfied while dealing with the conflicts generated by their different opinions and contrasting interests. We provide the COURAGE API that features multiple detectors to tackle the described threats using deep learning. A range of algorithms for the analysis of social media content (images and text) were implemented, wrapped up into this API and are provided to partner institutions via demo interfaces. This repository contains detailed information on the endpoints and features all implementations as well as server deployment requirements.

Endpoints and routes

There are several endpoints:

Documentation of the endpoints related to the Twitter demo

General

Endpoint	HTTP method	Requires auth?	Description	Returned data	Requested data format
/info/	GET	no	Info on API when it is live and online	200 OK {'COURAGE': 'api', 'version': '1.0'} if up and running	none

Images

Endpoint	HTTP method	Requires auth?	Description	Returned data	Requested data format
/predict_bmi/	POST	no	BMI prediction based on an image. Returns predicted BMI and class label on success, else sends 444	200 OK {'bmi': <bmi>, 'label': <label>} on success, where <bmi> contains the BMI as float and <label> the body class as string. 400 Missing Arg if no image is passed to the endpoint. 444 Bad Request else	{image: <image>} as utf-8 encoded bytes string
/predict_gender/	POST	no	Gender prediction based on image. Returns predicted gender label on success, else sends 444	200 OK {'gender': <gender> } on success, where <gender> contains gender class label as string. 400 Missing Arg if no image is passed to the endpoint. 444 Bad Request else	{image: <image>} as utf-8 encoded bytes string
/detect_objects/	POST	no	Object detection in image. Returns predicted object labels on success, else sends 444	200 OK {'objects': [{'label': <label>, 'x': <x>, 'y': <y>, 'w': <w>, 'h': <h>}*n]} on success, where <label> is the name of one detected object, <x> is its x coordinate in the image, <y> its y coordinate, <w> its width and <h> its height. 400 Missing Arg if no image is passed to the endpoint. 444 Bad Request else	{image: <image>} as utf-8 encoded bytes string

Text

Overview

Method	EN	IT	ES	DE
Sentiment	X	X	X	X
Emotion	X	X	X	-
Hate Speech	X	X	-	P
Fake News	P	-	-	-
Toxicity	-	-	-	X

X = available; P = in progress; - not available or in progress

Italian

Endpoint	HTTP method	Requires auth?	Description	Returned data	Requested data format
/IT/sentiment/	POST	no	Sentiment prediction based on an Italian text. Returns positve/negative sentiment scores on success, else 444	200 OK {'negative': <neg>, 'positive': <pos>} on success, where <neg> is the probability (float) of negative sentiment and <pos> the probability of positive sentiment, <neg> + <pos> = 1. 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/IT/emotion/	POST	no	Emotion prediction based on an Italian text. Returns emotion types and confidence scores on success, else 444	200 OK {'label': <confidence>, ...} on success, where <label> is a emotion type as string and <confidence> the probability of this emotion (multiple key-value pairs). 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/IT/hate_speech/	POST	no	Prediction whether an Italian text is hate speech or not. Returns hate speech/not hate speech class labels, else 444	200 OK {'not hate': <n_hate>, 'hate': <hate>} on success, where <n_hate> is 1 if the text is not hate speech (<hate> = 0 then) or <hate> is 1 if the text is hate speech (<n_hate> = 0 then). 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string

English

Endpoint	HTTP method	Requires auth?	Description	Returned data	Requested data format
/EN/sentiment/	POST	no	Sentiment prediction based on an English text. Returns positive/neutral/negative sentiment scores on success, else 444	200 OK {'negative': <neg>, 'neutral': <neu>, 'positive': <pos>} on success, where <neg> is the probability (float) of negative sentiment, <neu> the probability of neutral sentiment and <pos> the probability of positive sentiment, <neg> + <neu> + <pos> = 1. 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/EN/hate_speech_semeval19/	POST	no	Predicts Hate Speech related characteristics based on an English text. Returns Hate Speech types and probability scores on success, else 444	200 OK {'hateful': <hate>, 'targeted': <targ>, 'aggressive': <agg>} on success, where <hate> is the probability (float) of the text being Hate Speech, and <targ> the probability (float) of the text being targeted to a specific individual and <agg> the probability (float) of the text being aggressive. 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/EN/hate_speech_facebook/	POST	no	Predicts whether an English Text contains Hate Speech or not. Returns (not) Hate Speech probability scores on success, else 444	200 OK {'not hate': <not_hate>, 'hate': <hate>} on success, where <not_hate> is the probability (float) of the text NOT being Hate Speech, and <hate> the probability (float) of the text being Hate Speech. 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/EN/emotion/	POST	no	Emotion prediction based on an English text. Returns emotion types and confidence scores on success, else 444	200 OK {'label': <confidence>, ...} on success, where <label> is a emotion type as string and <confidence> the probability of this emotion (multiple key-value pairs). 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/EN/topics/	POST	no	Topic identification based on an English text. Returns identified topics on success, else 444	200 OK {'topics': [<topic>, ...]} on success, where <topic> is one of the possible topics if its probability is larger than 0.5 (none or multiple values possible). 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/EN/topics_cip/	POST	no	Topic identification based on an English text (covers the following classes: covid, immigration, politics, other). Returns identified topic on success, else 444	200 OK {'topic': <topic>} on success, where <topic> is the topic with the highest probability (exactly one class of: covid, immigration, plitics, other). 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string

Spanish

Endpoint	HTTP method	Requires auth?	Description	Returned data	Requested data format
/ES/sentiment/	POST	no	Sentiment prediction based on a Spanish text. Returns positive/neutral/negative sentiment scores on success, else 444	200 OK {'negative': <neg>, 'neutral': <neu>, 'positive': <pos>} on success, where <neg> is the probability (float) of negative sentiment, <neu> the probability of neutral sentiment and <pos> the probability of positive sentiment, <neg> + <neu> + <pos> = 1. 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/ES/emotion/	POST	no	Emotion prediction based on a Spanish text. Returns emotion types and confidence scores on success, else 444	200 OK {'label': <confidence>, ...} on success, where <label> is a emotion type as string and <confidence> the probability of this emotion (multiple key-value pairs). 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string

German

Endpoint	HTTP method	Requires auth?	Description	Returned data	Requested data format
/DE/sentiment/	POST	no	Sentiment prediction based on a German text. Returns positive/neutral/negative sentiment scores on success, else 444	200 OK {'negative': <neg>, 'neutral': <neu>, 'positive': <pos>} on success, where <neg> is the probability (float) of negative sentiment, <neu> the probability of neutral sentiment and <pos> the probability of positive sentiment, <neg> + <neu> + <pos> = 1. 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string
/DE/toxic/	POST	no	Prediction whether a German text is toxic or not. Returns toxic/not toxic class labels, else 444	200 OK {'not toxic': <n_tox>, 'toxic': <tox>} on success, where <n_tox> is 1 if the text is not toxic (<tox> = 0 then) or <tox> is 1 if the text is toxic (<n_tox> = 0 then). 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string

Cross Lingual

Endpoint	HTTP method	Requires auth?	Description	Returned data	Requested data format
/cross_lingual/IT_EN/	POST	no	Translation of an Italian text to English on success, else 444	200 OK {'translation_text': <translation>} on success, where <translation> is the translated text in English. 400 Missing Arg if no text is passed to the endpoint. 444 Bad Request else	{'text': <text>} as string in Italian

Instructions for running the docker container

To successfully deploy the application on your machine as a docker container, you have to follow the steps listed below:

1. run sudo docker build -f Dockerfile -t courage_api . inside the root directory to build de docker image
2. run sudo docker run -d -p 5000:4000 courage_api to run the docker container

You can now check if the container is up and running sudo docker container ls -a