Entity & Key Phrase Extraction

Q: What entity types does DetectEntities recognize out of the box?

Built-in types include PERSON, LOCATION, ORGANIZATION, COMMERCIAL_ITEM, EVENT, DATE, QUANTITY, TITLE, and OTHER. For types outside this list, train a Comprehend Custom entity recognizer.

Q: Do key phrases have a category like entities do?

No. DetectKeyPhrases returns text, score, and offsets only - it identifies meaningful noun phrases without assigning a type.

Q: How do I get the exact matched text back from an offset?

Slice the original string with BeginOffset and EndOffset - text[begin:end] in Python or text.slice(begin, end) in TypeScript - using the exact string you sent to Comprehend.

Q: Is there a bulk version of these calls?

Yes - StartEntitiesDetectionJob and StartKeyPhrasesDetectionJob run the same models asynchronously over an S3 prefix of documents instead of one string at a time.

Unstructured text carries structured information: who is mentioned, what organization, what date, what the passage is actually about. DetectEntities and DetectKeyPhrases pull that structure out without a custom model or any training step.

This page covers both operations, how their outputs relate, and the offset-based design that lets you map results back onto the original text - for highlighting, indexing, or feeding into a downstream pipeline.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
entities = comprehend.detect_entities(
    Text="Acme Corp announced a partnership with Nova Labs in Austin.",
    LanguageCode="en",
)["Entities"]
phrases = comprehend.detect_key_phrases(
    Text="Acme Corp announced a partnership with Nova Labs in Austin.",
    LanguageCode="en",
)["KeyPhrases"]

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectEntitiesCommand, DetectKeyPhrasesCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Acme Corp announced a partnership with Nova Labs in Austin.";
const { Entities } = await comprehend.send(new DetectEntitiesCommand({ Text: text, LanguageCode: "en" }));
const { KeyPhrases } = await comprehend.send(new DetectKeyPhrasesCommand({ Text: text, LanguageCode: "en" }));

When to reach for this:

Tagging support tickets or articles with who/what/where without hand-written rules.
Building a lightweight search index from free text without a full NLP pipeline.
Highlighting mentioned entities or key terms in a UI over the original document.
Extracting structured fields from semi-structured text (emails, reports, transcripts).

Working Example

Run both calls, then combine the results into spans you can render or store, sorted by position in the source text.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
text = "Acme Corp announced a partnership with Nova Labs in Austin on May 1st."
 
entities = comprehend.detect_entities(Text=text, LanguageCode="en")["Entities"]
phrases = comprehend.detect_key_phrases(Text=text, LanguageCode="en")["KeyPhrases"]
 
spans = []
for e in entities:
    spans.append({"kind": "entity", "type": e["Type"], "text": e["Text"],
                  "start": e["BeginOffset"], "end": e["EndOffset"], "score": e["Score"]})
for p in phrases:
    spans.append({"kind": "phrase", "type": None, "text": p["Text"],
                  "start": p["BeginOffset"], "end": p["EndOffset"], "score": p["Score"]})
 
spans.sort(key=lambda s: s["start"])
for s in spans:
    print(s["start"], s["end"], s["kind"], s.get("type"), s["text"])

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectEntitiesCommand, DetectKeyPhrasesCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Acme Corp announced a partnership with Nova Labs in Austin on May 1st.";
 
const { Entities = [] } = await comprehend.send(new DetectEntitiesCommand({ Text: text, LanguageCode: "en" }));
const { KeyPhrases = [] } = await comprehend.send(new DetectKeyPhrasesCommand({ Text: text, LanguageCode: "en" }));
 
type Span = { kind: "entity" | "phrase"; type?: string; text: string; start: number; end: number; score: number };
 
const spans: Span[] = [
  ...Entities.map((e): Span => ({ kind: "entity", type: e.Type, text: e.Text!, start: e.BeginOffset!, end: e.EndOffset!, score: e.Score! })),
  ...KeyPhrases.map((p): Span => ({ kind: "phrase", text: p.Text!, start: p.BeginOffset!, end: p.EndOffset!, score: p.Score! })),
];
 
