/commentIQ

Primary LanguagePythonGNU General Public License v2.0GPL-2.0

CommentIQ API

The Comment IQ API is a RESTful API used to evaluate comments on news articles and return scores based on four criteria shown to correlate with higher quality comments: Article Relevance, Conversational Relevance, Personal Experience, and Readability. These four criteria are explained briefly below, and in more detail in two research papers (including their validation as measures of higher quality comments):

  • N. Diakopoulos. The Editor’s Eye: Curation and Comment Relevance on the New York Times. Proc. Conference on Computer Supported Cooperative Work (CSCW). 2015. [PDF]
  • N. Diakopoulos. Picking the NYT Picks: Editorial Criteria and Automation in the Curation of Online News Comments. #ISOJ Journal. 2015. [PDF]

To install the API code and run it locally on your own server follow the instructions here

####Article Relevance This criterion calculates the comment score based on article similarity. The Article Relevance score is calculated by taking the cosine similarity or dot product of the respective normalized feature vectors for a comment and article to which it is attached.

####Conversational Relevance Conversational Relevance measures how similar a comment is to other comments on the same article. To measure conversational relevance, for each article’s comments a centroid feature vector is created representing the text of all of the comments on the article that were posted before a given comment. This represents the terms used across the thread up to that point in time. Then, for the next comment in the thread its cosine similarity to this centroid representation is calculated in order to measure the comment’s conversational relevance.

Personal Experience

The Personal Experience score is a measure of expressions of personal experiences calculated by counting the rate of use of words in Linguistic Inquiry and Word Count (LIWC) categories “I”, “We”, “Family”, and “Friends” which would reflect personal (1st and 3rd person pronouns) and close relational (i.e. family and friends) experiences.

Readability

The Readability score is calculated as the SMOG index or reading grade level of the text.

Length

The Length score is computed as the number of words in a comment.

###How to use the CommentIQ API There are 11 Different endpoints currently available, with their specific function, parameters and responses as described below. The basic gist of it is that you pass the API content (articles, and then comments associated with those articles) and the API will pass back the relevant scores. In order to provide a faster response time, content is cached on the CommentIQ server, which means that if your content changes (e.g. if an article is updated, or a comment is updated or deleted) you need to use the corresponding API endpoints so that the CommentIQ cache is synced and returning accurate scores.

  1. Add Article
  2. Update Article
  3. Add Comment
  4. Update Comment
  5. Delete Comment
  6. Get Article Relevance Score
  7. Get Conversational Relevance Score
  8. Get Personal Experience Score
  9. Get Readability Score
  10. Get Length Score
  11. Get All Scores
Name Values and Notes
Base URL http://api.comment-iq.com/commentIQ/v1
HTTP methods POST/GET
Response format JSON (.json)

1. Add Article

For new articles, article text needs to be sent via an HTTP POST method and an auto generated ArticleID will be sent in response. This Article ID needs to be kept track of in order to update the article or to add comments to the article in the future.
Note: Article ID is crucial in order to get the comment score

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/addArticle
HTTP method POST
Response format JSON (.json)

Parameters

Name Values and Notes
article_text Should be sent as key in a JSON format, Value Data Type: String

Response

Name Values and Notes
ArticleID Auto-generated ArticleID
status Success/Failure

Example

Python Code
import requests
import json

your_article_text = "Your Article Text"
url = "http://api.comment-iq.com/commentIQ/v1/addArticle"
params = {'article_text' : your_article_text }
param_json = json.dumps(params)
response = requests.post(url, param_json)
response_articleID = response.json()['articleID']
status = response.json()['status']
RESPONSE JSON
{
    "ArticleID": "172"
    "status": "Add Successful"
}

2. Update Article

To update articles - updated article text and ArticleID needs to be sent via an HTTP POST method.
Note: It is important to update the API database with updated article text if it changes in order to calculate the correct Article Relevance Score for a comment.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/updateArticle
HTTP method POST
Response format JSON (.json)

Parameters

Name Values and Notes
article_text Should be sent as key in a JSON format, Value Data Type: String
articleID Should be sent as key in a JSON format, Value Data Type: Integer/Number

Response

Name Values and Notes
status Success/Failure

Example

Python Code
import requests
import json

your_article_text = "Updated Article Text"
url = "http://api.comment-iq.com/commentIQ/v1/updateArticle"
params = {'article_text' : your_article_text, 'articleID' : articleID }
param_json = json.dumps(params)
response = requests.post(url, param_json)
status = response.json()['status']
RESPONSE JSON
{
    "status": "Update Successful"
}

3. Add Comment

For new comments - Comment Text and Article ID need to be sent via an HTTP POST method. All the scores will be calculated and sent via Response. An auto-generated commentID will also be sent in response. In order to get best results for conversational relevance make sure to add the comments of an article in chronological order.

Note: This Comment ID needs to be kept track of in order to update or delete the comment in the future.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/addComment
HTTP method POST
Response format JSON (.json)

