Starts a new text analytics job

post/analytics

Internal-Use Only

Starts a new background job that performs text analytics on the unstructured text in the objects found by the search. The job extracts significant terms, phrases, and topics as well as resolving named person, location, and organization entities. The response will include the unique identifier to be used with the related API endpoints to navigate the results.

Request Samples

application/json
analyticsRequest
1

Response Samples

202
application/json
1{
2  "identifier": "dff24648-3310-481f-8890-38ea823c4562",
3  "state": "running",
4  "types": [
5    "email"
6  ],
7  "query": {
8    "type": "object",
9    "objectIds": [
10      {
11        "type": "email",
12        "id": "2417"
13      },
14      {
15        "type": "email",
16        "id": "1327"
17      },
18      {
19        "type": "email",
20        "id": "2659"
21      }
22    ]
23  },
24  "categories": [
25    "significantTerm",
26    "topic",
27    "person",
28    "organization"
29  ],
30  "fields": [
31    "subject",
32    "body"
33  ],
34  "fromField": "metadatafrom",
35  "toFields": [
36    "metdatato",
37    "cc"
38  ],
39  "excludes": {
40    "significantTerm": [
41      "fw",
42      "time",
43      "pls"
44    ],
45    "person": [
46      "Pam Evens"
47    ]
48  },
49  "identities": {
50    "person": [
51      {
52        "name": "james robert smith",
53        "aliases": [
54          {
55            "name": "james robert smith"
56          },
57          {
58            "name": "james smith"
59          }
60        ]
61      }
62    ]
63  },
64  "maxResultsPerCategory": 200,
65  "locale": "en-US",
66  "errors": [],
67  "links": [
68    {
69      "method": "GET",
70      "rel": "self",
71      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562",
72      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562",
73      "type": "application/vnd.sas.sand.analytics.job"
74    },
75    {
76      "method": "GET",
77      "rel": "state",
78      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/state",
79      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/state",
80      "type": "text/plain"
81    },
82    {
83      "method": "PUT",
84      "rel": "cancel",
85      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/state?value=cancelled",
86      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/state?value=cancelled",
87      "responseType": "text/plain"
88    },
89    {
90      "method": "DELETE",
91      "rel": "delete",
92      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562",
93      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562"
94    },
95    {
96      "method": "GET",
97      "rel": "getIdentities",
98      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/identities",
99      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/identities",
100      "type": "application/vnd.sas.sand.analytics.explore",
101      "responseType": "application/vnd.sas.sand.analytics.identities"
102    },
103    {
104      "method": "POST",
105      "rel": "getCategories",
106      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/categories",
107      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/categories",
108      "type": "application/vnd.sas.sand.analytics.explore",
109      "responseType": "application/vnd.sas.sand.analytics.categories"
110    },
111    {
112      "method": "POST",
113      "rel": "getResults",
114      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/results",
115      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/results",
116      "type": "application/vnd.sas.sand.analytics.explore",
117      "responseType": "application/vnd.sas.sand.analytics.results"
118    },
119    {
120      "method": "POST",
121      "rel": "getSankeyDiagram",
122      "href": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/sankeyDiagrams",
123      "uri": "/svi-sand/analytics/dff24648-3310-481f-8890-38ea823c4562/sankeyDiagrams",
124      "type": "application/vnd.sas.sand.analytics.sankey.diagram.request",
125      "responseType": "application/vnd.sas.sand.analytics.sankey.diagram"
126    },
127    {
128      "method": "GET",
129      "rel": "getLocales",
130      "href": "/svi-sand/analytics/locales",
131      "uri": "/svi-sand/analytics/locales",
132      "type": "application/vnd.sas.collection",
133      "itemType": "application/vnd.sas.sand.analytics.locale"
134    },
135    {
136      "method": "POST",
137      "rel": "startTextAnalytics",
138      "href": "/svi-sand/analytics",
139      "uri": "/svi-sand/analytics",
140      "type": "application/vnd.sas.sand.analytics.request",
141      "responseType": "application/vnd.sas.sand.analytics.job"
142    }
143  ]
144}

Request Body

The request to /analytics to initiate a new text analytics job. The job analyses unstructured text in the matching search results to extract significant terms, phrases, and topics as well as resolve named person, organization, and location entities.

Name	Type	Required	Description
version	integer	false	The representation version (2).
types	array [string]	false	The optional list of type names for the object types to search. If missing, all types will be searched.
query	Query or anyOf QueryTypeAndQueryTypeCompoundQueryTypeObjectQueryTypeOrQueryTypeText	false	The different query types that can be used to search for objects. See specific query definitions for more details.
categories	array [string]	false	The optional list of categories specifying which types of analytics results to generate. Allowed values: unigrambigramtrigrampersonorganizationlocationsignificantTermtopic
fields	array [string]	false	The optional list of fields whose values will be combined to generate the corpus. Using this parameter overrides the administrator defined fields specified in the entity configuration.
fromField	string	false	The optional field whose values will be used when generating the Sankey diagram. Using this parameter overrides the administrator defined "from" field specified in the entity configuration.
toFields	array [string]	false	The optional fields whose values will be used when generating the Sankey diagram. Using this parameter overrides the administrator defined "to" fields specified in the entity configuration.
excludes	AnalyticsExcludesMap	false	The optional list of terms, phrases, topics, and entities to exclude from the analytics results keyed by category.
identities	AnalyticsIdentitiesMap	false	The identities keyed by category (person, organization, or location). Resolved entity results matching any of the aliases will be grouped under the respective identity name.
maxResultsPerCategory	integer	false	The maximum number of results to generate per category. Accepts values in the range 10 to 1000. The default value is 100.
locale	string	false	The locale of the data as a BCP-47 language tag.

Responses

Status	Meaning	Description
202	Accepted	The job was started.	Headers	Schema
400	Bad Request	The request is malformed or contains invalid parameter values.		Schema