Before you begin

The Intent API is intended for web and mobile developers who want to extract intent (meaning) from sentences, texts, conversations. 

This service is generally designed to work with social media data, but can be used for blogs, forums, and enterprise data.

API Key

All Intent API applications should use an API key. The API uses API keys to identify applications. API key is received together with usage instructions as part of the plan setup procedure. Check out the Pricing page for details.

Usage limits

There are no limits to the number of calls you can make per minute/hour/day etc however all Intent API customers have limits based on the plan details. 

In the event that you exceed the monthly amount, you will receive error status ST_OVERLIMIT on all subsequent API calls.

Process status

Return status values:
ST_OK
ST_NOINTENT - requested intent not found
ST_OVERLIMIT - monthly limit
exceeded ST_ERROR - When API returns error additional error_message field provides more detailed information about the reasons behind the error.

How to use Intent API

Usually start by calling GetIntent, to find intent you are interested in, e.g.

api.nmodes.com/GetIntent?key=gen_key

GetInent is typically a one-time call.

Use the intent found in GetIntent for all subsequent calls to ProcessData along with your text messages, e.g.

api.nmodes.com/ProcessData?key=gen_key&data=I need a hotel room in downtown Toronto next week&intent=travel

Intent API requests

GetIntent

Get the list of all supported intents.

USAGE: api.nmodes.com/GetIntent?key=gen_key

ARGUMENTS:
key – Intent API key

RETURN:
status - ST_OK if okay, ST_ERROR if error, ST_OVERLIMIT if limit exceeded
error_message – empty, unless status is ST_ERROR
intent - list of available intents

JSON:

GetIntent
{
        "ReturnValue" :
        {
                "status" : "This is status"
                "error_message" : "message"
                "intent":
                [
                        {"intent":"This is intent"},
                        {"intent":"This is intent"},
                        {"intent":"This is intent"},
                ]
        }
}

XML:

<functionReturn>
        <name>GetIntent</name>
        <returnValue>
                <status>status</status>
                <error_message>message</error_message>
                <intent>intent</intent>
        </returnValue>
</functionReturn>

ProcessData

Analyze messages based on intent (from the supported list of intents). This call tells if the message has the intent in question, if yes, returns topic, as well as additional information (if available). Messages provided by the users.

USAGE: api.nmodes.com/ProcessData?key=gen_key&data="text"&intent="intent"

ARGUMENTS:
key - Intent API key
intent  - one of the supported intents, use GetIntent for full list of intents.
data – Incoming message

RETURN:
status -  ST_OK if okay, ST_ERROR if error, ST_OVERLIMIT if limit exceeded, ST_NOINTENT if intent not found
error_message – empty, unless status is ST_ERROR  
intent – confirms intent as requested, or, if intent is different, no additional information is returned   
topic  - topic for the intent, e.g. if intent is ‘purchasing’ the topic could be ‘shoes’
subtopic [optional]  – subtopic for the topic, e.g. if intent is ‘purchasing’ and the topic is  ‘shoes’ subtopic could be ‘Nike’
category [optional] -  category for the specific intent, e.g. if intent is ‘purchasing’ category could be ‘Awareness’
attribute [optional] – additional information, e.g. location, or emotional component, etc.

JSON:

ProcessData
{
        "ReturnValue" :
        {
                "status" : "This is status"
                "error_message" : "message"
                "topic" : "Topic"
                "subtopic" : "Subtopic"
                "category" : "Category"
                "extra" : "Data"
        }
}

XML:

<functionReturn>
        <name>ProcessData</name>
        <returnValue>
                <status>status</status>
                <topic>topic</topic>
                <error_message>message</error_message>
                <subtopic>subtopic</subtopic>
                <category>category</category>
                <extra>extra</extra>
        </returnValue>
</functionReturn>

ProcessDataNm

Analyze messages based on intent (from the supported list of intents). This call tells if the message has the intent in question, if yes, returns topic, as well as additional information (if available) .

Messages provided by nmodes (By default, messages are from Twitter).

USAGE: api.nmodes.com/ProcessDataNm?key=gen_key&intent="intent"&timestamp="timestamp"

ARGUMENTS:
key - Intent API key
intent  - one of the supported intents, use GetIntent for full list of intents.
timetamp -  time period to use when extracting data from data source (e.g. Twitter)

RETURN:
status -  ST_OK if okay, ST_ERROR if error, ST_OVERLIMIT if limit exceeded, ST_NOINTENT if intent not found
error_message – empty, unless status is ST_ERROR  
text  - processed text
intent – confirms intent as requested, or, if intent is different, no additional information is returned   
topic  - topic for the intent, e.g. if intent is ‘purchasing’ the topic could be ‘shoes’
subtopic [optional]  – subtopic for the topic, e.g. if intent is ‘purchasing’ and the topic is  ‘shoes’ subtopic could be ‘Nike’
category [optional] -  category for the specific intent, e.g. if intent is ‘purchasing’ category could be ‘Awareness’
attribute [optional] – additional information, e.g. location, or emotional component, etc.

JSON:

ProcessDataNm
{
        "ReturnValue" :
        {
                "status" : "status"
                "error_message" : "message"
                "text" : "Text"
                "topic" : "Topic"
                "subtopic" : "Subtopic"
                "category" : "Category"
                "extra" : "Data"
        }
}

XML:

<functionReturn>
        <name>ProcessDataNm</name>
                <returnValue>
                <status>status</status>
                <error_message>message</error_message>
                <text>text</text>
                <topic>topic</topic>
                <subtopic>subtopic</subtopic>
                <category>category</category>
                <extra>extra</extra>
        </returnValue>
</functionReturn>

RequestIntent

Request new intent If not found in the list of available intents ( GetIntent ). Execution of this call can be delayed (up to 24h).

USAGE: api.nmodes.com/RequestIntent?key=gen_key

ARGUMENTS:
key – Intent API key

RETURN:
status - ST_OK if okay, ST _ERROR if error