Text API: Entity Extraction

AlchemyAPI provides easy-to-use facilities for extracting the semantic richness from any text content: Post (upload) any content directly to our service for analysis.

Posted content is analyzed to detect the primary document language, and named entities are automatically extracted. These API calls may be utilized to process posted (uploaded) text content. If you are processing content hosted on a publicly accessible website, consider using our URL processing calls instead. Or if you are processing uploaded HTML content, use our HTML API calls.

TextGetRankedNamedEntities	Extract a grouped, relevancy-ranked list of named entities from some text.
TextGetNamedEntities	Extract a non-grouped, non-ranked list of all named entities from some text.
TextGetAnnotatedNamedEntityText	Annotate text based on the named entities detected within.

API Call: TextGetRankedNamedEntities

Description: The TextGetRankedNamedEntities call is utilized to extract a grouped, ranked list of named entities (people, companies, organizations, etc.) from within a posted text document.

Endpoint: http://access.alchemyapi.com/calls/text/TextGetRankedNamedEntities

Parameters:

http argument	parameter description
apikey	your private api key (required parameter)
text	Text document content (must be uri-argument encoded) (required parameter)
url	Text document URL (optional parameter. must be uri-argument encoded)
outputMode	desired API output format Possible values: xml (default) json rdf rel-tag rel-tag-raw (optional parameter)
jsonp	desired JSONP callback (optional parameter, requires "outputMode" to be set to json)
disambiguate	whether to disambiguate detected entities. Possible values: 1 - enabled (default) 0 - disabled (optional parameter)
linkedData	whether to include Linked Data content links with disambiguated entities. Possible values: 1 - enabled (default) 0 - disabled (optional parameter. disambiguation must be enabled to utilize the linkedData feature.)
coreference	whether to resolve he/she/etc coreferences into detected entities. Possible values: 1 - enabled (default) 0 - disabled (optional parameter)
quotations	whether to enable quotations extraction. Possible values: 1 - enabled 0 - disabled (default) (optional parameter)
sentiment	whether to enable entity-level sentiment analysis. Possible values: 1 - enabled 0 - disabled (default) (optional parameter - Note that enabling this option will incur usage of one (1) additional AlchemyAPI transaction)
showSourceText	whether to include the original 'source text' the entities were extracted from within the API response. Possible values: 1 - enabled 0 - disabled (default) (optional parameter)
maxRetrieve	maximum number of named entities to extract (default: 50) (optional parameter)
baseUrl	rel-tag output base http url (optional parameter, used with rel-tag or rel-tag-raw outputMode. must be uri-argument encoded)

Response Format (XML):

<results>
    <status>REQUEST_STATUS</status>
    <language>DOCUMENT_LANGUAGE</language>
    <url>DOCUMENT_URL</url>
    <text>DOCUMENT_TEXT</text>
    <entities>
        <entity>
            <type>DETECTED_TYPE</type>
            <relevance>DETECTED_RELEVANCE</relevance>
            <count>DETECTED_COUNT</count>
            <text>DETECTED_ENTITY</text>
            <disambiguated>
                <name>DISAMBIGUATED_ENTITY</name>
                <subType>ENTITY_SUBTYPE</subType>
                <website>WEBSITE</website>
                <geo>LATITUDE LONGITUDE</geo>
                <dbpedia>LINKED_DATA_DBPEDIA</dbpedia>
                <yago>LINKED_DATA_YAGO</yago>
                <opencyc>LINKED_DATA_OPENCYC</opencyc>
                <umbel>LINKED_DATA_UMBEL</umbel>
                <freebase>LINKED_DATA_FREEBASE</freebase>
                <ciaFactbook>LINKED_DATA_FACTBOOK</ciaFactbook>
                <census>LINKED_DATA_CENSUS</census>
                <geonames>LINKED_DATA_GEONAMES</geonames>
                <musicBrainz>LINKED_DATA_MUSICBRAINZ</musicBrainz>
                <crunchbase>CRUNCHBASE_WEB_LINK</crunchbase>
                <semanticCrunchbase>LINKED_DATA_CRUNCHBASE</semanticCrunchbase>
            </disambiguated>
            <quotations>
                <quotation>ENTITY_QUOTATION</quotation>
            </quotations>
            <sentiment>
                <type>SENTIMENT_LABEL</type>
                <score>SENTIMENT_SCORE</score>
                <mixed>SENTIMENT_MIXED</mixed>
            </sentiment>
        </entity>
    </entities>
