Codeq NLP API Documentation

API Authentication

The first thing you need to do before you start using Codeq's NLP API is to sign up to generate a User ID and User Key. These two pieces of information are required to make requests. Go ahead and sign up if you have not done it yet.

Get started

API Calls

Once you have obtained a User ID and User Key, you can make requests to our API in the two following ways:

1. By using our Python SDK.

2. By sending a POST request to the API endpoints

Rate Limits

There is a monthly rate limit of 1,000 request per user. If you are interested on a custom plan, please take a look at our pricing plans or contact us.

Python SDK

The easiest way to call the API is by using our Python SDK (requires Python 3). To install it:

pip install codeq-nlp-api -U
    

NLP Pipeline

Once installed, you can import the SDK and use it to initialize a client object. This client can be used to send a text request to the NLP Pipeline endpoint and retrieve a Document object, which encapsulates a list of Sentence objects with the analyzed information of the text:

from codeq_nlp_api import CodeqClient

client = CodeqClient(user_id="YOUR_USER_ID", user_key="YOUR_USER_KEY")

text = "This model is an expensive alternative with useless battery life."
document = client.analyze(text)

for sentence in document.sentences:
    print(sentence.sentiments)

"""
Output:
>> ['Negative']
"""

It is also possible to pass as input a list of sentences. In this case, the API will not apply it's own sentence segmentation:

sentences = ["This model is an expensive alternative.", "It has a useless battery life."]
document = client.analyze_sentences(sentences)
print(len(document.sentences))

"""
Output:
>> 2
"""
    

Text Similarity

The client can also be used to call the Text Similarity endpoint and retrieve a textual similarity score between two texts.

from codeq_nlp_api import CodeqClient

client = CodeqClient(user_id="YOUR_USER_ID", user_key="YOUR_USER_KEY")

text1 = "Some people are singing"
text2 = "A group of people is singing"

result = client.analyze_text_similarity(text1, text2)
print(result)

"""
Output:
>> {"text_similarity_score": 4.6}
"""
                

HTTP Request

Alternatively, you can call the API by sending a POST request to one of the following endpoints:

NLP Pipeline

The POST request to this endpoint must be composed with the following parameters:

user_id: the id provided on the registration process.

user_key: the key also generated on the registration process.

pipeline (optional): a string indicating the specific NLP annotators to apply.

And one of both:

text: a string to be analyzed.

sentences: or a list of strings to be analyzed (no sentence segmentation will be applied).

curl -X POST https://api.codeq.com/v1 \
    -d '{ \
        "user_id": "YOUR_USER_ID", \
        "user_key": "YOUR_USER_KEY", \
        "text": "This model is an expensive alternative with useless battery life." \
    }' \


# Output:
{
  "sentences": [
    {
      "position": 0,
      "raw_sentence": "This model is an expensive alternative with useless battery life.",
      "tokens": ["This", "model", "is", "an", "expensive", "alternative", "with", ... ],
      "pos_tags": ["DT", "NN", "VBZ", "DT", "JJ", "NN", "IN", "JJ", "NN", "NN", "."],
      "speech_acts": ["Statement"],
      "sentiments": ["Negative"],
      ...
    }
  ]
}
            

Text Similarity

The POST request to this endpoint must be composed with the following parameters:

user_id: the id provided on the registration process.

user_key: the key also generated on the registration process.

text1: the first document to be compared.

text2: the second document to be compared.

curl -X POST https://api.codeq.com/v1 \
    -d '{ \
        "user_id": "YOUR_USER_ID", \
        "user_key": "YOUR_USER_KEY", \
        "text1": "Some people are singing", \
        "text2": "A group of people is singing" \
    }' \

# Output:
{
  "text_similarity_score": 4.6
}
            

Response Status

Independently of the method you use to call our API, we will return a status code helpful to debug any error you may encounter. The following table summarizes the list of Status responses:

Calling a specific NLP Pipeline

By default, when you call the NLP Pipeline API you will retrieve a text fully analyzed by our complete set of NLP Annotators (see following sections).

Or you can specify a custom pipeline depending on your needs. For example, if you are only interested on getting the emotion and speech acts labels of a text, you can declare a "pipeline" key as parameter in the Python SDK client object or in the content of the POST request, and send as value a comma separated string indicating the Annotators you need:

client = CodeqClient(user_id="YOUR_USER_ID", user_key="YOUR_USER_KEY")

text = "This is getting very interesting!"
pipeline = "speechact, sentiment"
document = client.analyze(text, pipeline)

for sentence in document.sentences:
    print(sentence.speech_acts)
    print(sentence.sentiments)

"""
Output:
>> ['Statement']
>> ['Positive']
"""
            

The following sections show the complete list of Annotators of our NLP API, including the KEY you can use as value of the pipeline parameter, as well as the description of the Annotators' output and its respective Python attribute.

Linguistic Features

Named Entities

Text Classification

Summarization

Scores

The probability scores of some text classifiers are stored at the Sentence level on the variable sentence.scores. This variable is a dictionary that can be accessed using the same name of the annotator and contain the assigned label as key and the probability as value.