Codeq NLP API Tutorial

Part 1. Getting started and making requests

In this series of posts we want to showcase different examples on how to call our NLP API to analyze your own texts.

Getting Started

To use our NLP API you need to sign up to generate a USER_ID and USER_KEY. Registration is free and we provide a developer plan with enough calls to start exploring our NLP tools.

Sign Up - Codeq Natural Language Processing API

Installation

Once you have signed up, next step would be to install our Python SDK:

pip install codeq-nlp-api -U

Import the client SDK and define a pipeline

The SDK can be used to create an instance of a client using your API credentials and analyze your own documents. By default, when you call the API you will retrieve a text fully analyzed by our complete set of NLP Annotators. Or you can specify a custom pipeline depending on your needs, for example a pipeline to analyze the speech acts, sentiments and emotions of a text:

from codeq_nlp_api import CodeqClient
client = CodeqClient(user_id="USER_ID", user_key="USER_KEY")
pipe='speechact, sentiment, emotion'

Analyze a text

Now you can pass a text and the pipeline you declared as input to the API client, which will return a Document object. The Document contains a list of Sentence objects with the analyzed information of the text:

text = "The hotel location is perfect. But the rooms are in great need of an upgrade."

document = client.analyze(text, pipeline=pipe)
for sentence in document.sentences:
    print(sentence.pretty_print())

In the last two lines, we iterate over the sentences extracted from the document and print all analyzed attributes for a quick look:

{
  "raw_sentence": "The hotel location is perfect.",
  "position": "0",
  "tokens": "['The', 'hotel', 'location', 'is', 'perfect', '.']",
  "speech_acts": "['Statement']",
  "sentiments": "['Positive']",
  "emotions": "['Joy/Like']"
}
{
  "raw_sentence": "But the rooms are in great need of an upgrade.",
  "position": "1",
  "tokens": "['But', 'the', 'rooms', 'are', 'in', 'great', 'need', 'of', 'an', 'upgrade', '.']",
  "speech_acts": "['Desire/Need']",
  "sentiments": "['Negative']",
  "emotions": "['Disgust/Dislike']"
}

You can also iterate over the results and access the specific attributes of each NLP annotator. A complete list of attributes can be found in our documentation; here is an example:

for sentence in document.sentences:
    print(sentence.raw_sentence)
    print("- speech_acts: %s" % sentence.speech_acts)
    print("- sentiments: %s" % sentence.sentiments)
    print("- emotions: %s\n" % sentence.emotions)

Wich will print:

The hotel location is perfect.
- speech_acts: [‘Statement’]
- sentiments: [‘Positive’]
- emotions: [‘Joy/Like’]
But the rooms are in great need of an upgrade.
- speech_acts: [‘Desire/Need’]
- sentiments: [‘Negative’]
- emotions: [‘Disgust/Dislike’]

Analyze a list of texts (or sentences)

The client can also be used to analyze list of texts or sentences without applying any further segmentation. This will keep the original structure of your texts, which can be helpful, for example, if you’re analyzing conversations. Let’s consider the following example:

texts = [
    "Hello! My name is John. Can I help you with something?",
    "I have not received the order I placed over two weeks ago. I already asked for it three times. This is frustrating!",
    "I'm sorry you have not received your order yet. Can you please let me know your order ID?",
    "What a terrible service you have!"
]

In this case, you just need to call the method client.analyze_sentences():

document = client.analyze_sentences(texts, pipeline=pipe)
for sentence in document.sentences:
    print(sentence.raw_sentence)
    print("- speech_acts: %s" % sentence.speech_acts)
    print("- sentiments: %s" % sentence.sentiments)
    print("- emotions: %s\n" % sentence.emotions)

The output will keep the original segmentation:

Hello! My name is John. Can I help you with something?
- speech_acts: ['Command/Request']
- sentiments: ['Neutral']
- emotions: ['No emotion']
I have not received the order I placed over two weeks ago. I already asked for it three times. This is frustrating!
- speech_acts: ['Statement']
- sentiments: ['Negative']
- emotions: ['Anger', 'Disgust/Dislike']
I'm sorry you have not received your order yet. Can you please let me know your order ID?
- speech_acts: ['Command/Request']
- sentiments: ['Neutral']
- emotions: ['Unknown emotion']
What a terrible service you have!
- speech_acts: ['Statement']
- sentiments: ['Negative']
- emotions: ['Disgust/Dislike']

Wrap Up

On this post we have shown how easy it is to send requests to our NLP API using our Python SDK and analyze your own texts. The following code snippet resumes the workflow explained above. Don’t forget to replace USER_ID and USER_KEY with your own API credentials.

• Take a look at our documentation to learn more about the NLP tools we provide.
• Do you need inspiration? Go to our use case demos and see how you can integrate different tools.
• In our NLP demos section you can also try our tools and find examples of the output of each module.