</results>

Response Format (JSON):

{
    "status": "REQUEST_STATUS",
    "language": "DOCUMENT_LANGUAGE",
    "url": "DOCUMENT_URL",
    "text": "DOCUMENT_TEXT",
    "entities": [
        "entity": {
            "type": "DETECTED_TYPE",
            "relevance": "DETECTED_RELEVANCE",
            "count": "DETECTED_COUNT",
            "text": "DETECTED_ENTITY"
            "disambiguated": {
                "name": "DISAMBIGUATED_ENTITY",
                "subType": "ENTITY_SUBTYPE",
                "website": "WEBSITE",
                "geo": "LATITUDE LONGITUDE",
                "dbpedia": "LINKED_DATA_DBPEDIA",
                "yago": "LINKED_DATA_YAGO",
                "opencyc": "LINKED_DATA_OPENCYC",
                "umbel": "LINKED_DATA_UMBEL",
                "freebase": "LINKED_DATA_FREEBASE",
                "ciaFactbook": "LINKED_DATA_FACTBOOK",
                "census": "LINKED_DATA_CENSUS",
                "geonames": "LINKED_DATA_GEONAMES",
                "musicBrainz": "LINKED_DATA_MUSICBRAINZ",
                "crunchbase": "CRUNCHBASE_WEB_LINK",
                "semanticCrunchbase": "LINKED_DATA_CRUNCHBASE"
            },
            "quotations": [
                {
                    "quotation": "ENTITY_QUOTATION"
                }
            ],
            "sentiment": {
                "type": "SENTIMENT_LABEL",
                "score": "SENTIMENT_SCORE",
                "mixed": "SENTIMENT_MIXED"
            }
        }
    ]
}

Response (RDF):

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                 xmlns:aapi="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#"
                 xml:base="http://rdf.alchemyapi.com/rdf/v1/r/response.rdf">
    <rdf:Description rdf:ID="DOCUMENT_HASH">
        <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#DocInfo"/>
        <aapi:ResultStatus>REQUEST_STATUS</aapi:ResultStatus>
        <aapi:Language>DOCUMENT_LANGUAGE</aapi:Language>
        <aapi:URL>DOCUMENT_URL</aapi:URL>
        <aapi:DocText>DOCUMENT_TEXT</aapi:DocText>
    </rdf:Description>
    <rdf:Description rdf:ID="DOCUMENT_HASH-ENTITY_NUM">
        <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#EntityOccurrences"/>
        <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
        <aapi:EntityType>DETECTED_TYPE</aapi:EntityType>
        <aapi:Relevance>DETECTED_RELEVANCE</aapi:Relevance>
        <aapi:NumOccurs>DETECTED_COUNT</aapi:NumOccurs>
        <aapi:Name>DETECTED_ENTITY</aapi:Name>
        <aapi:Disambiguation>
            <rdf:Description rdf:about="#DOCUMENT_HASH-ENTITY_NUM">
                <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#Disambiguation"/>
                <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
                <aapi:ResolvedName>DISAMBIGUATED_ENTITY</aapi:ResolvedName>
                <aapi:SubType>ENTITY_SUBTYPE</aapi:SubType>
                <aapi:URL>WEBSITE</aapi:URL>
                <aapi:Geo>LATITUDE LONGITUDE</aapi:Geo>
                <owl:sameAs rdf:resource="LINKED_DATA_DBPEDIA"/>
                <owl:sameAs rdf:resource="LINKED_DATA_YAGO"/>
                <owl:sameAs rdf:resource="LINKED_DATA_OPENCYC"/>
                <owl:sameAs rdf:resource="LINKED_DATA_UMBEL"/>
                <owl:sameAs rdf:resource="LINKED_DATA_FREEBASE"/>
                <owl:sameAs rdf:resource="LINKED_DATA_FACTBOOK"/>
                <owl:sameAs rdf:resource="LINKED_DATA_CENSUS"/>
                <owl:sameAs rdf:resource="LINKED_DATA_GEONAMES"/>
                <owl:sameAs rdf:resource="LINKED_DATA_MUSICBRAINZ"/>
                <owl:sameAs rdf:resource="LINKED_DATA_CRUNCHBASE"/>
            </rdf:Description>
        </aapi:Disambiguation>
        <aapi:Quotations>
            <rdf:Description rdf:about="#DOCUMENT_HASH-ENTITY_NUM">
                <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#Quotations"/>
                <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
                <aapi:Quotation>ENTITY_QUOTATION</aapi:Quotation>
            </rdf:Description>
        </aapi:Quotations>
        <aapi:Sentiment>
            <rdf:Description rdf:about="#DOCUMENT_HASH-ENTITY_NUM">
                <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#Sentiment"/>
                <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
                <aapi:SentimentType>SENTIMENT_LABEL</aapi:SentimentType>
                <aapi:SentimentScore>SENTIMENT_SCORE</aapi:SentimentScore>
                <aapi:SentimentMixed>SENTIMENT_MIXED</aapi:SentimentMixed>
            </rdf:Description>
        </aapi:Sentiment>
    </rdf:Description>
