Text Label API Documentation

Text Label API Implementation instructions

Text Label API, used for the extraction of important phrases ("labels") in a message, uses a JSON-based RPC format and can be accessed trough GET and POST interfaces over the world wide web. The API endpoint is located at:

 

http://api.ai-applied.nl/api/text_label_api/

Note: All our API's allow demo and testing use for free. You can request an API key to test our API's using the form below, after which an API key with 5000 credits will be e-mailed to the provided e-mail address. The use of the API beyond this limit requires a commercial account and a API key. We will never share your e-mail address with anyone, and use it only to prevent the abuse of the demo functionality. At any time you can upgrade your demo key by adding purchased credits to it, or by switching to a subscription plan.

The API call can be passed in a JSON format using the POST of GET command: 

request={
"data":{
"api_key":"api_key",
"call":{
"return_original":true,
"labels_nr":0,
"specificity_level":0,
"summary":true,
"include_weights":false,
"data":[
{
"text":"Some message text",
"language_iso":"lng",
"id":some_id
}
]
}
}
}

This API accepts the following parameters:

 

ParameterObligatoryDescription
dataYestransport container for the API call
api_keyYesyour key for the use of this API
callYesthe API call information container
return_originalNoreturn full posted messages (true) together with the language annotation or only the message id's (false) annotated with language
labels_nrNoreturn the N (integer) number of labels for this text. If the value is not supplied, or the supplied value is 0, the system will automatically determine the appropriate number of labels to return based on how interesting the text is compared to the entire language it was written in
specificity_levelNoreturn phrases of a maximum of N (integer) words. Large values can extract whole sentences from text, while small values only extract key concepts. If no value is supplied, or the supplied value is 0, the system will automatically determine the appropriate maximal phrase length based on how interesting the text is compared to the entire language is was written in
summaryNodetermines whether, next to the labeling of individual texts, a additional summary should be returned displaying the frequencies/weights of the extracted label phrases for the whole data batch. The default value is false
include_weightsNodetermines whether to include the weighs for every label phrase in the reply, or whether to just return the labels themselves. The default value is false. If the parameter is set to true, and a summary is generated as well, the summary will use labels weights instead of label counts to calculate the label frequencies in the summary
dataYesa list of JSON-dictionary formatted messages, or a link to a data source API returning such formatted messages (see API nesting documentation)

All messages passed in the final data parameter need to be JSON formatted like the following example:

{
"text":"Some message text",
"language_iso":"iso_639_3_language",
"id":some_id
}

Every message  consists of the following parameters:

ParameterObligatoryDescription
textYesThe message text as a string
idYesa unique message ID as a string or an integer
language_isoYesspecifying the language of this individual message in a ISO-639-3 format as a string. ISO-639-3 codes for the supported languages are:

  • eng for English
  • nld for Dutch
  • deu for German
  • fra for French
  • spa for Spanish
  • ita for Italian
  • rus for Russian

  • While the appropriate languages can be provided to the Text Label API by you, the user, if you do not have this information available you can also use our Language Detection API to perform automatic language annotations for you. It is possible to do language annotation and demographics analysis in one pass using our API nesting method

    NOTE: All Ai Applied API's are much more efficient in BATCH PROCESSING mode than when processing one message at the time. We encourage the sending of up to 20.000 messages at a time for processing, as larger batches incur additional bonuses in processing speed per message.

    Sample call and response interpretation

    This example requests from the Text Label API the extraction of most important phrases from three messages in different languages. You can copy-paste the code below into your browser URL bar, or click here, to view the API response: 

     http://api.ai-applied.nl/api/text_label_api/?request={
    "data":{
    "api_key":"DEMO_ACCOUNT",
    "call":{
    "return_original":true,
    "summary":true,
    "data":[
    {
    "text":"sometimes you get pleasantly surprised from unexpected sources",
    "language_iso":"eng",
    "id":1
    },
    {
    "text":"Nou... dat is zeker de slechtste vertoning van Ajax in tijden. :(",
    "language_iso":"nld",
    "id":2
    },
    {
    "text":"Ich las heute Fifty Shades of Gray ... rrrr",
    "language_iso":"deu",
    "id":3
    }
    ]
    }
    }
    }

    This call returns the following JSON formatted message:

     

    {
    "status":1,
    "id":null,
    "response":{
    "data":[
    {
    "language_iso":"deu",
    "text":"Ich las heute Fifty Shades of Gray ... rrrr",
    "id":3,
    "text_labels":[
    "gray rrrr"
    ]
    },
    {
    "language_iso":"nld",
    "text":"Nou... dat is zeker de slechtste vertoning van Ajax in tijden. :(",
    "id":2,
    "text_labels":[
    "slechtste vertoning"
    ]
    },
    {
    "language_iso":"eng",
    "text":"sometimes you get pleasantly surprised from unexpected sources",
    "id":1,
    "text_labels":[
    "pleasantly surprised"
    ]
    }
    ],
    "description":"OK: Call processed.",
    "success":true,
    "summary":[
    [
    "slechtste vertoning",
    1
    ],
    [
    "pleasantly surprised",
    1
    ],
    [
    "gray rrrr",
    1
    ]
    ]
    }
    }

    Following parameters in API reply belong to the transport layer, and can be stripped away in case of success:   

    ParameterDescription
    statushas value 1 if the transport of the message has been conducted succesfully trough all systems
    ida optional callback parameter that can be ignored for this API
    responsecontains the response from the API classifiers

    The "response" parameter contains this API's reply and consists of the following subparameters:

    ParameterDescription
    successindicates whether the API call has been completed with success (==true), or has failed (==false)
    descriptiongives a description of the API call's success or failure as a string
    summaryis returned only if summary has been requested in the API call. It contains an array of arrays, each of which has the format [label_phrase, phrase_weight], summarizing the most important phrases over the entire processed batch of documents. The array is presented in a descending order based on phrase weight
    datacontains a list of topic-annotated texts provided by the API in a JSON format

    All messages returned in the data parameter are JSON formatted like the following example:

    {
    "language_iso":"eng",
    "text":"sometimes you get pleasantly surprised from unexpected sources",
    "id":1,
    "text_labels":[
    "pleasantly surprised"
    ]
    }

    When the "return_original" parameter is set to true in the API call, the returned messages contain all parameters provided to the API in the call in addition to the annotation parameters. If the "return_original" parameter is set to false in the API call, only the following annotation parameters are returned:

     

    ParameterDescription
    text_labelsthe phrases extracted from text. Depending on whether the include_weights parameter has been set to true or not during the API call, this parameter either contains a array of strings, representing the labels extracted from text if false, or an array of arrays which themselves are formatted as [label, weight] if true

    If you need more assistance with the implementation of this API, please don't hesitate to comment below, or contact us for assistance!