Parameters

Required Parameters

Name Values and Notes
commentBody Should be sent as key in a JSON format, Value Data Type: String
articleID Should be sent as key in a JSON format, Value Data Type: Integer/Number

Optional Parameters

Name Values and Notes
commentDate Should be sent as key name In JSON format and its value should be a string in YYYY-MM-DD H:M:S format
recommendationCount Recommendation Count(or likes for comment) should be sent as key name in a JSON format, Value Data Type: Integer/Number
username Should be sent as key in a JSON format, Value Data Type: String
location Should be sent as key in a JSON format, Value Data Type: String

Response

Name Values and Notes
ArticleRelevance Comment Article Relevance Score
ConversationalRelevance Comment Conversational Relevance Score
PersonalXP Comment Personal Experience Score
Readability Comment Readability Score
Length Comment Length Score
commentID AutoGenerated Comment ID
status Success/Failure

Example1

Python Code
import requests
import json

your_comment_text = "Your Comment Text"
articleID = 78
url = "http://api.comment-iq.com/commentIQ/v1/addComment"
params = {'commentBody' : your_comment_text, 'articleID' : articleID }
param_json = json.dumps(params)
response = requests.post(url, param_json)
AR = response.json()['ArticleRelevance']
CR = response.json()['ConversationalRelevance']
personal_exp = response.json()['PersonalXP']
readability = response.json()['Readability']
Length = response.json()['Length']
commentID = response.json()['commentID']
status = response.json()['status']

Example2

Python Code
import requests
import json

your_comment_text = "Your Comment Text"
articleID = 78
todaysdate = "2015-01-13 14:11:32"
RecommendationCount = 9
username = 'johnsmith'
location = 'chicago'

url = "http://api.comment-iq.com/commentIQ/v1/addComment"

params = {'commentBody' : your_comment_text, 'articleID' : articleID, 'commentDate': todaysdate, \
'recommendationCount': RecommendationCount,'username': username,'location': location}

param_json = json.dumps(params)
response = requests.post(url, param_json)
AR = response.json()['ArticleRelevance']
CR = response.json()['ConversationalRelevance']
personal_exp = response.json()['PersonalXP']
readability = response.json()['Readability']
Length = response.json()['Length']
commentID = response.json()['commentID']
status = response.json()['status']
RESPONSE JSON
{
    "ArticleRelevance": "0.06496080742983745"
    "ConversationalRelevance": "0.4046152704799379"
    "PersonalXP": "0.0727272727273"
    "Readability": "17.2"
    "Length": "55"
    "status": "Add Successful"
    "commentID": "1714"
}

4. Update Comment

]]]To update comment - Comment Text and Comment ID needs to be sent via an HTTP POST method. All the scores will be calculated and sent via the Response.
Note: It is important to update the API with comment text that has changed in order to calculate the correct scores for a comment.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/updateComment
HTTP method POST
Response format JSON (.json)

Parameters

Required Parameters

Name Values and Notes
commentBody Should be sent as key in a JSON format, Value Data Type: String
commentID Should be sent as key in a JSON format, Value Data Type: Integer/Number

Optional Parameters

Name Values and Notes
commentDate Should be sent as key name In JSON format and its value should be a string in YYYY-MM-DD H:M:S format
recommendationCount Recommendation Count(or likes for comment) should be sent as key name in a JSON format, Value Data Type: Integer/Number
username Should be sent as key in a JSON format, Value Data Type: String
location Should be sent as key in a JSON format, Value Data Type: String

Response

Name Values and Notes
ArticleRelevance Comment Article Relevance Score
ConversationalRelevance Comment Conversational Relevance Score
PersonalXP Comment Personal Experience Score
Readability Comment Readability Score
Length Comment Length Score
status Success/Failure

Example

Python Code
import requests
import json

updated_comment_text = "Your Updated Comment Text"
commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/updateComment"
params = {'commentBody' : updated_comment_text, 'commentID' : commentID }
param_json = json.dumps(params)
response = requests.post(url, param_json)
AR = response.json()['ArticleRelevance']
CR = response.json()['ConversationalRelevance']
personal_exp = response.json()['PersonalXP']
readability = response.json()['Readability']
Length = response.json()['Length']
status = response.json()['status']
RESPONSE JSON
{
    "ArticleRelevance": "0.06496080742983745"
    "ConversationalRelevance": "0.4046152704799379"
    "PersonalXP": "0.0727272727273"
    "Readability": "17.2"
    "Length": "55"
    "Status": "Update Successful"
}

5. Delete Comment

To delete a comment - Comment ID needs to be sent via an HTTP DELETE method.
Note: Since Conversational Relevance depends upon all the previous comments, the database needs to be updated with any deleted comment(s).

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/deleteComment/commentID
HTTP method DELETE
Response format JSON (.json)

Parameters