</rdf:RDF>

Response Format (REL-TAG Microformat [XML-embedded] ):

<results>
    <status>REQUEST_STATUS</status>
    <language>DOCUMENT_LANGUAGE</language>
    <url>REQUESTED_URL</url>
    <text>DOCUMENT_TEXT</text>
    <microformats>
        <a href="REQUESTED_BASE_URL/DETECTED_ENTITY" rel="tag">DETECTED_ENTITY</a>
        <a href="REQUESTED_BASE_URL/DETECTED_ENTITY" rel="tag">DETECTED_ENTITY</a>
    </microformats>
</results>

Response Format (REL-TAG Microformat [raw] ):

<a href="REQUESTED_BASE_URL/DETECTED_ENTITY" rel="tag">DETECTED_ENTITY</a>
<a href="REQUESTED_BASE_URL/DETECTED_ENTITY" rel="tag">DETECTED_ENTITY</a>

Response Fields:

field name

field description

status

success / failure status indicating whether the request was processed.

Possible values:
OK
ERROR

language

detected language (english, french, ..) for the submitted content.

url

http url information was requested for.

type

the detected entity type.

Possible values: (click to see list)

relevance

relevance score for a detected entity.

Possible values: (0.0 - 1.0) [1.0 = most relevant]

count

number of times an entity was seen within the source text.

text

the detected entity text.

disambiguated

disambiguation information for the detected entity (sent only if disambiguation occurred)

disambiguation field	field description
name	the disambiguated entity name.
subType	the disambiguated entity subType SubTypes expose additional ontological mappings for a detected entity, such as identification of a Person as a Politician or Athlete.
website	the disambiguated entity website.
geo	latitude longitude the disambiguated entity geographic coordinates.
dbpedia	sameAs link to DBpedia for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
yago	sameAs link to YAGO for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
opencyc	sameAs link to OpenCyc for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
umbel	sameAs link to UMBEL for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
freebase	sameAs link to Freebase for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
ciaFactbook	sameAs link to the CIA World Factbook for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
census	sameAs link to the US Census for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
geonames	sameAs link to Geonames for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
musicBrainz	sameAs link to MusicBrainz for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
crunchbase	website link to CrunchBase for the disambiguated entity. Note: Provided only for entities that exist in CrunchBase.
semanticCrunchbase	sameAs link to Semantic CrunchBase for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.

quotations

extracted quotations for the detected entity (sent only if quotations extraction is enabled)

field	field description
quotation	quotation extracted for a particular named entity.

sentiment