spans.sort((a, b) => a.start - b.start);
for (const s of spans) console.log(s.start, s.end, s.kind, s.type, s.text);

What this demonstrates:

Entities and key phrases are independent calls with independent result sets - some text can be both.
BeginOffset/EndOffset is the common contract that lets you merge results from different Detect operations.
Sorting by start gives you a single reading-order stream, useful for rendering highlights over the source text.
Nothing here mutates the input text - both calls only annotate positions within it.

Deep Dive

What DetectEntities Returns

DetectEntities scans text for spans matching built-in types: PERSON, LOCATION, ORGANIZATION, COMMERCIAL_ITEM, EVENT, DATE, QUANTITY, TITLE, and a catch-all OTHER. Each match is an object with Type, Text, Score, BeginOffset, and EndOffset. The offsets are character indices into the exact string you sent, not into any tokenized or normalized version of it - a common cause of off-by-one bugs when a document is preprocessed differently before display than before detection.

What DetectKeyPhrases Returns

DetectKeyPhrases is untyped by design - it returns KeyPhrases, each with Text, Score, BeginOffset, EndOffset, but no category. A key phrase is a noun-phrase fragment ("the quarterly earnings report") rather than a single named entity. It often overlaps with entity spans (a company name may show up as both an ORGANIZATION entity and a key phrase) but the two calls are computed independently and neither result set is derived from the other.

Combining the Two Signals

A common pattern is to use entities for typed tagging (link a PERSON match to a CRM record, an ORGANIZATION match to a company database) and key phrases for a broader "what is this about" summary or search index. Because both use the same offset contract, you can merge them into one ordered list, as in the working example, without reconciling two different coordinate systems.

Size and Language Limits

Each call operates on a single text blob with a per-call size limit (check the current service quota for your input format). For documents longer than the limit, split by paragraph or sentence boundary rather than an arbitrary character count, and keep a running offset so results from each chunk map back to positions in the original, unsplit document.

Gotchas

Treating offsets as token indices - BeginOffset/EndOffset are character positions in the exact string sent, not word or token counts. Fix: slice the original string with text[begin:end] (Python) or text.slice(begin, end) (TypeScript) to recover the match.
Re-detecting after reformatting text - if you strip whitespace, normalize unicode, or translate the text before rendering, old offsets no longer line up. Fix: run Detect on the exact string you will render, or keep a mapping between the original and transformed text.
Assuming key phrases are typed like entities - KeyPhrases has no Type field; do not expect a category. Fix: use DetectEntities when you need typed categories, DetectKeyPhrases for general topical signal.
Sending a whole large document in one call - long input either gets rejected or truncated at the service limit. Fix: chunk by paragraph and track cumulative offsets per chunk.
Dropping low-confidence matches by accident - some pipelines filter on Score but forget both entities and phrases carry it. Fix: apply a consistent minimum-score threshold across both result sets if you filter at all.
Expecting duplicate mentions to be deduplicated - the same organization name mentioned three times returns three separate entities. Fix: deduplicate downstream by normalized Text if you need unique mentions.

Alternatives

Alternative	Use When	Don't Use When
`DetectEntities` / `DetectKeyPhrases` (this page)	General text, built-in entity types are sufficient	You need domain-specific entity types the built-in model doesn't have
Comprehend Custom entity recognizer	You must recognize proprietary or domain-specific entity types	The built-in `PERSON`/`ORGANIZATION`/etc. types already cover your need
Regex / rule-based extraction	Very narrow, well-defined patterns (IDs, SKUs, fixed formats)	Free-form natural language where patterns vary
`StartEntitiesDetectionJob` / `StartKeyPhrasesDetectionJob` (batch)	Processing many documents from S3 in bulk	You need a result for one document right now

FAQs

What entity types does DetectEntities recognize out of the box?

Built-in types include PERSON, LOCATION, ORGANIZATION, COMMERCIAL_ITEM, EVENT, DATE, QUANTITY, TITLE, and OTHER. For types outside this list, train a Comprehend Custom entity recognizer.

Do key phrases have a category like entities do?

