API Nesting

API Nesting

Most of our API's can be chained in order to enforce processing of data by multiple API's in a single pass and with a single API call. This is useful in order to minimize the amount of information you need to pass back-and-forth between your infrastructure and our APIs, when you want to apply multiple processing steps to your data by using multiple of our APIs. Chainable API's are:

  • Text Extraction API*
  • Language Detection API
  • Demographics API
  • Text Label API
  • Sentiment Analysis API

Where only the output of the Text Extraction API can be processed further up the chain (if used, it must be the first API that is called), all other APIs can called at arbitrary locations in the processing chain.

API Nesting is achieved by supplying the "data" field, which usually contains the actual data to be processed, with a special parameter:

{"remote_resource":"api_name","data":{ full api call of requested api}}

The remote_resouce parameter determines which API should be called to process the data, while the data parameter contains your usual API call for that particular API. The callable API namecodes are:

API Name

Callable API code

Text Extraction API

text_extraction_api

Language Detection API

language_detection_api

Demographics API

demographics_api

Text Label API

text_label_api

Sentiment Analysis API

sentiment_api

When calling a remote_resource parameter, you provide a normal API call for the corresponding API into its data field. This includes providing the appropriate API key for every API you call through the remote_resource parameter.

WARNING: When calling remote_resource, please make sure that the return_original parameters of all API's being called are set to true, or API nesting will not work.

Example

API Nesting is useful for calling multiple API funtionalities in a single call. Consider, for instance, a situation in which you have the following corpus of texts submitted by a few people to your site, of which you would like to know the demographics and the sentiment:

  • "This is a wonderful opportunity for everyone" - John
  • "I am quite content either way" - Jenny
  • "This idea sucks" - Jeffrey

In order to detect demographics and sentiment of your corpus (which in reality is obviously much larger), you need to know the language each individual message is written in. While for this small example it is easy to establish that the used language is English, in real-world situations dealing with millions of real-time messages, manual language detection is not feasible. Ideally, you would like to annotate the raw messages with their language by the Language Detection API, then request the demographics information from the Demographics API, and finally have the sentiment annotated for you by the Sentiment Analysis API.

In order to achieve this, you would call the last API in your processing pipeline directly, in this case the Sentiment Analysis API:

http://api.ai-applied.nl/api/sentiment_api/?request={"data":{"api_key":"DEMO_ACCOUNT","call":{"return_original":true,"classifier":"subjective","data":[ YOUR_DATA ]}}}

Instead of providing the individual messages directly to the API, your can use a remote_resource parameter to call the Demographics API with it's parameters:

http://api.ai-applied.nl/api/sentiment_api/?request={"data":{"api_key":"DEMO_ACCOUNT","call":{"return_original":true,"classifier":"subjective","data":[ {"remote_resource": "demographics_api", "data": {"api_key": "DEMO_ACCOUNT", "call": {"return_original": true, "data": [ YOUR_DATA ]}}}]}}}

Before your data go to the Demographics API, you would like to have them processed by the Language Detection API, in order to have the appropriate language tagging required by the other API's. This can be achieved by adding another remote_resource to your current chain:

http://api.ai-applied.nl/api/sentiment_api/?request={"data":{"api_key":"DEMO_ACCOUNT","call":{"return_original":true,"classifier":"subjective","data":[ {"remote_resource": "demographics_api", "data": {"api_key": "DEMO_ACCOUNT", "call": {"return_original": true, "data": [ {"remote_resource": "language_detection_api", "data": {"api_key": "DEMO_ACCOUNT", "call": {"return_original": true, "data": [ YOUR_DATA ]}}} ]}}}]}}}

Your chain is now completed. Your full call, with your data inserted, looks as the following (click or copy-paste to a browser window to see the results):

http://api.ai-applied.nl/api/sentiment_api/?request={"data":{"api_key":"DEMO_ACCOUNT","call":{"return_original":true,"classifier":"subjective","data":[ {"remote_resource": "demographics_api", "data": {"api_key": "DEMO_ACCOUNT", "call": {"return_original": true, "data": [ {"remote_resource": "language_detection_api", "data": {"api_key": "DEMO_ACCOUNT", "call": {"return_original": true, "data": [ {"text":"This is a wonderful opportunity for everyone","user":"John"}, {"text":"I am quite content either way","user":"Jenny"},{"text":"This idea sucks","user":"Jeffrey"}]}}} ]}}}]}}}

The chained command yields the following reply:

{"status": 1, "id": null, "response": {"data": [{"confidence_sentiment": 0.4572169354822258, "text": "This is a wonderful opportunity for everyone", "confidence_language": 0.9999999999999991, "sentiment_class": "positive", "language_eng_name": "English", "language_iso": "eng", "confidence_gender": 0.9141521429638381, "user": "John", "gender": "male", "confidence_age": 0.28369693259912704, "age": "31-40"}, {"confidence_sentiment": 0.9483287304817927, "text": "I am quite content either way", "confidence_language": 0.9999999999990865, "sentiment_class": "neutral", "language_eng_name": "English", "language_iso": "eng", "confidence_gender": 0.6275927317152495, "user": "Jenny", "gender": "female", "confidence_age": 0.43603368888556926, "age": "31-40"}, {"confidence_sentiment": 0.9631489819827653, "text": "This idea sucks", "confidence_language": 0.9998334998463042, "sentiment_class": "negative", "language_eng_name": "English", "language_iso": "eng", "confidence_gender": 0.8901124592538052, "user": "Jeffrey", "gender": "male", "confidence_age": 0.3857077168808739, "age": "21-30"}], "description": "OK: Call processed.", "success": true}}

in which every text item has been processed and annotated for language, age, gender and sentiment using a single call, e.g:

{"confidence_sentiment": 0.4572169354822258, "text": "This is a wonderful opportunity for everyone", "confidence_language": 0.9999999999999991, "sentiment_class": "positive", "language_eng_name": "English", "language_iso": "eng", "confidence_gender": 0.9141521429638381, "user": "John", "gender": "male", "confidence_age": 0.28369693259912704, "age": "31-40"}

If you have more questions about API Nesting, please contact us!