sentiment for the detected entity (sent only if entity-level sentiment analysis is enabled)

field	field description
type	sentiment polarity: "positive", "negative", or "neutral"
score	sentiment strength (0.0 == neutral)
mixed	whether sentiment is mixed (both positive and negative) (1 == mixed)

statusInfo

failure status information (sent only if "status" == "ERROR").

Possible values:
invalid-api-key

API Notes:

Calls to TextGetRankedNamedEntities should be made using HTTP POST.
HTTP POST calls should include the Content-Type header: application/x-www-form-urlencoded
Posted text documents can be a maximum of 150 kilobytes. Larger documents will result in a "content-exceeds-size-limit" error response.
Language detection is performed on the retrieved document before attempting named entity extraction. A minimum of 15 characters of text must exist within the requested HTTP document to perform language detection.
Documents containing less than 15 characters of text are assumed to be English-language content.
Disambiguation of detected entities is enabled by default. Disambiguation information will be included for each entity that is successfully resolved.
Entity extraction is currently supported for all languages listed on the language support page. Other non-supported language submissions will be rejected and an error response returned.
Enabling entity-level sentiment analysis results in one additional transaction utilized against your daily API limit. Entity-level sentiment analysis is currently provided for both English and German-language content.
Disambiguation and quotations extraction are currently available for English-language content only. Support for other languages is in development.

API Call: TextGetNamedEntities

Description: The TextGetNamedEntities call is utilized to extract named entities (people, companies, organizations, etc.) from within a posted text document.

Endpoint: http://access.alchemyapi.com/calls/text/TextGetNamedEntities

Parameters:

http argument	parameter description
apikey	your private api key (required parameter)
text	Text document content (must be uri-argument encoded) (required parameter)
url	Text document URL (optional parameter. must be uri-argument encoded)
outputMode	desired API output format Possible values: xml (default) json rdf (optional parameter)
disambiguate	whether to disambiguate detected entities. Possible values: 1 - enabled (default) 0 - disabled (optional parameter)
linkedData	whether to include Linked Data content links with disambiguated entities. Possible values: 1 - enabled (default) 0 - disabled (optional parameter. disambiguation must be enabled to utilize the linkedData feature.)
coreference	whether to resolve he/she/etc coreferences into detected entities. Possible values: 1 - enabled (default) 0 - disabled (optional parameter)
quotations	whether to enable quotations extraction. Possible values: 1 - enabled 0 - disabled (default) (optional parameter)
showSourceText	whether to include the original 'source text' the entities were extracted from within the API response. Possible values: 1 - enabled 0 - disabled (default) (optional parameter)

Response Format (XML):

<results>
    <status>REQUEST_STATUS</status>
    <language>DOCUMENT_LANGUAGE</language>
    <url>DOCUMENT_URL</url>
    <text>DOCUMENT_TEXT</text>
    <entities>
        <entity>
            <type>DETECTED_TYPE</type>
            <start>START_POS</start>
            <end>END_POS</end>
            <text>DETECTED_ENTITY</text>
            <disambiguated>
                <name>DISAMBIGUATED_ENTITY</name>
                <subType>ENTITY_SUBTYPE</subType>
                <website>WEBSITE</website>
                <geo>LATITUDE LONGITUDE</geo>
                <dbpedia>LINKED_DATA_DBPEDIA</dbpedia>
                <yago>LINKED_DATA_YAGO</yago>
                <opencyc>LINKED_DATA_OPENCYC</opencyc>
                <umbel>LINKED_DATA_UMBEL</umbel>
                <freebase>LINKED_DATA_FREEBASE</freebase>
                <ciaFactbook>LINKED_DATA_FACTBOOK</ciaFactbook>
                <census>LINKED_DATA_CENSUS</census>
                <geonames>LINKED_DATA_GEONAMES</geonames>
                <musicBrainz>LINKED_DATA_MUSICBRAINZ</musicBrainz>
                <crunchbase>CRUNCHBASE_WEB_LINK</crunchbase>
                <semanticCrunchbase>LINKED_DATA_CRUNCHBASE</semanticCrunchbase>
            </disambiguated>
            <quotations>
                <quotation>ENTITY_QUOTATION</quotation>
            </quotations>
        </entity>
    </entities>
