How to call the Text Analytics REST API

 07/30/2019
 3 minutes to read

o

 
o

 
o

 
o

 
o

 
o +6

In this article
1. Prerequisites
2. JSON schema definition
3. Set up a request in Postman
4. See also
5. Next steps

Calls to the Text Analytics API are HTTP POST/GET calls, which you can formulate in
any language. In this article, we use REST and Postman to demonstrate key concepts.

Each request must include your access key and an HTTP endpoint. The endpoint
specifies the region you chose during sign up, the service URL, and a resource used
on the request: sentiment, keyphrases, languages, and entities.

Recall that Text Analytics is stateless so there are no data assets to manage. Your text
is uploaded, analyzed upon receipt, and results are returned immediately to the
calling application.

 Tip

For detailed API technical documentation and to see it in action, use the following
links. You can also send POST requests from the built-in API test console. No setup is
required, simply paste your resource key and JSON documents into the request:
  Latest stable API - v3.0
 Latest preview API - v3.1-Preview.1
 Important

Text Analytics API v3 is not available in the following regions: Central India, UAE
North, China North 2, China East.

Prerequisites
A key and endpoint for a Text Analytics resource. Azure Cognitive Services are
represented by Azure resources that you subscribe to. Create a resource for Text
Analytics using the Azure portal or Azure CLI on your local machine. You can also
view your resource on the Azure portal

JSON schema definition

Input must be JSON in raw unstructured text. XML is not supported. The schema is
simple, consisting of the elements described in the following list.

You can currently submit the same documents for all Text Analytics operations:
sentiment, key phrase, language detection, and entity identification. (The schema is
likely to vary for each analysis in the future.)

JSON SCHEMA DEFINITION

Elemen Valid values Required Usage
t ?
id The data type is string, Required The system uses the IDs you provide to structure
but in practice the output. Language codes, key phrases, and
document IDs tend to sentiment scores are generated for each ID in the
be integers. request.
text Unstructured raw text, Required For language detection, text can be expressed in
up to 5,120 characters. any language. For sentiment analysis, key phrase
extraction and entity identification, the text must
be in a supported language.
language 2-character ISO 639- Varies Required for sentiment analysis, key phrase
1 code for a supported extraction, and entity linking; optional for
language language detection. There is no error if you
exclude it, but the analysis is weakened without it.
The language code should correspond to
the text you provide.

For more information about limits, see Text Analytics Overview > Data limits.

JSONCopy
{
 "documents": [
{
"language": "en",
"id": "1",
"text": "Sample text to be sent to the text analytics api."
},
{
"language": "en",
"id": "2",
"text": "It's incredibly sunny outside! I'm so happy."
},
{
"language": "en",
"id": "3",
"text": "Pike place market is my favorite Seattle attraction."
}
]
}

Set up a request in Postman

The service accepts request up to 1 MB in size. If you are using Postman (or another
Web API test tool), set up the endpoint to include the resource you want to use, and
provide the access key in a request header. Each operation requires that you append
the appropriate resource to the endpoint.

1. In Postman:
o Choose Post as the request type.
o Paste in the endpoint you copied from the portal page.
o Append a resource.

Resource endpoints are as follows (your region may vary):

o https://westus.api.cognitive.microsoft.com/text/analytics/v3.0/senti
ment
o https://westus.api.cognitive.microsoft.com/text/analytics/v3.0/keyPh
rases
o https://westus.api.cognitive.microsoft.com/text/analytics/v3.0/langu
ages
o https://westus.api.cognitive.microsoft.com/text/analytics/v3.0/entit
ies/recognition/general
2. Set the three request headers:
o Ocp-Apim-Subscription-Key: your access key, obtained from Azure portal.
o Content-Type: application/json.
o Accept: application/json.
 Your request should look similar to the following screenshot, assuming
a /keyPhrases resource.

3. Click Body and choose raw for the format.

4. Paste in some JSON documents in a format that is valid for the intended
analysis. For more information about a particular analysis, see the topics below:

 Language detection
 Key phrase extraction
 Sentiment analysis
 Entity recognition

6. Click Send to submit the request. See the data limits section in the overview

for information on the number of requests you can send per minute and
second.

In Postman, the response is displayed in the next window down, as a single

JSON document, with an item for each document ID provided in the request.