# Using the Amazon Comprehend API
The Amazon Comprehend API supports operations to perform real-time (synchronous) analysis and operations to start and manage asynchronous analysis jobs.
You can use the Amazon Comprehend API operators directly, or you can use the CLI or one of the SDKs. The examples in this chapter use the CLI, the Python SDK, and Java SDK.
To run the AWS CLI and Python examples, you must install the AWS CLI. For more information, see [Set up the AWS Command Line Interface (AWS CLI)](setting-up.md#setup-awscli).
To run the Java examples, you must install the AWS SDK for Java. For instructions for installing the SDK for Java, see [ Set up the AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html).
**Topics**
+ [Using Amazon Comprehend with an AWS SDK](sdk-general-information-section.md)
+ [Real-time analysis using the API](using-api-sync.md)
+ [Async analysis jobs using the API](api-async.md)
# Using Amazon Comprehend with an AWS SDK
AWS software development kits (SDKs) are available for many popular programming languages. Each SDK provides an API, code examples, and documentation that make it easier for developers to build applications in their preferred language.
| SDK documentation | Code examples |
| --- | --- |
| [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/sdk-for-cpp) | [AWS SDK for C\$1\$1 code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp) |
| [AWS CLI](https://docs.aws.amazon.com/cli) | [AWS CLI code examples](https://docs.aws.amazon.com/code-library/latest/ug/cli_2_code_examples.html) |
| [AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go) | [AWS SDK for Go code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2) |
| [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java) | [AWS SDK for Java code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2) |
| [AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript) | [AWS SDK for JavaScript code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3) |
| [AWS SDK for Kotlin](https://docs.aws.amazon.com/sdk-for-kotlin) | [AWS SDK for Kotlin code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin) |
| [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net) | [AWS SDK for .NET code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv3) |
| [AWS SDK for PHP](https://docs.aws.amazon.com/sdk-for-php) | [AWS SDK for PHP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php) |
| [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell) | [AWS Tools for PowerShell code examples](https://docs.aws.amazon.com/code-library/latest/ug/powershell_5_code_examples.html) |
| [AWS SDK for Python (Boto3)](https://docs.aws.amazon.com/pythonsdk) | [AWS SDK for Python (Boto3) code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python) |
| [AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby) | [AWS SDK for Ruby code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby) |
| [AWS SDK for Rust](https://docs.aws.amazon.com/sdk-for-rust) | [AWS SDK for Rust code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1) |
| [AWS SDK for SAP ABAP](https://docs.aws.amazon.com/sdk-for-sapabap) | [AWS SDK for SAP ABAP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap) |
| [AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift) | [AWS SDK for Swift code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) |
**Example availability**
Can't find what you need? Request a code example by using the **Provide feedback** link at the bottom of this page.
# Real-time analysis using the API
The following examples demonstrate how to use Amazon Comprehend API for real-time analysis, using the AWS CLI, and the AWS SDKs for .NET, Java, and Python. Use the examples to learn about the Amazon Comprehend synchronous operations and as building blocks for your own applications.
The .NET examples in this section use the [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/welcome.html). You can use the [AWS Toolkit for Visual Studio](https://docs.aws.amazon.com/AWSToolkitVS/latest/UserGuide/welcome.html) to develop AWS applications using .NET. It includes helpful templates and the AWS Explorer for deploying applications and managing services. For a .NET developer perspective of AWS, see the [AWS guide for .NET developers](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/welcome.html).
**Topics**
+ [Detecting the dominant language](#get-started-api-dominant-language)
+ [Detecting named entities](#get-started-api-entities)
+ [Detecting key phrases](#get-started-api-key-phrases)
+ [Determining sentiment](#get-started-api-sentiment)
+ [Real-time analysis for targeted sentiment](#get-started-api-targeted-sentiment)
+ [Detecting syntax](#get-started-api-syntax)
+ [Real-time batch APIs](#get-started-batch)
## Detecting the dominant language
To determine the dominant language used in text, use the [DetectDominantLanguage](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectDominantLanguage.html) operation. To detect the dominant language in up to 25 documents in a batch, use the [BatchDetectDominantLanguage](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectDominantLanguage.html) operation. For more information, see [Real-time batch APIs](#get-started-batch).
**Topics**
+ [Using the AWS Command Line Interface](#get-started-api-dominant-language-cli)
+ [Using the AWS SDK for Java, SDK for Python, or SDK for .NET](#get-started-api-dominant-language-java)
### Using the AWS Command Line Interface
The following example demonstrates using the `DetectDominantLanguage` operation with the AWS CLI.
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend detect-dominant-language \
--region region \
--text "It is raining today in Seattle."
```
Amazon Comprehend responds with the following:
```
{
"Languages": [
{
"LanguageCode": "en",
"Score": 0.9793661236763
}
]
}
```
### Using the AWS SDK for Java, SDK for Python, or SDK for .NET
For SDK examples of how to determine the dominant language, see [Use `DetectDominantLanguage` with an AWS SDK or CLI](example_comprehend_DetectDominantLanguage_section.md).
## Detecting named entities
To determine the named entities in a document, use the [DetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectEntities.html) operation. To detect entities in up to 25 documents in a batch, use the [BatchDetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectEntities.html) operation. For more information, see [Real-time batch APIs](#get-started-batch).
**Topics**
+ [Using the AWS Command Line Interface](#get-started-api-entities-cli)
+ [Using the AWS SDK for Java, SDK for Python, or SDK for .NET](#get-started-api-entities-java)
### Using the AWS Command Line Interface
The following example demonstrates using the `DetectEntities` operation using the AWS CLI. You must specify the language of the input text.
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend detect-entities \
--region region \
--language-code "en" \
--text "It is raining today in Seattle."
```
Amazon Comprehend responds with the following:
```
{
"Entities": [
{
"Text": "today",
"Score": 0.97,
"Type": "DATE",
"BeginOffset": 14,
"EndOffset": 19
},
{
"Text": "Seattle",
"Score": 0.95,
"Type": "LOCATION",
"BeginOffset": 23,
"EndOffset": 30
}
],
"LanguageCode": "en"
}
```
### Using the AWS SDK for Java, SDK for Python, or SDK for .NET
For SDK examples of how to determine the dominant language, see [Use `DetectEntities` with an AWS SDK or CLI](example_comprehend_DetectEntities_section.md).
## Detecting key phrases
To determine the key noun phrases used in text, use the [DetectKeyPhrases](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectKeyPhrases.html) operation. To detect the key noun phrases in up to 25 documents in a batch, use the [BatchDetectKeyPhrases](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectKeyPhrases.html) operation. For more information, see [Real-time batch APIs](#get-started-batch).
**Topics**
+ [Using the AWS Command Line Interface](#get-started-api-key-phrases-cli)
+ [Using the AWS SDK for Java, SDK for Python, or SDK for .NET](#get-started-api-key-phrases-java)
### Using the AWS Command Line Interface
The following example demonstrates using the `DetectKeyPhrases` operation with the AWS CLI. You must specify the language of the input text.
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend detect-key-phrases \
--region region \
--language-code "en" \
--text "It is raining today in Seattle."
```
Amazon Comprehend responds with the following:
```
{
"LanguageCode": "en",
"KeyPhrases": [
{
"Text": "today",
"Score": 0.89,
"BeginOffset": 14,
"EndOffset": 19
},
{
"Text": "Seattle",
"Score": 0.91,
"BeginOffset": 23,
"EndOffset": 30
}
]
}
```
### Using the AWS SDK for Java, SDK for Python, or SDK for .NET
For SDK examples that detect key phrases, see [Use `DetectKeyPhrases` with an AWS SDK or CLI](example_comprehend_DetectKeyPhrases_section.md).
## Determining sentiment
Amazon Comprehend provides the following API operations for analyzing sentiment:
+ [DetectSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectSentiment.html) – Determines the overall emotional sentiment of a document.
+ [BatchDetectSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectSentiment.html) – Determine the overall sentiment in up to 25 documents in a batch. For more information, see [Real-time batch APIs](#get-started-batch)
+ [StartSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartSentimentDetectionJob.html) – Starts an asynchronous sentiment detection job for a collection of documents.
+ [ListSentimentDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListSentimentDetectionJobs.html) – Returns the list of sentiment detection jobs that you have submitted.
+ [DescribeSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeSentimentDetectionJob.html) – Gets the properties (including status) associated with the specified sentiment detection job.
+ [StopSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StopSentimentDetectionJob.html) – Stops the specified in-progress sentiment job.
**Topics**
+ [Using the AWS Command Line Interface](#get-started-api-sentiment-cli)
+ [Using the AWS SDK for Java, SDK for Python, or SDK for .NET](#get-started-api-sentiment-java)
### Using the AWS Command Line Interface
The following example demonstrates using the `DetectSentiment` operation with the AWS CLI. This example specifies the language of the input text.
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend detect-sentiment \
--region region \
--language-code "en" \
--text "It is raining today in Seattle."
```
Amazon Comprehend responds with the following:
```
{
"SentimentScore": {
"Mixed": 0.014585512690246105,
"Positive": 0.31592071056365967,
"Neutral": 0.5985543131828308,
"Negative": 0.07093945890665054
},
"Sentiment": "NEUTRAL",
"LanguageCode": "en"
}
```
### Using the AWS SDK for Java, SDK for Python, or SDK for .NET
For SDK examples that determine the sentiment of input text, see [Use `DetectSentiment` with an AWS SDK or CLI](example_comprehend_DetectSentiment_section.md).
## Real-time analysis for targeted sentiment
Amazon Comprehend provides the following API operations for targeted sentiment real-time analysis:
+ [DetectTargetedSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectTargetedSentiment.html) – Analyzes sentiment of the entities mentioned in a document.
+ [BatchDetectTargetedSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectTargetedSentiment.html) – Analyzes targeted sentiment for up to 25 documents in a batch. For more information, see [Real-time batch APIs](#get-started-batch)
If the text you are analyzing doesn't include any targeted sentiment [Entity types](how-targeted-sentiment.md#how-targeted-sentiment-entities), the API returns an empty Entities array.
### Using the AWS Command Line Interface
The following example demonstrates using the `DetectTargetedSentiment` operation with the AWS CLI. This example specifies the language of the input text.
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend detect-targeted-sentiment \
--region region \
--language-code "en" \
--text "The burger was cooked perfectly but it was cold. The service was OK."
```
Amazon Comprehend responds with the following:
```
{
"Entities": [
{
"DescriptiveMentionIndex": [
0
],
"Mentions": [
{
"BeginOffset": 4,
"EndOffset": 10,
"Score": 1,
"GroupScore": 1,
"Text": "burger",
"Type": "OTHER",
"MentionSentiment": {
"Sentiment": "POSITIVE",
"SentimentScore": {
"Mixed": 0.001515,
"Negative": 0.000822,
"Neutral": 0.000243,
"Positive": 0.99742
}
}
},
{
"BeginOffset": 36,
"EndOffset": 38,
"Score": 0.999843,
"GroupScore": 0.999661,
"Text": "it",
"Type": "OTHER",
"MentionSentiment": {
"Sentiment": "NEGATIVE",
"SentimentScore": {
"Mixed": 0,
"Negative": 0.999996,
"Neutral": 0.000004,
"Positive": 0
}
}
}
]
},
{
"DescriptiveMentionIndex": [
0
],
"Mentions": [
{
"BeginOffset": 53,
"EndOffset": 60,
"Score": 1,
"GroupScore": 1,
"Text": "service",
"Type": "ATTRIBUTE",
"MentionSentiment": {
"Sentiment": "NEUTRAL",
"SentimentScore": {
"Mixed": 0.000033,
"Negative": 0.000089,
"Neutral": 0.993325,
"Positive": 0.006553
}
}
}
]
}
]
}
```
## Detecting syntax
To parse text to extract the individual words and determine the parts of speech for each word, use the [DetectSyntax](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectSyntax.html) operation. To parse the syntax of up to 25 documents in a batch, use the [BatchDetectSyntax](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectSyntax.html) operation. For more information, see [Real-time batch APIs](#get-started-batch).
**Topics**
+ [Using the AWS Command Line Interface.](#get-started-api-syntax-cli)
+ [Using the AWS SDK for Java, SDK for Python, or SDK for .NET](#get-started-api-syntax-java)
### Using the AWS Command Line Interface.
The following example demonstrates using the `DetectSyntax` operation with the AWS CLI. This example specifies the language of the input text.
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend detect-syntax \
--region region \
--language-code "en" \
--text "It is raining today in Seattle."
```
Amazon Comprehend responds with the following:
```
{
"SyntaxTokens": [
{
"Text": "It",
"EndOffset": 2,
"BeginOffset": 0,
"PartOfSpeech": {
"Tag": "PRON",
"Score": 0.8389829397201538
},
"TokenId": 1
},
{
"Text": "is",
"EndOffset": 5,
"BeginOffset": 3,
"PartOfSpeech": {
"Tag": "AUX",
"Score": 0.9189288020133972
},
"TokenId": 2
},
{
"Text": "raining",
"EndOffset": 13,
"BeginOffset": 6,
"PartOfSpeech": {
"Tag": "VERB",
"Score": 0.9977611303329468
},
"TokenId": 3
},
{
"Text": "today",
"EndOffset": 19,
"BeginOffset": 14,
"PartOfSpeech": {
"Tag": "NOUN",
"Score": 0.9993606209754944
},
"TokenId": 4
},
{
"Text": "in",
"EndOffset": 22,
"BeginOffset": 20,
"PartOfSpeech": {
"Tag": "ADP",
"Score": 0.9999061822891235
},
"TokenId": 5
},
{
"Text": "Seattle",
"EndOffset": 30,
"BeginOffset": 23,
"PartOfSpeech": {
"Tag": "PROPN",
"Score": 0.9940338730812073
},
"TokenId": 6
},
{
"Text": ".",
"EndOffset": 31,
"BeginOffset": 30,
"PartOfSpeech": {
"Tag": "PUNCT",
"Score": 0.9999997615814209
},
"TokenId": 7
}
]
}
```
### Using the AWS SDK for Java, SDK for Python, or SDK for .NET
For SDK examples that detect the syntax of input text, see [Use `DetectSyntax` with an AWS SDK or CLI](example_comprehend_DetectSyntax_section.md).
## Real-time batch APIs
To send batches of up to 25 documents, you can use the Amazon Comprehend real-time batch operations. Calling a batch operation is identical to calling the single document APIs for each document in the request. Using the batch APIs can result in better performance for your applications. For more information, see [Multiple document synchronous processing](concepts-processing-modes.md#how-batch).
**Topics**
+ [Batch processing with the AWS CLI](#batch-cli)
+ [Batch processing with the AWS SDK for .NET](#batch-csharp)
### Batch processing with the AWS CLI
These examples show how to use the batch API operations using the AWS Command Line Interface. All of the operations except `BatchDetectDominantLanguage` use the following JSON file called `process.json` as input. For that operation the `LanguageCode` entity is not included.
The third document in the JSON file (`"$$$$$$$$"`) will cause an error during batch processing. It is included so that the operations will include an [BatchItemError](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchItemError.html) in the response.
```
{
"LanguageCode": "en",
"TextList": [
"I have been living in Seattle for almost 4 years",
"It is raining today in Seattle",
"$$$$$$$$"
]
}
```
The examples are formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
**Topics**
+ [Detect the dominant language using a batch (AWS CLI)](#batch-dominant-language)
+ [Detect entities using a batch (AWS CLI)](#batch-entities)
+ [Detect key phrases using a batch (AWS CLI)](#batch-key-phrase)
+ [Detect sentiment using a batch (AWS CLI)](#batch-sentiment)
#### Detect the dominant language using a batch (AWS CLI)
The [BatchDetectDominantLanguage](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectDominantLanguage.html) operation determines the dominant language of each document in a batch. For a list of the languages that Amazon Comprehend can detect, see [Dominant language](how-languages.md). The following AWS CLI command calls the `BatchDetectDominantLanguage` operation.
```
aws comprehend batch-detect-dominant-language \
--endpoint endpoint \
--region region \
--cli-input-json file://path to input file/process.json
```
The following is the response from the `BatchDetectDominantLanguage` operation:
```
{
"ResultList": [
{
"Index": 0,
"Languages":[
{
"LanguageCode":"en",
"Score": 0.99
}
]
},
{
"Index": 1
"Languages":[
{
"LanguageCode":"en",
"Score": 0.82
}
]
}
],
"ErrorList": [
{
"Index": 2,
"ErrorCode": "InternalServerException",
"ErrorMessage": "Unexpected Server Error. Please try again."
}
]
}
```
#### Detect entities using a batch (AWS CLI)
Use the [BatchDetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectEntities.html) operation to find the entities present in a batch of documents. For more information about entities, see [Entities](how-entities.md). The following AWS CLI command calls the `BatchDetectEntities` operation.
```
aws comprehend batch-detect-entities \
--endpoint endpoint \
--region region \
--cli-input-json file://path to input file/process.json
```
#### Detect key phrases using a batch (AWS CLI)
The [BatchDetectKeyPhrases](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectKeyPhrases.html) operation returns the key noun phrases in a batch of documents. The following AWS CLI command calls the `BatchDetectKeyNounPhrases` operation.
```
aws comprehend batch-detect-key-phrases
--endpoint endpoint
--region region
--cli-input-json file://path to input file/process.json
```
#### Detect sentiment using a batch (AWS CLI)
Detect the overall sentiment of a batch of documents using the [BatchDetectSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectSentiment.html) operation. The following AWS CLI command calls the `BatchDetectSentiment` operation.
```
aws comprehend batch-detect-sentiment \
--endpoint endpoint \
--region region \
--cli-input-json file://path to input file/process.json
```
### Batch processing with the AWS SDK for .NET
The following sample program shows how to use the [BatchDetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectEntities.html) operation with the SDK for .NET. The response from the server contains a [BatchDetectEntitiesItemResult](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_BatchDetectEntitiesItemResult.html) object for each document that was successfully processed. If there is an error processing a document, there will be a record in the error list in the response. The example gets each of the documents with an error and resends them.
The .NET example in this section uses the [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/welcome.html). You can use the [AWS Toolkit for Visual Studio](https://docs.aws.amazon.com/AWSToolkitVS/latest/UserGuide/welcome.html) to develop AWS applications using .NET. It includes helpful templates and the AWS Explorer for deploying applications and managing services. For a .NET developer perspective of AWS, see the [AWS guide for .NET developers](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/welcome.html).
```
using System;
using System.Collections.Generic;
using Amazon.Comprehend;
using Amazon.Comprehend.Model;
namespace Comprehend
{
class Program
{
// Helper method for printing properties
static private void PrintEntity(Entity entity)
{
Console.WriteLine(" Text: {0}, Type: {1}, Score: {2}, BeginOffset: {3} EndOffset: {4}",
entity.Text, entity.Type, entity.Score, entity.BeginOffset, entity.EndOffset);
}
static void Main(string[] args)
{
AmazonComprehendClient comprehendClient = new AmazonComprehendClient(Amazon.RegionEndpoint.USWest2);
List textList = new List()
{
{ "I love Seattle" },
{ "Today is Sunday" },
{ "Tomorrow is Monday" },
{ "I love Seattle" }
};
// Call detectEntities API
Console.WriteLine("Calling BatchDetectEntities");
BatchDetectEntitiesRequest batchDetectEntitiesRequest = new BatchDetectEntitiesRequest()
{
TextList = textList,
LanguageCode = "en"
};
BatchDetectEntitiesResponse batchDetectEntitiesResponse = comprehendClient.BatchDetectEntities(batchDetectEntitiesRequest);
foreach (BatchDetectEntitiesItemResult item in batchDetectEntitiesResponse.ResultList)
{
Console.WriteLine("Entities in {0}:", textList[item.Index]);
foreach (Entity entity in item.Entities)
PrintEntity(entity);
}
// check if we need to retry failed requests
if (batchDetectEntitiesResponse.ErrorList.Count != 0)
{
Console.WriteLine("Retrying Failed Requests");
List textToRetry = new List();
foreach(BatchItemError errorItem in batchDetectEntitiesResponse.ErrorList)
textToRetry.Add(textList[errorItem.Index]);
batchDetectEntitiesRequest = new BatchDetectEntitiesRequest()
{
TextList = textToRetry,
LanguageCode = "en"
};
batchDetectEntitiesResponse = comprehendClient.BatchDetectEntities(batchDetectEntitiesRequest);
foreach(BatchDetectEntitiesItemResult item in batchDetectEntitiesResponse.ResultList)
{
Console.WriteLine("Entities in {0}:", textList[item.Index]);
foreach (Entity entity in item.Entities)
PrintEntity(entity);
}
}
Console.WriteLine("End of DetectEntities");
}
}
}
```
# Async analysis jobs using the API
The following examples use the Amazon Comprehend asynchronous APIs to create and manage analysis jobs, using the AWS CLI.
**Topics**
+ [Async analysis for Amazon Comprehend insights](api-async-insights.md)
+ [Async analysis for targeted sentiment](using-api-targeted-sentiment.md)
+ [Async analysis for event detection](get-started-api-events.md)
+ [Async analysis for topic modeling](get-started-topics.md)
# Async analysis for Amazon Comprehend insights
The following sections use the Amazon Comprehend API to run asynchronous operations to analyze Amazon Comprehend insights.
**Topics**
+ [Prerequisites](#detect-topics-role-auth)
+ [Starting an analysis job](#how-start-job)
+ [Monitoring analysis jobs](#how-monitor-progress)
+ [Getting analysis results](#how-get-results)
## Prerequisites
Documents must be in UTF-8-formatted text files. You can submit your documents in two formats. The format you use depends on the type of documents you want to analyze, as described in the following table.
| Description | Format |
| --- | --- |
| Each file contains one input document. This is best for collections of large documents. | One document per file |
| The input is one or more files. Each line in a file is considered a document. This is best for short documents, such as social media postings. Each line must end with a line feed (LF, \$1n), a carriage return (CR, \$1r), or both (CRLF, \$1r\$1n). You can't use the UTF-8 line separator (u\$12028) to end a line. | One document per line |
When you start an analysis job, you specify the S3 location for your input data. The URI must be in the same AWS Region as the API endpoint that you are calling. The URI can point to a single file or it can be the prefix for a collection of data files. For more information, see the [InputDataConfig](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html) data type.
You must grant Amazon Comprehend access to the Amazon S3 bucket that contains your document collection and output files. For more information, see [Role-based permissions required for asynchronous operations](security_iam_id-based-policy-examples.md#auth-role-permissions).
## Starting an analysis job
To submit an analysis job, use either the Amazon Comprehend console or the appropriate `Start*` operation:
+ [StartDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDominantLanguageDetectionJob.html) — Start a job to detect the dominant language in each document in the collection. For more information about the dominant language in a document, see [Dominant language](how-languages.md).
+ [StartEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEntitiesDetectionJob.html) — Start a job to detect entities in each document in the collection. For more information about entities, see [Entities](how-entities.md).
+ [StartKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartKeyPhrasesDetectionJob.html) — Start a job to detect key phrases in each document in the collection. For more information about key phrases, see [Key phrases](how-key-phrases.md).
+ [StartPiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartPiiEntitiesDetectionJob.html) — Start a job to detect personally identifiable information (PII) in each document in the collection. For more information about PII, see [Detecting PII entities](how-key-phrases.md).
+ [StartSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartSentimentDetectionJob.html) — Start a job to detect the sentiment in each document in the collection. For more information about sentiments, see [Sentiment](how-sentiment.md).
## Monitoring analysis jobs
The `Start*` operation returns an ID that you can use to monitor the job's progress.
To monitor progress using the API, you use one of two operations, depending on whether you want to monitor the progress of an individual job or multiple jobs.
To monitor the progress of an individual analysis job, use the `Describe*` operations. You provide the job ID returned by the `Start*` operation. The response from the `Describe*` operation contains the `JobStatus` field with the job's status.
To monitor the progress of multiple analysis jobs, use the `List*` operations. `List*` operations return a list of jobs that you submitted to Amazon Comprehend. The response includes a `JobStatus` field for each job that tells you the status of the job.
If the status field is set to `COMPLETED` or `FAILED`, job processing has completed.
To get the status of individual jobs, use the `Describe*` operation for the analysis that you are performing.
+ [DescribeDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeDominantLanguageDetectionJob.html)
+ [DescribeEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEntitiesDetectionJob.html)
+ [DescribeKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeKeyPhrasesDetectionJob.html)
+ [DescribePiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribePiiEntitiesDetectionJob.html)
+ [DescribeSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeSentimentDetectionJob.html)
To get the status of a multiple jobs, use the `List*` operation for the analysis that you are performing.
+ [ListDominantLanguageDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListDominantLanguageDetectionJobs.html)
+ [ListEntitiesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListEntitiesDetectionJobs.html)
+ [ListKeyPhrasesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListKeyPhrasesDetectionJobs.html)
+ [ListPiiEntitiesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListPiiEntitiesDetectionJobs.html)
+ [ListSentimentDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListSentimentDetectionJobs.html)
To restrict the results to jobs that match certain criteria, use the `List*` operations' `Filter` parameter. You can filter on the job name, the job status, and the date and time that the job was submitted. For more information, see the `Filter` parameter for each of the `List*` operations in the Amazon Comprehend API reference.
## Getting analysis results
After an analysis job has finished, use a `Describe*` operation to get the location of the results. If the job status is `COMPLETED`, the response includes an `OutputDataConfig` field that contains a field with the Amazon S3 location of the output file. The file, `output.tar.gz`, is a compressed archive that contains the results of the analysis.
If the status of a job is `FAILED`, the response contains a `Message` field that describes the reason that the analysis job didn't complete successfully.
To get the status of individual jobs, use the appropriate `Describe*` operation:
+ [DescribeDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeDominantLanguageDetectionJob.html)
+ [DescribeEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEntitiesDetectionJob.html)
+ [DescribeKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeKeyPhrasesDetectionJob.html)
+ [DescribeSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeSentimentDetectionJob.html)
The results are returned in a single file, with one JSON structure for each document. Each response file also includes error messages for any job with the status field set to `FAILED`.
Each of the following sections shows examples of output for the two input formats.
### Getting dominant language detection results
The following is an example of an output file from an analysis that detected the dominant language. The format of the input is one document per line. For more information, see the [DetectDominantLanguage](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectDominantLanguage.html) operation.
```
{"File": "0_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9514502286911011}, {"LanguageCode": "de", "Score": 0.02374090999364853}, {"LanguageCode": "nl", "Score": 0.003208699868991971}, "Line": 0}
{"File": "1_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9822712540626526}, {"LanguageCode": "de", "Score": 0.002621392020955682}, {"LanguageCode": "es", "Score": 0.002386554144322872}], "Line": 1}
```
The following is an example of output from an analysis where the format of the input is one document per file:
```
{"File": "small_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9728053212165833}, {"LanguageCode": "de", "Score": 0.007670710328966379}, {"LanguageCode": "es", "Score": 0.0028472368139773607}]}
{"File": "huge_doc", "Languages": [{"LanguageCode": "en", "Score": 0.984955906867981}, {"LanguageCode": "de", "Score": 0.0026436643674969673}, {"LanguageCode": "fr", "Score": 0.0014206881169229746}]}
```
### Getting entity detection results
The following is an example of an output file from an analysis that detected entities in documents. The format of the input is one document per line. For more information, see the [DetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectEntities.html) operation. The output contains two error messages, one for a document that is too long and one for a document that isn't in UTF-8 format.
```
{"File": "50_docs", "Line": 0, "Entities": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.9763959646224976, "Text": "Cluj-NapocaCluj-Napoca", "Type": "LOCATION"}"]}
{"File": "50_docs", "Line": 1, "Entities": [{"BeginOffset": 11, "EndOffset": 15, "Score": 0.9615424871444702, "Text": "Maat", "Type": "PERSON"}}]}
{"File": "50_docs", "Line": 2, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds maximum size limit 102400 bytes."}
{"File": "50_docs", "Line": 3, "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent lines are ignored."}
```
The following is an example of output from an analysis where the format of the input is one document per file. The output contains two error messages, one for a document that is too long and one for a document that isn't in UTF-8 format.
```
{"File": "non_utf8.txt", "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent line are ignored."}
{"File": "small_doc", "Entities": [{"BeginOffset": 0, "EndOffset": 4, "Score": 0.645766019821167, "Text": "Maat", "Type": "PERSON"}]}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds size limit 102400 bytes."}
```
### Getting key phrase detection results
The following is an example of an output file from an analysis that detected key phrases in a document. The format of the input is one document per line. For more information, see the [DetectKeyPhrases](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectKeyPhrases.html) operation.
```
{"File": "50_docs", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}], "Line": 0}
```
The following is an example of the output from an analysis where the format of the input is one document per file.
```
{"File": "1_doc", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}]}
```
### Getting personally identifiable information (PII) detection results
The following is an example an output file from an analysis job that detected PII entities in documents. The format of the input is one document per line.
```
{"Entities":[{"Type":"NAME","BeginOffset":40,"EndOffset":69,"Score":0.999995},{"Type":"ADDRESS","BeginOffset":247,"EndOffset":253,"Score":0.998828},{"Type":"BANK_ACCOUNT_NUMBER","BeginOffset":406,"EndOffset":411,"Score":0.693283}],"File":"doc.txt","Line":0}
{"Entities":[{"Type":"SSN","BeginOffset":1114,"EndOffset":1124,"Score":0.999999},{"Type":"EMAIL","BeginOffset":3742,"EndOffset":3775,"Score":0.999993},{"Type":"PIN","BeginOffset":4098,"EndOffset":4102,"Score":0.999995}],"File":"doc.txt","Line":1}
```
The following is an example of output from an analysis where the format of the input is one document per file.
```
{"Entities":[{"Type":"NAME","BeginOffset":40,"EndOffset":69,"Score":0.999995},{"Type":"ADDRESS","BeginOffset":247,"EndOffset":253,"Score":0.998828},{"Type":"BANK_ROUTING","BeginOffset":279,"EndOffset":289,"Score":0.999999}],"File":"doc.txt"}
```
### Getting sentiment detection results
The following is an example of an output file from an analysis that detected the sentiment expressed in a document. It includes an error message because one document is too long. The format of the input is one document per line. For more information, see the [DetectSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectSentiment.html) operation.
```
{"File": "50_docs", "Line": 0, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.002734508365392685, "Negative": 0.008935936726629734, "Neutral": 0.9841893315315247, "Positive": 0.004140198230743408}}
{"File": "50_docs", "Line": 1, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeded maximum size limit 5120 bytes."}
{"File": "50_docs", "Line": 2, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023119584657251835, "Negative": 0.0029857370536774397, "Neutral": 0.9866572022438049, "Positive": 0.008045154623687267}}
```
The following is an example of the output from an analysis where the format of the input is one document per file.
```
{"File": "small_doc", "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023450672160834074, "Negative": 0.0009663937962614, "Neutral": 0.9795311689376831, "Positive": 0.017157377675175667}}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeds the limit of 5120 bytes."}
```
# Async analysis for targeted sentiment
For information about real-time analysis for Targeted sentiment, see [Real-time analysis for targeted sentiment](using-api-sync.md#get-started-api-targeted-sentiment).
Amazon Comprehend provides the following API operations to start and manage asynchronous targeted sentiment analysis:
+ [StartTargetedSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartTargetedSentimentDetectionJob.html) – Starts an asynchronous targeted sentiment detection job for a collection of documents.
+ [ListTargetedSentimentDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListTargetedSentimentDetectionJobs.html) – Returns the list of targeted sentiment detection jobs that you have submitted.
+ [DescribeTargetedSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeTargetedSentimentDetectionJob.html) – Gets the properties (including status) associated with the specified targeted sentiment detection job.
+ [StopTargetedSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StopTargetedSentimentDetectionJob.html) – Stops the specified in-progress targeted sentiment job.
**Topics**
+ [Before you start](#api-targeted-sentiment-before)
+ [Analyzing targeted sentiment using the AWS CLI](#api-targeted-sentiment-cli)
## Before you start
Before you start, make sure that you have:
+ **Input and output buckets**—Identify the Amazon S3 buckets that you want to use for input and output. The buckets must be in the same Region as the API that you are calling.
+ **IAM service role**—You must have an IAM service role with permission to access your input and output buckets. For more information, see [Role-based permissions required for asynchronous operations](security_iam_id-based-policy-examples.md#auth-role-permissions).
## Analyzing targeted sentiment using the AWS CLI
The following example demonstrates using the `StartTargetedSentimentDetectionJob` operation with the AWS CLI. This example specifies the language of the input text.
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend start-targeted-sentiment-detection-job \
--job-name "job name" \
--language-code "en" \
--cli-input-json file://path to JSON input file
```
For the `cli-input-json` parameter you supply the path to a JSON file that contains the request data, as shown in the following example.
```
{
"InputDataConfig": {
"S3Uri": "s3://input bucket/input path",
"InputFormat": "ONE_DOC_PER_FILE"
},
"OutputDataConfig": {
"S3Uri": "s3://output bucket/output path"
},
"DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role"
}
```
If the request to start the job was successful, you will receive the following response:
```
{
"JobStatus": "SUBMITTED",
"JobArn": "job ARN"
"JobId": "job ID"
}
```
# Async analysis for event detection
**Topics**
+ [Before you start](#events-before)
+ [Detect events using the AWS CLI](#events-cli)
+ [List events using the AWS CLI](#list-events)
+ [Describe events using the AWS CLI](#describe-events)
+ [Get events detection results](#async-events)
To detect events in a document set, use the [StartEventsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEventsDetectionJob.html) to start an asynchronous job.
## Before you start
Before you start, make sure that you have:
+ **Input and output buckets**—Identify the Amazon S3 buckets that you want to use for input and output. The buckets must be in the same Region as the API that you are calling.
+ **IAM service role**—You must have an IAM service role with permission to access your input and output buckets. For more information, see [Role-based permissions required for asynchronous operations](security_iam_id-based-policy-examples.md#auth-role-permissions).
## Detect events using the AWS CLI
The following example demonstrates using the [StartEventsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEventsDetectionJob.html) operation with the AWS CLI
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend start-events-detection-job \
--region region \
--job-name job name \
--cli-input-json file://path to JSON input file
```
For the `cli-input-json` parameter you supply the path to a JSON file that contains the request data, as shown in the following example.
```
{
"InputDataConfig": {
"S3Uri": "s3://input bucket/input path",
"InputFormat": "ONE_DOC_PER_LINE"
},
"OutputDataConfig": {
"S3Uri": "s3://output bucket/output path"
},
"DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role"
"LanguageCode": "en",
"TargetEventTypes": [
"BANKRUPTCY",
"EMPLOYMENT",
"CORPORATE_ACQUISITION",
"INVESTMENT_GENERAL",
"CORPORATE_MERGER",
"IPO",
"RIGHTS_ISSUE",
"SECONDARY_OFFERING",
"SHELF_OFFERING",
"TENDER_OFFERING",
"STOCK_SPLIT"
]
}
```
If the request to start the events detection job was successful, you will receive the following response:
```
{
"JobStatus": "SUBMITTED",
"JobId": "job ID"
}
```
## List events using the AWS CLI
Use the [ListEventsDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListEventsDetectionJobs.html) operation to see a list of the events detection jobs that you have submitted. The list includes information about the input and output locations that you used and the status of each of the detection jobs. The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend list-events-detection-jobs --region region
```
You will get JSON similar to the following in response:
```
{
"EventsDetectionJobPropertiesList": [
{
"DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role",
"EndTime": timestamp,
"InputDataConfig": {
"InputFormat": "ONE_DOC_PER_LINE",
"S3Uri": "s3://input bucket/input path"
},
"JobId": "job ID",
"JobName": "job name",
"JobStatus": "COMPLETED",
"LanguageCode": "en",
"Message": "message",
"OutputDataConfig": {
"S3Uri": "s3://output bucket/ouput path"
},
"SubmitTime": timestamp,
"TargetEventTypes": [
"BANKRUPTCY",
"EMPLOYMENT",
"CORPORATE_ACQUISITION",
"INVESTMENT_GENERAL",
"CORPORATE_MERGER",
"IPO",
"RIGHTS_ISSUE",
"SECONDARY_OFFERING",
"SHELF_OFFERING",
"TENDER_OFFERING",
"STOCK_SPLIT"
]
}
],
"NextToken": "next token"
}
```
## Describe events using the AWS CLI
You can use the [DescribeEventsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEventsDetectionJob.html) operation to get the status of an existing job. The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend describe-events-detection-job \
--region region \
--job-id job ID
```
You will get the following JSON in response:
```
{
"EventsDetectionJobProperties": {
"DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role",
"EndTime": timestamp,
"InputDataConfig": {
"InputFormat": "ONE_DOC_PER_LINE",
"S3Uri": "S3Uri": "s3://input bucket/input path"
},
"JobId": "job ID",
"JobName": "job name",
"JobStatus": "job status",
"LanguageCode": "en",
"Message": "message",
"OutputDataConfig": {
"S3Uri": "s3://output bucket/output path"
},
"SubmitTime": timestamp,
"TargetEventTypes": [
"BANKRUPTCY",
"EMPLOYMENT",
"CORPORATE_ACQUISITION",
"INVESTMENT_GENERAL",
"CORPORATE_MERGER",
"IPO",
"RIGHTS_ISSUE",
"SECONDARY_OFFERING",
"SHELF_OFFERING",
"TENDER_OFFERING",
"STOCK_SPLIT"
]
}
}
```
## Get events detection results
The following is an example an output file from an analysis job that detected events in documents. The format of the input is one document per line.
```
{"Entities": [{"Mentions": [{"BeginOffset": 12, "EndOffset": 27, "GroupScore": 1.0, "Score": 0.916355, "Text": "over a year ago", "Type": "DATE"}]}, {"Mentions": [{"BeginOffset": 33, "EndOffset": 39, "GroupScore": 1.0, "Score": 0.996603, "Text": "Amazon", "Type": "ORGANIZATION"}]}, {"Mentions": [{"BeginOffset": 66, "EndOffset": 77, "GroupScore": 1.0, "Score": 0.999283, "Text": "Whole Foods", "Type": "ORGANIZATION"}]}], "Events": [{"Arguments": [{"EntityIndex": 2, "Role": "INVESTEE", "Score": 0.999283}, {"EntityIndex": 0, "Role": "DATE", "Score": 0.916355}, {"EntityIndex": 1, "Role": "INVESTOR", "Score": 0.996603}], "Triggers": [{"BeginOffset": 373, "EndOffset": 380, "GroupScore": 0.999984, "Score": 0.999955, "Text": "acquire", "Type": "CORPORATE_ACQUISITION"}], "Type": "CORPORATE_ACQUISITION"}, {"Arguments": [{"EntityIndex": 2, "Role": "PARTICIPANT", "Score": 0.999283}], "Triggers": [{"BeginOffset": 115, "EndOffset": 123, "GroupScore": 1.0, "Score": 0.999967, "Text": "combined", "Type": "CORPORATE_MERGER"}], "Type": "CORPORATE_MERGER"}], "File": "doc.txt", "Line": 0}
```
For more information about events output file structure and supported event types, see [Events](how-events.md).
# Async analysis for topic modeling
To determine the topics in a document set, use the [StartTopicsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartTopicsDetectionJob.html) to start an asynchronous job. You can monitor topics in documents written in English or Spanish.
**Topics**
+ [Before you start](#topics-before)
+ [Using the AWS Command Line Interface](#topics-cli)
+ [Using the SDK for Python or SDK for .NET](#topic-java)
## Before you start
Before you start, make sure that you have:
+ **Input and output buckets**—Identify the Amazon S3 buckets that you want to use for input and output. The buckets must be in the same Region as the API that you are calling.
+ **IAM service role**—You must have an IAM service role with permission to access your input and output buckets. For more information, see [Role-based permissions required for asynchronous operations](security_iam_id-based-policy-examples.md#auth-role-permissions).
## Using the AWS Command Line Interface
The following example demonstrates using the `StartTopicsDetectionJob` operation with the AWS CLI
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend start-topics-detection-job \
--number-of-topics topics to return \
--job-name "job name" \
--region region \
--cli-input-json file://path to JSON input file
```
For the `cli-input-json` parameter you supply the path to a JSON file that contains the request data, as shown in the following example.
```
{
"InputDataConfig": {
"S3Uri": "s3://input bucket/input path",
"InputFormat": "ONE_DOC_PER_FILE"
},
"OutputDataConfig": {
"S3Uri": "s3://output bucket/output path"
},
"DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role"
}
```
If the request to start the topic detection job was successful, you will receive the following response:
```
{
"JobStatus": "SUBMITTED",
"JobId": "job ID"
}
```
Use the [ListTopicsDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListTopicsDetectionJobs.html) operation to see a list of the topic detection jobs that you have submitted. The list includes information about the input and output locations that you used and the status of each of the detection jobs. The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend list-topics-detection-jobs \-- region
```
You will get JSON similar to the following in response:
```
{
"TopicsDetectionJobPropertiesList": [
{
"InputDataConfig": {
"S3Uri": "s3://input bucket/input path",
"InputFormat": "ONE_DOC_PER_LINE"
},
"NumberOfTopics": topics to return,
"JobId": "job ID",
"JobStatus": "COMPLETED",
"JobName": "job name",
"SubmitTime": timestamp,
"OutputDataConfig": {
"S3Uri": "s3://output bucket/output path"
},
"EndTime": timestamp
},
{
"InputDataConfig": {
"S3Uri": "s3://input bucket/input path",
"InputFormat": "ONE_DOC_PER_LINE"
},
"NumberOfTopics": topics to return,
"JobId": "job ID",
"JobStatus": "RUNNING",
"JobName": "job name",
"SubmitTime": timestamp,
"OutputDataConfig": {
"S3Uri": "s3://output bucket/output path"
}
}
]
}
```
You can use the [DescribeTopicsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeTopicsDetectionJob.html) operation to get the status of an existing job. The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).
```
aws comprehend describe-topics-detection-job --job-id job ID
```
You will get the following JSON in response:
```
{
"TopicsDetectionJobProperties": {
"InputDataConfig": {
"S3Uri": "s3://input bucket/input path",
"InputFormat": "ONE_DOC_PER_LINE"
},
"NumberOfTopics": topics to return,
"JobId": "job ID",
"JobStatus": "COMPLETED",
"JobName": "job name",
"SubmitTime": timestamp,
"OutputDataConfig": {
"S3Uri": "s3://output bucket/ouput path"
},
"EndTime": timestamp
}
}
```
## Using the SDK for Python or SDK for .NET
For SDK examples of how to start a topic modeling job, see [Use `StartTopicsDetectionJob` with an AWS SDK or CLI](example_comprehend_StartTopicsDetectionJob_section.md).