</results>

Response Format (JSON):

{
    "status": "REQUEST_STATUS",
    "language": "DOCUMENT_LANGUAGE",
    "url": "DOCUMENT_URL",
    "text": "DOCUMENT_TEXT",
    "entities": [
        "entity": {
            "type": "DETECTED_TYPE",
            "start": "START_POS",
            "end": "END_POS",
            "text": "DETECTED_ENTITY"
            "disambiguated": {
                "name": "DISAMBIGUATED_ENTITY",
                "subType": "ENTITY_SUBTYPE",
                "website": "WEBSITE",
                "geo": "LATITUDE LONGITUDE",
                "dbpedia": "LINKED_DATA_DBPEDIA",
                "yago": "LINKED_DATA_YAGO",
                "opencyc": "LINKED_DATA_OPENCYC",
                "umbel": "LINKED_DATA_UMBEL",
                "freebase": "LINKED_DATA_FREEBASE",
                "ciaFactbook": "LINKED_DATA_FACTBOOK",
                "census": "LINKED_DATA_CENSUS",
                "geonames": "LINKED_DATA_GEONAMES",
                "musicBrainz": "LINKED_DATA_MUSICBRAINZ",
                "crunchbase": "CRUNCHBASE_WEB_LINK",
                "semanticCrunchbase": "LINKED_DATA_CRUNCHBASE"
            },
            "quotations": [
                {
                    "quotation": "ENTITY_QUOTATION"
                }
            ]
        }
    ]
}

Response Format (RDF):

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                 xmlns:aapi="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#"
                 xml:base="http://rdf.alchemyapi.com/rdf/v1/r/response.rdf">
    <rdf:Description rdf:ID="DOCUMENT_HASH">
        <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#DocInfo"/>
        <aapi:ResultStatus>REQUEST_STATUS</aapi:ResultStatus>
        <aapi:Language>DOCUMENT_LANGUAGE</aapi:Language>
        <aapi:URL>DOCUMENT_URL</aapi:URL>
        <aapi:DocText>DOCUMENT_TEXT</aapi:DocText>
    </rdf:Description>
    <rdf:Description rdf:ID="DOCUMENT_HASH-ENTITY_NUM">
        <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#EntityOccurrence"/>
        <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
        <aapi:EntityType>DETECTED_TYPE</aapi:EntityType>
        <aapi:TextStartPos>START_POS</aapi:TextStartPos>
        <aapi:TextEndPos>END_POS</aapi:TextEndPos>
        <aapi:Name>DETECTED_ENTITY</aapi:Name>
        <aapi:Disambiguation>
            <rdf:Description rdf:about="#DOCUMENT_HASH-ENTITY_NUM">
                <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#Disambiguation"/>
                <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
                <aapi:ResolvedName>DISAMBIGUATED_ENTITY</aapi:ResolvedName>
                <aapi:SubType>ENTITY_SUBTYPE</aapi:SubType>
                <aapi:URL>WEBSITE</aapi:URL>
                <aapi:Geo>LATITUDE LONGITUDE</aapi:Geo>
                <owl:sameAs rdf:resource="LINKED_DATA_DBPEDIA"/>
                <owl:sameAs rdf:resource="LINKED_DATA_YAGO"/>
                <owl:sameAs rdf:resource="LINKED_DATA_OPENCYC"/>
                <owl:sameAs rdf:resource="LINKED_DATA_UMBEL"/>
                <owl:sameAs rdf:resource="LINKED_DATA_FREEBASE"/>
                <owl:sameAs rdf:resource="LINKED_DATA_FACTBOOK"/>
                <owl:sameAs rdf:resource="LINKED_DATA_CENSUS"/>
                <owl:sameAs rdf:resource="LINKED_DATA_GEONAMES"/>
                <owl:sameAs rdf:resource="LINKED_DATA_MUSICBRAINZ"/>
                <owl:sameAs rdf:resource="LINKED_DATA_CRUNCHBASE"/>
            </rdf:Description>
        </aapi:Disambiguation>
        <aapi:Quotations>
            <rdf:Description rdf:about="#DOCUMENT_HASH-ENTITY_NUM">
                <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#Quotations"/>
                <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
                <aapi:Quotation>ENTITY_QUOTATION</aapi:Quotation>
            </rdf:Description>
        </aapi:Quotations>
    </rdf:Description>
