/processing/linguistics/execute

Returns a content profile computed on the fly, given the unstructured natural language text of an input document. The content profile can be customized using customer-specific whitelists and blacklists. Whitelists and blacklists are referenced via processing dictionary identifiers.

The user must be authenticated and have read access to any referenced dictionary identifiers.

Request

The request object has the following fields:

Name	Type	Required	Description
`document`	Object	Yes	The input text to process. The keys are field names in the document, and a field's value is either a text block or a list of text blocks. The latter is beneficial for, e.g., fields that are composed of multiple paragraphs. The client can choose which field names to use, i.e., no special schema is enforced for this. All field values should be markup-free text, i.e., no HTML or XML.
`documentId`	String	No	Deprecated. An optional document identifier. Gets echoed in the response.
`language`	String	No	The language of the input document, expressed as a ISO 639-1 language code. If no language is specified, an algorithm for automatic language identification tries to infer the language.
`whitelistGroupId`	String	No	Deprecated. Use whitelistDictionaryIds instead.
`blacklistGroupId`	String	No	Deprecated. Use blacklistDictionaryIds instead.
`processing`	Object	No	Deprecated. Use whitelistDictionaryIds and blacklistDictionaryIds instead.
`whitelistDictionaryIds`	Array of String	No	The set of whitelist dictionaries to use for custom processing of the input text, in addition to standard processing. All dictionaries are applied sequentially and independently of each other. A whitelist dictionary is typically configured to be consulted in `overlap` mode, and is applied to the textual field values in the request's `document` object.
`blacklistDictionaryIds`	Array of String	No	The set of blacklist dictionaries to use for custom processing of the input text, in addition to standard processing. A match in any of the specified blacklist dictionaries will suffice for blacklisting. A blacklist dictionary is typically configured to be consulted in `complete` mode, and is applied to the `item` values in the response's `profile` object.
`customOnly`	Boolean	No	If `true`, the input text will only be processed with the dictionaries specified with `whitelistDictionaryIds and blacklistDictionaryIds`. I.e., the default text processing for the specified or inferred language will be skipped.

The processing object has the following fields:

Name	Type	Required	Description
`whitelist`	Array of Object	No	Deprecated. Use whitelistDictionaryIds in request object instead.
`blacklist`	Array of Object	No	Deprecated. Use blacklistDictionaryIds in request object instead.

"processing": {
 "whitelist": [
 {"dictionaryId": "1111111111111111"},
 {"dictionaryId": "2222222222222222"}
 ],
 "blacklist": [
 {"dictionaryId": "3333333333333333"},
 ]
}

An individual whitelist or blacklist dictionary reference object has the following fields:

Name	Type	Required	Description
`dictionaryId`	String	Yes	Deprecated. Use whitelistDictionaryIds and blacklistDictionaryIds in request object instead.

Whitelist and blacklist dictionaries can be defined and updated using the /processing/dictionary/update API. Dictionaries can be provided in JSON format or as Excel workbooks.

Don't mix this deprecated old-style fields (for example for the ESCENIC Semantic Plugin configuration):

documentId
whitelistGroupId
blacklistGroupId
processing

with their new-style versions:

whitelistDictionaryIds
blacklistDictionaryIds

You will get this error message in the API response:==> { "error": "Invalid request: Mixing of old and new request formats not allowed." }

Response

The response object has the following fields:

Name	Type	Description
`profile`	Object	The content profile computed from the input text. See /profile/content/fetch for documentation of the object structure.
`documentId`	String	Deprecated. Only used if the request specified documentId.
`language`	String	The [ISO 639-1](http://ISO 639-1) language code denoting the language that was assumed when the input text was processed. If no language code was explicitly specified as part of the request, this will then yield the result of the automatic language detection algorithm.
`processing`	Object	Deprecated. Only used if the request specified `processing.`
`whitelistGroupId`	String	Deprecated. Only used if the request specified `whitelistGroupId`.
`blacklistGroupId`	String	Deprecated. Only used if the request specified `blacklistGroupId`.

Examples

Bash

$ # Note that 'title' and 'body' are arbitrary field names, that all input text is markup-free, and that fields with multiple paragraphs are best supplied as lists.
$ python cx.py /processing/linguistics/execute '{"document":{"title":"Inconceivable!", "body":["My name is Inigo Montoya. You killed my father.", "Prepare to die."]}}'
{
 "profile": [
 {
 "item": "inigo montoya",
 "groups": [
 {
 "count": 1,
 "group": "person",
 "weight": 1.0
 }
 ]
 },
 {
 "item": "en",
 "groups": [
 {
 "count": 1,
 "group": "language",
 "weight": 0.1
 }
 ]
 }
 ],
 "language": "en"
}

Bash

$ # Note that 'title' and 'body' are arbitrary field names, that all input text is markup-free, and that fields with multiple paragraphs are best supplied as lists. The caller has read access to the referenced dictionaries.
$ python cx.py /processing/linguistics/execute '{"document":{"title":"Great food", "body":["I like pastrami very much.", "Really, it is almost as good as bacon."]}, "customOnly":true, "whitelistDictionaryIds":["13579"], "blacklistDictionaryIds":["24680"]}'
{
 "profile": [
 {
 "item": "pastrami",
 "groups": [
 {
 "count": 1,
 "group": "meat",
 "weight": 1.0
 }
 ]
 }
 ]
}

The cx.py utility used in the examples above is available from here.

Last updated: December 28, 2023