No. DetectKeyPhrases returns text, score, and offsets only - it identifies meaningful noun phrases without assigning a type.

How do I get the exact matched text back from an offset?

Slice the original string with BeginOffset and EndOffset - text[begin:end] in Python or text.slice(begin, end) in TypeScript - using the exact string you sent to Comprehend.

Can the same word show up as both an entity and a key phrase?

Yes. The two calls are independent, so overlap is normal - an organization name can appear as an ORGANIZATION entity and also within a key phrase span.

What should I do with a document longer than the size limit?

Split it by paragraph or sentence boundary, call Detect on each chunk, and keep a running offset so chunk-relative positions map back to the original document.

Is there a bulk version of these calls?

Yes - StartEntitiesDetectionJob and StartKeyPhrasesDetectionJob run the same models asynchronously over an S3 prefix of documents instead of one string at a time.

Should I filter results by Score?

It depends on your tolerance for false positives. Both entities and key phrases carry a Score; a common starting threshold is to drop matches below roughly 0.5-0.7 confidence, tuned to your data.

Comprehend Basics - the first entity and key phrase calls, side by side.
Comprehend's Managed NLP Model Surface - pretrained vs custom, real-time vs batch.
Custom Classification & Custom Entity Recognition - training entity types beyond the built-in set.
Batch vs Real-Time Comprehend Jobs - running entity/key phrase detection over many documents.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
entities = comprehend.detect_entities(
    Text="Acme Corp announced a partnership with Nova Labs in Austin.",
    LanguageCode="en",
)["Entities"]
phrases = comprehend.detect_key_phrases(
    Text="Acme Corp announced a partnership with Nova Labs in Austin.",
    LanguageCode="en",
)["KeyPhrases"]

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectEntitiesCommand, DetectKeyPhrasesCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Acme Corp announced a partnership with Nova Labs in Austin.";
const { Entities } = await comprehend.send(new DetectEntitiesCommand({ Text: text, LanguageCode: "en" }));
const { KeyPhrases } = await comprehend.send(new DetectKeyPhrasesCommand({ Text: text, LanguageCode: "en" }));

When to reach for this:

Tagging support tickets or articles with who/what/where without hand-written rules.
Building a lightweight search index from free text without a full NLP pipeline.
Highlighting mentioned entities or key terms in a UI over the original document.
Extracting structured fields from semi-structured text (emails, reports, transcripts).

Working Example

Run both calls, then combine the results into spans you can render or store, sorted by position in the source text.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
text = "Acme Corp announced a partnership with Nova Labs in Austin on May 1st."
 
entities = comprehend.detect_entities(Text=text, LanguageCode="en")["Entities"]
phrases = comprehend.detect_key_phrases(Text=text, LanguageCode="en")["KeyPhrases"]
 
spans = []
for e in entities:
    spans.append({"kind": "entity", "type": e["Type"], "text": e["Text"],
                  "start": e["BeginOffset"], "end": e["EndOffset"], "score": e["Score"]})
for p in phrases:
    spans.append({"kind": "phrase", "type": None, "text": p["Text"],
                  "start": p["BeginOffset"], "end": p["EndOffset"], "score": p["Score"]})
 
spans.sort(key=lambda s: s["start"])
for s in spans:
    print(s["start"], s["end"], s["kind"], s.get("type"), s["text"])

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectEntitiesCommand, DetectKeyPhrasesCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Acme Corp announced a partnership with Nova Labs in Austin on May 1st.";
 
const { Entities = [] } = await comprehend.send(new DetectEntitiesCommand({ Text: text, LanguageCode: "en" }));
const { KeyPhrases = [] } = await comprehend.send(new DetectKeyPhrasesCommand({ Text: text, LanguageCode: "en" }));
 
type Span = { kind: "entity" | "phrase"; type?: string; text: string; start: number; end: number; score: number };
 
const spans: Span[] = [
  ...Entities.map((e): Span => ({ kind: "entity", type: e.Type, text: e.Text!, start: e.BeginOffset!, end: e.EndOffset!, score: e.Score! })),
  ...KeyPhrases.map((p): Span => ({ kind: "phrase", text: p.Text!, start: p.BeginOffset!, end: p.EndOffset!, score: p.Score! })),
];
 