</rdf:RDF>

Response Fields:

field name

field description

status

success / failure status indicating whether the request was processed.

Possible values:
OK
ERROR

language

detected language (english, french, ..) for the submitted content.

url

http url information was requested for.

type

the detected entity type.

Possible values: (click to see list)

text

the detected entity text.

disambiguated

disambiguation information for the detected entity (sent only if disambiguation occurred)

disambiguation field	field description
name	the disambiguated entity name.
subType	the disambiguated entity subType SubTypes expose additional ontological mappings for a detected entity, such as identification of a Person as a Politician or Athlete.
website	the disambiguated entity website.
geo	latitude longitude the disambiguated entity geographic coordinates.
dbpedia	sameAs link to DBpedia for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
yago	sameAs link to YAGO for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
opencyc	sameAs link to OpenCyc for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
umbel	sameAs link to UMBEL for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
freebase	sameAs link to Freebase for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
ciaFactbook	sameAs link to the CIA World Factbook for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
census	sameAs link to the US Census for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
geonames	sameAs link to Geonames for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
musicBrainz	sameAs link to MusicBrainz for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.
crunchbase	website link to CrunchBase for the disambiguated entity. Note: Provided only for entities that exist in CrunchBase.
semanticCrunchbase	sameAs link to Semantic CrunchBase for the disambiguated entity. Note: Provided only for entities that exist in this linked data-set.

quotations

extracted quotations for the detected entity (sent only if quotations extraction is enabled)

field	field description
quotation	quotation extracted for a particular named entity.

statusInfo

failure status information (sent only if "status" == "ERROR").

Possible values:
invalid-api-key

API Notes:

Calls to TextGetNamedEntities should be made using HTTP POST.
HTTP POST calls should include the Content-Type header: application/x-www-form-urlencoded
Posted text documents can be a maximum of 150 kilobytes. Larger documents will result in a "content-exceeds-size-limit" error response.
Language detection is performed on the retrieved document before attempting named entity extraction. A minimum of 15 characters of text must exist within the requested HTTP document to perform language detection.
Documents containing less than 15 characters of text are assumed to be English-language content.
Disambiguation of detected entities is enabled by default. Disambiguation information will be included for each entity that is successfully resolved.
Entity extraction is currently supported for all languages listed on the language support page. Other foreign-language submissions will be rejected and an error response returned.
Disambiguation and quotations extraction are currently available for English-language content only. Support for other languages is in development.

API Call: TextGetAnnotatedNamedEntityText

Description: The URLGetAnnotatedNamedEntityText call is utilized to annotate a posted text document with detected named entities (people, companies, organizations, etc.). AlchemyAPI will perform entity extraction operations on the posted text content, and annotate the text according to the provided variable substitution template.

Endpoint: http://access.alchemyapi.com/calls/text/TextGetAnnotatedNamedEntityText

Parameters:

http argument

parameter description

text

the text to annotate (must be uri-argument encoded)

(required parameter)

apikey

your private api key

(required parameter)

url

Text document URL

(optional parameter. must be uri-argument encoded)

template

the annotation template to apply to the text we're marking up. this template is applied to each detected entity in the source text. Variable substitution is utilized to integrate entity information into the annotated text.

Supported substitution variables:

variable	variable description
$ENTITY	the detected named entity text
$ENCODED_ENTITY	the detected named entity text (uri-argument encoded)
$TRIMMED_ENTITY	the detected named entity text (punctuation-trimmed)
$ENCODED_TRIMMED_ENTITY	the detected named entity text (punctuation-trimmed, uri-argument encoded)
$RESOLVED_ENTITY	the resolved, disambiguated named entity
$ENCODED_RESOLVED_ENTITY	the resolved, disambiguated named entity (uri-argument encoded)
$TYPE	the detected named entity type