Name Values and Notes
commentID Should be sent as part of URL, Value Data Type: Integer/Number

Response

Name Values and Notes
status Success/Failure

Example

Python Code
import requests
import json

commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/deleteComment/" + str(commentID)
response = requests.delete(url)
print response.json()
RESPONSE JSON
{
    "status": "Delete successful"
}

6. Get Article Relevance Score

To get the Article Relevance Score of a comment - the Comment ID needs to be sent via an HTTP GET method. The Article Relevance score will be fetched and sent via Response.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/getArticleRelevance/commentID
HTTP method GET
Response format JSON (.json)

Parameters

Name Values and Notes
commentID Should be sent as part of URL, Value Data Type: Integer/Number

Response

Name Values and Notes
ArticleRelevance Comment Article Relevance Score
status Success/Failure

Example

Python Code
import requests
import json

commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/getArticleRelevance/" + str(commentID)
response = requests.get(url)
print response.json()
RESPONSE JSON
{
    "ArticleRelevance": "0.06496080742983745"
    "status": "success"
}

7. Get Conversational Relevance Score

To get the Conversational Relevance Score of a comment - the Comment ID needs to be sent via HTTP GET method. The Conversational Relevance score will be fetched and sent via Response.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/getConversationalRelevance/commentID
HTTP method GET
Response format JSON (.json)

Parameters

Name Values and Notes
commentID Should be sent as part of URL, Value Data Type: Integer/Number

Response

Name Values and Notes
ConversationalRelevance Comment Conversational Relevance Score
status Success/Failure

Example

Python Code
import requests
import json

commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/getConversationalRelevance/" + str(commentID)
response = requests.get(url)
print response.json()
RESPONSE JSON
{
    "ConversationalRelevance": "0.40461527048"
    "status": "success"
}

8. Get Personal Experience Score

To get the Personal Experience Score of a comment - the Comment ID needs to be sent via HTTP GET method. The Personal Experience score will be fetched and sent via Response.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/getPersonalXP/commentID
HTTP method GET
Response format JSON (.json)

Parameters

Name Values and Notes
commentID Should be sent as part of URL, Value Data Type: Integer/Number

Response

Name Values and Notes
PersonalXP Comment Personal Experience Score
status Success/Failure

Example

Python Code
import requests
import json

commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/getPersonalXP/" + str(commentID)
response = requests.get(url)
print response.json()
RESPONSE JSON
{
    "PersonalXP": "0.0727272727273"
    "status": "success"
}

9. Get Readability Score

To get the Readability Score of a comment - Comment ID needs to be sent via an HTTP GET method. The Readability score will be fetched and sent via Response.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/getReadability/commentID
HTTP method GET
Response format JSON (.json)

Parameters

Name Values and Notes
commentID Should be sent as part of URL, Value Data Type: Integer/Number

Response

Name Values and Notes
Readability Comment Readability Score
status Success/Failure

Example

Python Code
import requests
import json

commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/getReadability/"+ str(commentID) 
response = requests.get(url)
print response.json()
RESPONSE JSON
{
    "Readability": "17.2"
    "status": "success"
}

10. Get Length Score

To get the Length Score of a comment - Comment ID needs to be sent via an HTTP GET method. The Length score will be fetched and sent via Response.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/getLength/commentID
HTTP method GET
Response format JSON (.json)

Parameters

Name Values and Notes
commentID Should be sent as part of URL, Value Data Type: Integer/Number

Response

Name Values and Notes
Length Comment Length Score
status Success/Failure

Example

Python Code
import requests
import json

commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/getLength/"+ str(commentID)
response = requests.get(url)
print response.json()
RESPONSE JSON
{
    "Length": "55"
    "status": "success"
}

11. Get All Scores

To get All Scores of a comment - the Comment ID needs to be sent via HTTP GET method. All the scores will be fetched and sent via Response.

Name Values and Notes
URL http://api.comment-iq.com/commentIQ/v1/getScores/commentID
HTTP method GET
Response format JSON (.json)

Parameters

Name Values and Notes
commentID Should be sent as part of URL, Value Data Type: Integer/Number

Response

Name Values and Notes
ArticleRelevance Comment Article Relevance Score
ConversationalRelevance Comment Conversational Relevance Score
PersonalXP Comment Personal Experience Score
Readability Comment Readability Score
Length Comment Length Score
status Success/Failure

Example

Python Code
imoport requests
import json

commentID = 172
url = "http://api.comment-iq.com/commentIQ/v1/getScores/"+ str(commentID)
response = requests.get(url)
print response.json()
RESPONSE JSON
{
    "ArticleRelevance": "0.06496080742983745"
    "ConversationalRelevance": "0.4046152704799379"
    "PersonalXP": "0.0727272727273"
    "Readability": "17.2"
    "Length": "55"
    "Status": "success"
}

To install the API code and run it locally on your own server follow the instructions here