How to call the Text Analytics REST API

In this article, we use the Text Analytics REST API and Postman to demonstrate key concepts. The API provides several synchronous and asynchronous endpoints for using the features of the service.

Create a Text Analytics resource

Note

  • You will need a Text Analytics resource using a Standard (S) pricing tier if you want to use the /analyze or /health endpoints. The /analyze endpoint is included in your pricing tier.

Before you use the Text Analytics API, you will need to create a Azure resource with a key and endpoint for your applications.

  1. First, go to the Azure portal and create a new Text Analytics resource, if you don't have one already. Choose a pricing tier.

  2. Select the region you want to use for your endpoint. Please note the /analyze and /health endpoints are only available in the following regions: West US 2, East US 2, Central US, North Europe and West Europe.

  3. Create the Text Analytics resource and go to the “keys and endpoint blade” in the left of the page. Copy the key to be used later when you call the APIs. You'll add this later as a value for the Ocp-Apim-Subscription-Key header.

Using the API synchronously

You can call Text Analytics synchronously (for low latency scenarios). You have to call each API (feature) separately when using synchronous API. If you need to call multiple features then check out below section on how to call Text Analytics asynchronously.

Using the API asynchronously

Starting in v3.1-preview.3, the Text Analytics API provides two asynchronous endpoints:

  • The /analyze endpoint for Text Analytics allows you to analyze the same set of text documents with multiple text analytics features in one API call. Previously, to use multiple features you would need to make separate API calls for each operation. Consider this capability when you need to analyze large sets of documents with more than one Text Analytics feature.

  • The /health endpoint for Text Analytics for health, which can extract and label relevant medical information from clinical documents.

See the table below to see which features can be used asynchronously. Note that only a few features can be called from the /analyze endpoint.

Feature Synchronous Asynchronous
Language detection
Sentiment analysis
Opinion mining
Key phrase extraction ✔*
Named Entity Recognition (including PII and PHI) ✔*
Text Analytics for health (container)
Text Analytics for health (API)

* - Called asynchronously through the /analyze endpoint.

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:

API request formats

You can send both synchronous and asynchronous calls to the Text Analytics API.

Synchronous requests

The format for API requests is the same for all synchronous operations. Documents are submitted in a JSON object as raw unstructured text. XML is not supported. The JSON schema consists of the elements described below.

Element Valid values Required? Usage
id The data type is string, but in practice document IDs tend to be integers. Required The system uses the IDs you provide to structure the output. Language codes, key phrases, and sentiment scores are generated for each ID in the request.
text Unstructured raw text, up to 5,120 characters. Required For language detection, text can be expressed in any language. For sentiment analysis, key phrase extraction and entity identification, the text must be in a supported language.
language 2-character ISO 639-1 code for a supported language Varies Required for sentiment analysis, key phrase extraction, and entity linking; optional for 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.

The following is an example of an API request for the synchronous Text Analytics endpoints.

{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "Sample text to be sent to the text analytics api."
    }
  ]
}

Tip

See the Data and rate limits article for information on the rates and size limits for sending data to the Text Analytics API.

Set up a request

In Postman (or another web API test tool), add the endpoint for the feature you want to use. Use the table below to find the appropriate endpoint format, and replace <your-text-analytics-resource> with your resource endpoint. For example:

https://my-resource.cognitiveservices.azure.com/text/analytics/v3.0/languages

Endpoints for sending synchronous requests

Feature Request type Resource endpoints
Language detection POST <your-text-analytics-resource>/text/analytics/v3.0/languages
Sentiment analysis POST <your-text-analytics-resource>/text/analytics/v3.0/sentiment
Opinion Mining POST <your-text-analytics-resource>/text/analytics/v3.0/sentiment?opinionMining=true
Key phrase extraction POST <your-text-analytics-resource>/text/analytics/v3.0/keyPhrases
Named entity recognition - general POST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/general
Named entity recognition - PII POST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/pii
Named entity recognition - PHI POST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/pii?domain=phi

After you have your endpoint, in Postman (or another web API test tool):

  1. Choose the request type for the feature you want to use.

  2. Paste in the endpoint of the proper operation you want from the above table.

  3. Set the three request headers:

    • Ocp-Apim-Subscription-Key: your access key, obtained from Azure portal
    • Content-Type: application/json
    • Accept: application/json

    If you're using Postman, your request should look similar to the following screenshot, assuming a /keyPhrases endpoint.

    Request screenshot with endpoint and headers

  4. Choose raw for the format of the Body

    Request screenshot with body settings

  5. Paste in some JSON documents in a valid format. Use the examples in the API request format section above, and for more information and examples, see the topics below:

Send the request

Submit the API request. If you made the call to a synchronous endpoint, the response will be displayed immediately, as a single JSON document, with an item for each document ID provided in the request.

If you made the call to the asynchronous /analyze or /health endpoints, check that you received a 202 response code. you will need to get the response to view the results:

  1. In the API response, find the Operation-Location from the header, which identifies the job you sent to the API.

  2. Create a GET request for the endpoint you used. refer to the table above for the endpoint format, and review the API reference documentation. For example:

    https://my-resource.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/analyze/jobs/<Operation-Location>

  3. Add the Operation-Location to the request.

  4. The response will be a single JSON document, with an item for each document ID provided in the request.

Please note that for both asynchronous /analyze or /health operations, the results from the GET request in step 2 above are available for 24 hours from the time the job was created. This time is indicated by the expirationDateTime value in the GET response. After this time period, the results are purged and are no longer available for retrieval.

Example API responses

Example responses for synchronous operation

The synchronous endpoint responses will vary depending on the endpoint you use. See the following articles for example responses.

See also