(optional parameter)

outputMode

desired API output format

Possible values:
xml (default)
json
rdf

(optional parameter)

disambiguate

whether to disambiguate detected entities.

Possible values:
1 - enabled (default)
0 - disabled

(optional parameter)

coreference

whether to resolve he/she/etc coreferences into detected entities.

Possible values:
1 - enabled (default)
0 - disabled

(optional parameter)

quotations

whether to enable quotations extraction.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)

showSourceText

whether to include the original 'source text' the entities were extracted from within the API response.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)

Response Format (XML):

<results>
    <status>REQUEST_STATUS</status>
    <url>REQUESTED_URL</url>
    <language>DETECTED_LANGUAGE</language>
    <text>DOCUMENT_TEXT</text>
    <annotatedText>ANNOTATED_TEXT</annotatedText>
</results>

Response Format (JSON):

{
    "status": "REQUEST_STATUS",
    "url": "REQUESTED_URL",
    "language": "DETECTED_LANGUAGE",
    "text": "DOCUMENT_TEXT",
    "annotatedText": "ANNOTATED_TEXT"
}

Response Format (RDF):

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                 xmlns:aapi="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#"
                 xml:base="http://rdf.alchemyapi.com/rdf/v1/r/response.rdf">
    <rdf:Description rdf:ID="DOCUMENT_HASH">
        <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#DocInfo"/>
        <aapi:ResultStatus>REQUEST_STATUS</aapi:ResultStatus>
        <aapi:Language>DOCUMENT_LANGUAGE</aapi:Language>
        <aapi:URL>DOCUMENT_URL</aapi:URL>
        <aapi:DocText>DOCUMENT_TEXT</aapi:DocText>
        <aapi:AnnotatedDocText>ANNOTATED_TEXT</aapi:AnnotatedDocText>
    </rdf:Description>
</rdf:RDF>

Response Fields:

field name	field description
status	success / failure status indicating whether the request was processed. Possible values: OK ERROR
language	detected language (english, french, ..) for the submitted content.
url	http url information was requested for.
language	the detected language that the source text was written in.
annotatedText	the source text annotated with all identified named entities. Text annotation is controlled by the provided template parameter.
statusInfo	failure status information (sent only if "status" == "ERROR"). Possible values: invalid-api-key cannot-retrieve page-is-not-html

API Notes:

Calls to TextGetAnnotatedNamedEntityText should be made using HTTP POST.
HTTP POST calls should include the Content-Type header: application/x-www-form-urlencoded
Posted text documents can be a maximum of 150 kilobytes. Larger documents will result in a "content-exceeds-size-limit" error response.
Language detection is performed on the retrieved document before attempting text annotation. A minimum of 15 characters of text must exist within the requested HTTP document to perform language detection.
Documents containing less than 15 characters of text are assumed to be English-language content.
Disambiguation of detected entities is enabled by default. Disambiguation information will be made available for variable substitution for each entity that is successfully resolved.
Entity extraction is currently supported for all languages listed on the language support page. Other foreign-language submissions will be rejected and an error response returned.
Disambiguation and quotations extraction are currently available for English-language content only. Support for other languages is in development.

Text API

Text API: Entity Extraction

API Call: TextGetRankedNamedEntities

Parameters:

Response Format (XML):

Response Format (JSON):

Response (RDF):

Response Format (REL-TAG Microformat [XML-embedded] ):

Response Format (REL-TAG Microformat [raw] ):

Response Fields:

API Notes:

API Call: TextGetNamedEntities

Parameters:

Response Format (XML):

Response Format (JSON):

Response Format (RDF):

Response Fields:

API Notes:

API Call: TextGetAnnotatedNamedEntityText

Parameters:

Response Format (XML):

Response Format (JSON):

Response Format (RDF):

Response Fields:

API Notes:

Documentation Index