spans.sort((a, b) => a.start - b.start);
for (const s of spans) console.log(s.start, s.end, s.kind, s.type, s.text);

What this demonstrates:

Entities and key phrases are independent calls with independent result sets - some text can be both.
BeginOffset/EndOffset is the common contract that lets you merge results from different Detect operations.
Sorting by start gives you a single reading-order stream, useful for rendering highlights over the source text.
Nothing here mutates the input text - both calls only annotate positions within it.

Deep Dive

What DetectEntities Returns

What DetectKeyPhrases Returns

Combining the Two Signals

Size and Language Limits

Gotchas

Treating offsets as token indices - BeginOffset/EndOffset are character positions in the exact string sent, not word or token counts. Fix: slice the original string with text[begin:end] (Python) or text.slice(begin, end) (TypeScript) to recover the match.
Re-detecting after reformatting text - if you strip whitespace, normalize unicode, or translate the text before rendering, old offsets no longer line up. Fix: run Detect on the exact string you will render, or keep a mapping between the original and transformed text.
Assuming key phrases are typed like entities - KeyPhrases has no Type field; do not expect a category. Fix: use DetectEntities when you need typed categories, DetectKeyPhrases for general topical signal.
Sending a whole large document in one call - long input either gets rejected or truncated at the service limit. Fix: chunk by paragraph and track cumulative offsets per chunk.
Dropping low-confidence matches by accident - some pipelines filter on Score but forget both entities and phrases carry it. Fix: apply a consistent minimum-score threshold across both result sets if you filter at all.
Expecting duplicate mentions to be deduplicated - the same organization name mentioned three times returns three separate entities. Fix: deduplicate downstream by normalized Text if you need unique mentions.

Alternatives

Alternative	Use When	Don't Use When
`DetectEntities` / `DetectKeyPhrases` (this page)	General text, built-in entity types are sufficient	You need domain-specific entity types the built-in model doesn't have
Comprehend Custom entity recognizer	You must recognize proprietary or domain-specific entity types	The built-in `PERSON`/`ORGANIZATION`/etc. types already cover your need
Regex / rule-based extraction	Very narrow, well-defined patterns (IDs, SKUs, fixed formats)	Free-form natural language where patterns vary
`StartEntitiesDetectionJob` / `StartKeyPhrasesDetectionJob` (batch)	Processing many documents from S3 in bulk	You need a result for one document right now

FAQs

What entity types does DetectEntities recognize out of the box?

Do key phrases have a category like entities do?

No. DetectKeyPhrases returns text, score, and offsets only - it identifies meaningful noun phrases without assigning a type.

How do I get the exact matched text back from an offset?

Slice the original string with BeginOffset and EndOffset - text[begin:end] in Python or text.slice(begin, end) in TypeScript - using the exact string you sent to Comprehend.

Can the same word show up as both an entity and a key phrase?

Yes. The two calls are independent, so overlap is normal - an organization name can appear as an ORGANIZATION entity and also within a key phrase span.

What should I do with a document longer than the size limit?

Split it by paragraph or sentence boundary, call Detect on each chunk, and keep a running offset so chunk-relative positions map back to the original document.

Is there a bulk version of these calls?

Yes - StartEntitiesDetectionJob and StartKeyPhrasesDetectionJob run the same models asynchronously over an S3 prefix of documents instead of one string at a time.

Should I filter results by Score?

It depends on your tolerance for false positives. Both entities and key phrases carry a Score; a common starting threshold is to drop matches below roughly 0.5-0.7 confidence, tuned to your data.

Comprehend Basics - the first entity and key phrase calls, side by side.
Comprehend's Managed NLP Model Surface - pretrained vs custom, real-time vs batch.
Custom Classification & Custom Entity Recognition - training entity types beyond the built-in set.
Batch vs Real-Time Comprehend Jobs - running entity/key phrase detection over many documents.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Entity & Key Phrase Extraction

Search Documentation

Entity & Key Phrase Extraction