Intelligent Tagging - RESTful API
What is Intelligent Tagging?
Intelligent Tagging is a sophisticated web service designed to let people in the financial domain extract insight from unstructured content.
The underlying NLP engine uses a combination of statistical, machine-learning, and custom pattern-based methods to attach highly-accurate, detailed semantic metadata to unstructured content.
Intelligent Tagging also maps the metadata-tags in the tagging output to Refinitiv unique IDs. This supports disambiguation (and linking) of data across all documents processed by Intelligent Tagging, and the opportunity to further enrich your data with related information from the Refinitiv datasets.
How Does it Work?
Intelligent Tagging analyzes your input text and performs the following processes:
- Named Entity and Relationship Recognition – Intelligent Tagging identifies and tags mentions (text strings) of things like companies, people, deals, geographical locations, industries, physical assets, organizations, products, events, etc.
- Aboutness Tagging – Intelligent Tagging assigns tags (topic tags, social tags, industry tags, slugline tags) that describe what the input document is about as a whole.
Learn more about how the Intelligent Tagging API tags your text...
Deployment Options
Intelligent Tagging (Premium Version)
Premium Intelligent Tagging is available as a Hosted service or as an On Premise solution.
Premium Intelligent Tagging supports:
- Up to millions of submissions per day
- Larger files
- Premium metadata types (such as deals, pharmaceutical drugs, and company hierarchy
- Premium features such as support for tagging PDF files, optimized processing for research reports, and RCS topic classification
Note to internal Refinitiv customers: Internal Intelligent Tagging (also called One Calais) is the premium hosted Intelligent Tagging service available to internal Refinitiv customers who do not connect via API Gateway. The Supplementary Guide for Internal Intelligent Tagging (for internal customers who do not connect through API Gateway) explains the things that are unique to Internal Intelligent Tagging. (These differences are not relevant to Internal customers who connect through API Gateway.) This guide is not relevant to external users.
Open Calais (Free Version)
The free, limited version of Intelligent Tagging is Open Calais, available as a hosted service.
Currently, the free service supports up to 500 requests per day, and provides an extensive set of semantic metadata tags.
To register for a free API Key:
- Register for MyRefinitiv.
- Login to https://PermID.org with your new credentials. An Open Calais API Key is automatically e-mailed to you.
Subsequently, the key is displayed on https://permid.org under APIs > Display my API token.
If you are interested in processing a higher volume of data, or in the functionality provided by premium metadata types, please contact us for further information.
About this Guide
This API User Guide is relevant to all Intelligent Tagging packages and users: premium Intelligent Tagging, free Open Calais, Intelligent Tagging On Premise, internal Intelligent Tagging (for internal customers who do not connect through API Gateway) and Intelligent Tagging for internal customers who do connect through API Gateway.
Any differences are noted in the text, so please look out for sections relevant to a specific Intelligent Tagging package.
Further, the supplementary guide for internal customers who do not connect through API Gateway should be used together with the API User Guide. See Additional Resources.
Note to internal Intelligent Tagging users: The information in this user guide, including the output examples, is specific to the allMetadata profile. The News profile is documented in the Supplementary Guide for Internal Intelligent Tagging (for internal customers who do not connect through API Gateway).
Additional Resources
- How Does Intelligent Tagging Work? provides a detailed conceptual explanation about how tags are applied, with output examples.
- A Practical Approach to Understanding and Ingesting Intelligent Tagging Output for Your Use Case provides some helpful information about getting started using Intelligent Tagging output.
- Abstraction Layer Developer Guide
Since the Intelligent Tagging output does not group metadata types, we highly recommend using the CalaisModel Abstraction Layer to simplify parsing the Intelligent Tagging output.
The Abstraction Layer is relevant to the RDF/XML response format only.
- Release Notes describes what's new in the current release, known issues, and fixed bugs.
- Release Notes Digest provides a running list of new features, and of known and fixed issues since R9.5.
- Intelligent Tagging Semantic Metadata Tags provides detailed definitions of all supported Intelligent Tagging semantic metadata tags.
- Intelligent Tagging for Non-English Languages provides detailed information about using Intelligent Tagging to tag Chinese, French, German, Japanese, and Spanish language input texts.
- Linking to Workspace (Eikon) explains how to link directly from the the Intelligent Tagging output to related pages on Workspace (Eikon). This is relevant to registered Workspace (Eikon) users.
- Additional API User Documentation for Premium Users:
- Download List of all supported RCS Topics (relevant to topic tagging for premium users)
- Download Hierarchical tree view of all RCS topics
- New RCS Topic Classifiers
- Supplementary Guide for Internal Intelligent Tagging (for internal customers who do not connect through API Gateway)
Forming the API Call
Resource URL
Calls to tag content are made via a simple HTTP REST interface.
- Free Open Calais:
POST https://api-eit.refinitiv.com/permid/calais
- Hosted Premium Intelligent Tagging:
POST https://api-eit.refinitiv.com/permid/calais
- On Premise Intelligent Tagging:
POST http://<HOST SERVER IP or HOSTNAME>/tag/rs/enrich
- Internal Refinitiv Customers who connect through API Gateway:
POST https://api-eit.refinitiv.com/permid/calais
- Internal Intelligent Tagging (for internal customers who do not connect through API Gateway):
Please contact us for a link to the tagging method.
Tagging requests must always be sent to port 80. (Although Intelligent Tagging administration services run on port 8080, tagging requests must always be sent to port 80.)
Request Authentication
In order to post a request, you must register and obtain an API access token:
- Open Calais:
Register for MyRefinitiv. Next, login to https://PermID.org with your new credentials. An Open Calais API Key is automatically e-mailed to you.
If you are already a registered user of the Open PermID services, you can use the same token for Intelligent Tagging with the Open Calais API.
If you aren’t familiar with Open PermID, please check out the Open PermID website!
- Hosted Intelligent Tagging:
Please contact us to obtain an access token.
- Intelligent Tagging On Premise:
Request authentication is not relevant to Intelligent Tagging On Premise. To obtain an Intelligent Tagging On Premise license, please contact us.
- Internal Customers:
In order to post a request, you are required to register and obtain an API access token. Please contact us for further information.
Input Content Type
Intelligent Tagging currently supports the following input content types:
- text/html
- text/xml
- application/pdf (for premium users)
- text/raw
Input Size
The input size limitation applies to the entire document, including the body and xml tags, but excluding the HTTP headers.
A submission that exceeds the input size limit is not processed, and an error message is returned.
Note: The size limitation defines the maximum file size that the system can process. However, processing time depends on the complexity of the text within the file, and a timeout error may be generated if a file is too complex (contains too many entities and relations) to be processed within the time limit.
- Free Open Calais
The maximum input size is limited to 100KB (not characters, KB) per request.
The input size limitation applies to all input file types (raw text, xml, html). (The pdf input file type is available to premium users.)
- Hosted Intelligent Tagging
The maximum input size is limited to 500KB (not characters, KB) per request.
The input size limitation applies to all input file types (raw text, xml, html, pdf).
If you require support for larger input files, please contact us.
- Intelligent Tagging On Premise
For Intelligent Tagging On Premise, the maximum file size per request is as follows:
- html – 45 MB
- xml, raw text – 1.5 MB
- pdf – 45 MB
- Internal Customers
The maximum input size per request is defined by your license key, according to your agreement.
The input size limitation applies to all input file types (raw text, xml, html, pdf).
Input Language
Intelligent Tagging currently supports input in the following languages.
- English
- Chinese (Person and Company tagging)
- French (Company, Person, MarketIndex, Organization, City, Country, and more)
- German (Company tagging)
- Japanese (Company tagging)
- Spanish (Company, Person, MarketIndex, Organization, City, Country, and more)
English language support encompasses the full range of Intelligent Tagging metadata types and features. For a full inventory of supported metadata, see Intelligent Tagging Semantic Metadata Tags.
Each of the non-English languages supports a specific subset of Intelligent Tagging semantic metadata types and features. See Intelligent Tagging for Non-English Languages for detailed information and instructions.
Intelligent Tagging determines the language of the submitted content automatically, and invokes the appropriate extraction module for extracting information from the text. Intelligent Tagging may be unable to determine the language properly if the submitted content is too short or contains many non-letter symbols which reduces the accuracy of automatic language detection.
You can use the x-calais-language request header to override the automatic language detection functionality, and it is highly recommended to do so for non-English language input.
Concurrent Requests
Each instance of Intelligent Tagging On Premise supports up to 4 concurrent requests. If you are interested in processing a higher volume of data, please contact us.
This is not relevant to hosted Intelligent Tagging or to free Open Calais.
Request Headers
Note to internal users who do not connect through API Gateway– A different set of input headers is supported for internal Intelligent Tagging (for internal customers who do not connect through API Gateway). These are described in the Supplementary Guide for Internal Intelligent Tagging (for internal customers who do not connect through API Gateway).
All Supported Headers - Intelligent Tagging also supports a number of optional headers that can be used to customize the Intelligent Tagging workflow to your use case.
Mandatory Headers
Note to internal users who do not connect through API Gateway - See the section about Request Headers in the Supplementary Guide for Internal Intelligent Tagging (for internal customers who do not connect through API Gateway).
The input content sent to Intelligent Tagging is accompanied by a set of parameters specified in key-value pairs as HTTP headers of the request. The parameters must be sent as US-ASCII characters. Header names and values are not case sensitive.
In case an HTTP header contains a non-US-ASCII character, the client application must encode it before sending this header to Intelligent Tagging.
The request is an HTTP Post with the following mandatory query parameters:
- x-ag-access-token (mandatory only for hosted Intelligent Tagging and for Open Calais)
- x-calais-selectiveTags (mandatory for new users, soon to be mandatory for all users, not relevant to On Premise users)
x-ag-access-token
Mandatory for hosted Intelligent Tagging and for Open Calais. For Intelligent Tagging On Premise, this header is not supported and not relevant.
| Description: | The license key (token) which grants you access to Intelligent Tagging and defines your submission capacity rights. |
| Values: | Your license key. For Open Calais, if you do not already have a license key, you can Register for MyRefinitiv, and then login to https://PermID.org with your new credentials. An Open Calais API Key is automatically e-mailed to you. For Intelligent Tagging, if you do not already have a license key, contact us. |
| Default: | None |
| Remarks: |
|
Content-Type
| Description: | Indicates the input content type (mime type). Intelligent Tagging processes the input documents according to the value of this parameter for optimal metadata extraction. |
| Values: |
|
| Default: | None |
| Remarks: |
|
| Description | Determines which of the tagging processes are triggered. Use this header to specify all of the metadata-types that are relevant to your use case. |
| Default | None. |
| Remarks | This is a mandatory parameter for all new users, and will become mandatory for existing users. Learn how to implement the x-calais-selectiveTags header.
|
A Sample Request File
Intelligent Tagging On Premise
Intelligent Tagging for Internal Customers who connect through API Gateway
Internal Intelligent Tagging (for internal customers who do not connect through API Gateway)
A Sample Request File (Hosted Intelligent Tagging, Free Open Calais, Intelligent Tagging for Internal Customers who connect through API Gateway):
HTTPS REST
POST https://api-eit.refinitiv.com/permid/calais
Parameters
Content-Type: text/xml
outputFormat:xml/rdf
x-ag-access-token: (your authorized token)
x-calais-selectiveTags:topic-selfservice,company,person
Body
<Document>
<Title>GoPro launches $800 million offering, CEO to sell some shares</Title>
<Body>
Wearable camera maker GoPro Inc's chief executive, Nicholas Woodman, plans to sell a portion of his stake as part of an $800 million offering of the company's shares. The offering of Class A common shares is expected to start in the next couple of weeks and close by November, a company spokesman told Reuters. GoPro's shares fell as much as 5.1 percent before easing back a little to trade down 3.8 percent at $76.04 on Monday.
</Body>
</Document>
HTTP REST
POST http://<HOST SERVER IP or HOSTNAME>:80/tag/rs/enrich
Parameters
Content-Type: text/xml
outputFormat:xml/rdf
Body
<Document>
<Title>GoPro launches $800 million offering, CEO to sell some shares</Title>
<Body>
Wearable camera maker GoPro Inc's chief executive, Nicholas Woodman, plans to sell a portion of his stake as part of an $800 million offering of the company's shares. The offering of Class A common shares is expected to start in the next couple of weeks and close by November, a company spokesman told Reuters. GoPro's shares fell as much as 5.1 percent before easing back a little to trade down 3.8 percent at $76.04 on Monday.
</Body>
</Document>
HTTP REST
POST http://hostname/tag/rs/enrich
Parameters
Content-Type: text/xml
outputFormat: xml/rdf
x-calais-licenseID: (your license)
x-calais-profile: allMetadata
x-calais-selectiveTags:topic-selfservice,company,person
Body
<Document>
<Title>GoPro launches $800 million offering, CEO to sell some shares</Title>
<Body>
Wearable camera maker GoPro Inc's chief executive, Nicholas Woodman, plans to sell a portion of his stake as part of an $800 million offering of the company's shares. The offering of Class A common shares is expected to start in the next couple of weeks and close by November, a company spokesman told Reuters. GoPro's shares fell as much as 5.1 percent before easing back a little to trade down 3.8 percent at $76.04 on Monday. The lock-up period on the stock, which listed in June, expires on Dec. 22, allowing employees and early investors to sell shares of the company. Typically, on the day a lock-up expires, prices tend to fall as a large number of shares become available for trading. The company said the offering was expected to soften the blow of the lock-up expiration on the share price. (Additional reporting by Arathy Nair; Editing by Saumyadeb Chakrabarty)
</Body>
</Document>
For a detailed explanation of Intelligent Tagging output see The API Response.
Security (Relevant to Hosted Intelligent Tagging and free Open Calais)
We respect and guard the privacy of your information. We implement technological safeguards to prevent unauthorized access to your data and we have made a point of implementing a processing workflow that negates any requirement for us to store your data or metadata.
Intelligent Tagging operates entirely over HTTPS in order to secure traffic to and from Intelligent Tagging. The secure connection (HTTPS) ensures that the information you send for processing remains private.
Your data simply passes through our processing engine. Intelligent Tagging processes your data and returns metadata. Intelligent Tagging does not store your data; Intelligent Tagging does not store your metadata.
(This is not relevant to Intelligent Tagging On Premise, or to internal Intelligent Tagging which runs in the Refinitiv secured network .)
If you have any questions or concerns, please contact us.
The API Response
This chapter describes the following:
Since the Intelligent Tagging output does not group metadata types, we highly recommend using the CalaisModel Abstraction Layer to simplify parsing the Intelligent Tagging output.
The Abstraction Layer is relevant to the RDF/XML output format.
See the Abstraction Layer Developer Guide for details.
REST Interface
The Intelligent Tagging web service follows standard REST web service guidelines. This mainly involves responding to the client with standard HTTP error codes.
All successful HTTP transactions return the HTTP status of 200 OK.
Appropriate load/processing errors such as the server is under load, the language or format of document is not supported, etc., are returned in the body of the HTTP response.
Internal Intelligent Tagging exceptions due to unknown reasons result in HTTP responses with the exception/message in the response body and HTTP error code 500.
In addition, the client must take into account issues usually associated with HTTP transactions, such as networking, transport protocol and system issues. An example would be any erroneous HTTP status-code (other than 200), tcp-timeout, tcp-connection-closed, etc., which was reported by the low-level networking layers.
OWL Schema
Intelligent Tagging OWL is an ontology which describes the data structure of the Intelligent Tagging output. The OWL describes the metadata types that can be output by Intelligent Tagging, their possible attributes and the relevant constraints. The OWL also describes relations such as inheritance and directional referencing between metadata elements.
Note: It is important to note that most attributes are optional; a tag can be extracted with some but not all of its attributes.
The OWL can be used as a reference for understanding the range of Calais metadata elements and their relationships to one another. You can download the current OWL schema from the Downloads Tab.
Response Headers (Hosted Intelligent Tagging Only)
These headers are relevant to hosted premium Intelligent Tagging only.
Your license for hosted Intelligent Tagging allows up to a certain number of document submissions per day. The Intelligent Tagging output files include HTTP response headers that indicate the daily quota defined by your license, and the number of submissions already made.
- x-permid-quota-daily: Indicates the daily quota defined by your license.
- x-permid-quota-used: Indicates the number of submissions already made.
HTTP/1.1 200 OK
Content-Type: xml/rdf;charset=UTF-8
DurationMillis: 165
Vary: Accept-Encoding
x-permid-quota-daily: 5000
x-permid-quota-used: 2000
Transfer-Encoding: chunked
Connection: keep-alive
<?xml version="1.0" encoding="UTF-8"?>
…
…
…
<rdf:RDF>
For all other deployment options, including internal Intelligent Tagging (for internal customers who do not connect through API Gateway), these headers are not supported and not relevant.
JSON Response Format
This section provides a JSON output sample with explanation as a general guideline to parsing and interpreting the Intelligent Tagging response. (If you are working with RDF output, then please see the RDF output sample with explanation.)
Please note that the JSON output is derived from RDF and therefore in the output, metadata types are not grouped.
Note: Most attributes are optional; a tag can be extracted with some but not all of its attributes.
The output file is comprised of the following main sections:
Aboutness Tags – tags that describe the document as a whole.
Named Entity and Relationship Recognition – tags that describe the individual text strings contained within the document.
General Document Information – information about when and how the input document was processed.
Note: The forenduserdisplay attribute is displayed by many of the metadata tag types. This is our recommendation of whether the tag is suitable as a search item for a specific document (true) or whether the metadata is primarily of use for aggregation and analytics on large quantities of documents (false). See ForEndUserDisplay Attribute.
Aboutness Tags
Aboutness tags describe the piece of content as a whole.
The Intelligent Tagging response may include any of the following metadata tags:
Social Tag
Social Tags attempt to classify the document as a whole, based on Wikipedia folksonomy.
Examples of social tags, extracted by Intelligent Tagging from the article about Apple developing a self-driving car:
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/SocialTag/1": {
"_typeGroup": "socialTag",
"id": "http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/SocialTag/1",
"socialTag": "http://d.opencalais.com/genericHasher-1/1205cb52-d703-34d2-83b2-a09d4d47575c",
"forenduserdisplay": "true",
"name": "Apple Inc.",
"importance": "1",
"originalValue": "Apple Inc."
},
Note the importance attribute, which indicates how centric the topic named by the social tag is to the document as a whole. The importance attribute value can be 1 (very centric), 2 (somewhat centric), or 3 (less centric).
The docID (dochash) is the unique ID of the containing document.
The Subject (http://d.opencalais.com/dochash-1/268b4e49…) is the tag’s unique ID within the containing document. The dochash component of the subject is what associates this tag with this document.
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/SocialTag/2": {
"_typeGroup": "socialTag",
"id": "http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/SocialTag/2",
"socialTag": "http://d.opencalais.com/genericHasher-1/ccc60460-211d-3b02-b13e-11fba4449fbd",
"forenduserdisplay": "true",
"name": "Autonomous car",
"importance": "1",
"originalValue": "Autonomous car"
},
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/SocialTag/4": {
"_typeGroup": "socialTag",
"id": "http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/SocialTag/4",
"socialTag": "http://d.opencalais.com/genericHasher-1/083d56d1-2fed-3063-b59a-963d4fdaee36",
"forenduserdisplay": "true",
"name": "Electric car",
"importance": "2",
"originalValue": "Electric car"
},
Topic Tags
Topic tagging identifes the topic or topics that are discussed in the document. The reference list of topics is drawn from the RCS (Refinitiv Classification Services) taxonomy and the IPTC (International Press Telecommunications Council) news taxonomy.
Note that access to RCS is available upon subscription to one of the premium Intelligent Tagging deployment options. For more information please contact us.
Note to Internal Intelligent Tagging customers: Internal Intelligent Tagging output exposes different attributes for the Topic tag. For details, see the Supplementary Guide for Internal Intelligent Tagging (for internal customers who do not connect through API Gateway).
Examples
An IPTC taxonomy topic extracted by Intelligent Tagging from the article about Apple developing a self-driving car:
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/cat/1": {
"_typeGroup": "topics",
"forenduserdisplay": "false",
"score": 0.988,
"name": "Technology_Internet"
},
Note the score attribute, which indicates the probability, on a scale of 0 to 1, that the topic is indeed discussed in the text, and also how centric the topic is to the text. The higher the value, the higher the probability.
A TRCS taxonomy topic extracted by Intelligent Tagging from the article about Apple developing a self-driving car:
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/cat/2": {
"_typeGroup": "topics",
"forenduserdisplay": "false",
"rcscode": "B:73",
"name": "Auto, Truck & Motorcycle Parts",
"permid": "4294952928",
"score": 0.75
Industry Tags
Industry tags indicate the industries that are related to the companies mentioned in the input text. The reference list of industries is defined by the Refinitiv Business Classification (TRBC) taxonomy. The Industry tag is a premium metadata type.
The following Industry tags were extracted by Intelligent Tagging from the story about Apple developing a self-driving car.
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/Industry/5": {
"_typeGroup": "industry",
"forenduserdisplay": "false",
"name": "Automobiles & Multi Utility Vehicles",
"rcscode": "B:1294",
"trbccode": "5210101097",
"permid": "4294951707",
"relevance": 0.5
},
Industry tags include a unique Refinitiv ID (the permid attribute value). The ID can be used to extract information about the industry from the Refinitiv dataset. The ID also supports linkage across documents processed by Intelligent Tagging.
Note the relevance attribute, which indicates how relevant the industry is to the story. Values range from 0 to 1. The higher the score, the higher the relevance.
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/Industry/7": {
"_typeGroup": "industry",
"forenduserdisplay": "false",
"name": "Electrical (Alternative) Vehicles",
"rcscode": "B:1296",
"trbccode": "5210101025",
"permid": "4294951705",
"relevance": 0.5
},
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/Industry/8": {
"_typeGroup": "industry",
"forenduserdisplay": "false",
"name": "Auto & Truck Manufacturers - NEC",
"rcscode": "B:1292",
"trbccode": "5210101029",
"permid": "4294951709",
"relevance": 0.5
},
Slugline Tag
Sligline tagging (available to premium customers) classifies documents using Reuters slug lines, providing another way to consistently classify news documents across multiple sources. A document may be assigned up to 8 slugline tags.
Examples of slugline tags extracted from a story about the Bank of England and Brexit:
"http://d.opencalais.com/dochash-1/2771afb0-3124-3a21-ac80-ba4a94fbc8d3/Slugline/1": {
"_typeGroup": "sluglines",
"id": "http://d.opencalais.com/dochash-1/2771afb0-3124-3a21-ac80-ba4a94fbc8d3/Slugline/1",
"forenduserdisplay": "true",
"slugline": "BRITAIN-EU/BANKS",
"isactive": "true",
"creationdate": "2017-01-01T00:00:00.000Z",
"slugid": "sluglines/BRITAIN-EU/BANKS",
"confidencelevel": "0.2617"
"http://d.opencalais.com/dochash-1/2771afb0-3124-3a21-ac80-ba4a94fbc8d3/Slugline/2": {
"_typeGroup": "sluglines",
"id": "http://d.opencalais.com/dochash-1/2771afb0-3124-3a21-ac80-ba4a94fbc8d3/Slugline/2",
"forenduserdisplay": "true",
"slugline": "BRITAIN-EU/BANKS-BOE",
"isactive": "true",
"creationdate": "2017-01-01T00:00:00.000Z",
"slugid": "sluglines/BRITAIN-EU/BANKS-BOE",
"confidencelevel": "0.2446"
Named Entity and Relationship Recognition
Intelligent Tagging scans and analyzes the input text, searching for mentions of things like companies, people, deals, and geographical locations, based on the list of metadata types specified by the x-calais-selectiveTags request header.
The resulting tags form the major part of the output response: Instance tags, Entity Markup tags, Confidence tags, Relevance tags, Resolution (Disambiguation) tags.
Here we’ll highlight some of the metadata tags extracted by Intelligent Tagging from the article about Apple developing a self-driving car.
Note that in the JSON output format, all of the tags related to an extracted entity or relation are nested within the entity markup tag.
Example 1: An Extracted Entity of the Type Company
Example 2: An Extracted Relation of the Type CompanyExpansion
Example 3: An Extracted Relation of the Type CompanyTechnology
Example 4: An Extracted Entity of the Type City
Example 5: An Extracted Relation of the Type CompanyLocation
Example 1: An Extracted Entity of the Type Company
One of the Intelligent Tagging predefined entity types is Company. The article mentions several companies. Let’s take a look at the metadata tags generated by Intelligent Tagging for the company, Apple.
Each group of one or more instances deemed to refer to a unique thing is expressed as an Entity Markup tag. The following is the Entity Markup (em/e/company) tag for the company entity, Apple. (The instances tags, nested within the Entity Markup tag, are also illustrated separately for ease of viewing, but normally they are nested inside the entity tag.)
"http://d.opencalais.com/comphash-1/705cd5cf-93e1-323c-8d4e-1ea3200d37e4": {
"_typeGroup": "entities",
"_type": "Company",
"forenduserdisplay": "true",
"name": "Apple",
"nationality": "American",
"confidencelevel": "0.996",
"recognizedas": "name",
"_typeReference": "http://s.opencalais.com/1/type/em/e/Company",
The hash tag (comphash) is the unique ID assigned by Intelligent Tagging to this extracted entity.
The high confidencelevel value indicates a high level of confidence that the extracted company, Apple, is indeed a company. Some tag types that include the confidencelevel attribute also have an associated Confidence tag.
The associated confidence tag (nested within the Entity Markup tag). The aggregate attribute value is the confidence score:
"confidence": {
"statisticalfeature": "0.997",
"dblookup": "0.0",
"resolution": "0.9928677",
"aggregate": "0.996"
},
Note: The Confidence tag’s aggregate attribute is the same as the related entity markup tag’s confidencelevel attribute. So you can retrieve the confidence score from either tag.
Intelligent Tagging succeeded in mapping the extracted company entity, Apple, to the corresponding company and unique ID in the Refinitiv dataset, resulting in the following Disambiguation tag (nested within the Entity Markup tag):
"resolutions": [{
"permid": "4295905573",
"score": 0.9928677,
"name": "Apple Inc",
"commonname": "Apple",
"ticker": "AAPL",
"primaryric": "AAPL.OQ",
"id": https://permid.org/1-4295905573,
“ispublic”: “true”,
}],
Company Resolution Tag Attributes
Note: The id attribute gives you direct access to high quality, curated Refinitiv company data. The attribute value is a direct link to the relevant company page on the Open PermID website.
The successful mapping to the corresponding Refinitiv entity and permid enables the Intelligent Tagging entity, in this case the company, Apple, Inc., to be unambiguously identified (and thus linked) across all documents processed by Intelligent Tagging.
The following Instance tags were generated when Intelligent Tagging found text strings that it identified as mentions of the company, Apple:
“Apple studies self-driving car, auto industry source says”
"instances": [{
"detection": "[<Document> \n\t<Title>]Apple[ studies self-driving car, auto industry source]",
"prefix": "<Document> \n\t<Title>",
"exact": "Apple",
"suffix": " studies self-driving car, auto industry source",
"offset": 20,
"length": 5
},
“Technology giant Apple (APPL.O) is looking beyond mobile devices to learn how to make a self-driving electric car, and is…”
{
"detection": "[\n\t<Body> \n(Reuters) - Technology giant ]Apple (AAPL.O)[ is looking beyond mobile devices to learn how to]",
"prefix": "\n\t<Body> \n(Reuters) - Technology giant ",
"exact": "Apple (AAPL.O)",
"suffix": " is looking beyond mobile devices to learn how to",
"offset": 151,
"length": 14
},
“An Apple spokesman in London on Saturday declined to comment on ‘rumors or speculation.’ ”
{"detection":"[carmaker Tesla Motors Inc(TSLA.O).\n\n An]Apple[spokesman in Londonon Saturday declined to]",
"prefix":"car-maker Tesla Motors Inc(TSLA.O).\n\n An",
"exact":"Apple",
"suffix":"spokesman in Londonon Saturday declined to",
"offset":1625,
"length":5
},
The RelevanceInfo tag associated with the company entity, Apple, indicates that Apple is highly relevant to the story:
"relevance": 0.8
},
"http://d.opencalais.com/genericHasher-1/4c3556cd-1c91-363f-b4b2-a9d1b372aa85": {
"_typeGroup": "relations",
"_type": "CompanyExpansion",
"forenduserdisplay": "false",
"expansiontype": "New Unit",
"status": "known",
"_typeReference": "http://s.opencalais.com/1/type/em/r/CompanyExpansion",
"company": "http://d.opencalais.com/comphash-1/705cd5cf-93e1-323c-8d4e-1ea3200d37e4",
"instances": [{
"detection": "[ \nThe Wall Street Journal reported on Friday that ]Apple had set up a secret lab[ working on the creation of an Apple-branded]",
"prefix": " \nThe Wall Street Journal reported on Friday that ",
"exact": "Apple had set up a secret lab",
"suffix": " working on the creation of an Apple-branded",
"offset": 2003,
"length": 29
}]
},
CompanyExpansion Tag Attributes
Example 3: An Extracted Relation of the Type CompanyTechnology
The following tags were generated when Intelligent Tagging found a mention in the text that it identified as a relationship between a company and a technology.
"http://d.opencalais.com/genericHasher-1/55d6ef1d-6140-3150-930c-0d5c2fbd0107": {
"_typeGroup": "relations",
"_type": "CompanyTechnology",
"forenduserdisplay": "false",
"_typeReference": "http://s.opencalais.com/1/type/em/r/CompanyTechnology",
"company": "http://d.opencalais.com/comphash-1/705cd5cf-93e1-323c-8d4e-1ea3200d37e4",
"technology": "http://d.opencalais.com/genericHasher-1/38c58bd0-2536-3f03-bfa0-be1867f6fce8",
"instances": [{
"detection": "[\n\t<Date>2015-03-09</Date> \n\t<Body> \n(Reuters) - ]Technology giant Apple (AAPL.O) is looking beyond mobile devices[ to learn how to make a self-driving electric]",
"prefix": "\n\t<Date>2015-03-09</Date> \n\t<Body> \n(Reuters) - ",
"exact": "Technology giant Apple (AAPL.O) is looking beyond mobile devices",
"suffix": " to learn how to make a self-driving electric",
"offset": 134,
"length": 64
}]
},
CompanyTechnology Tag Attributes
Note that the company attribute value is the comphash which references the extracted company entity, Apple Inc., and the technology attribute value is the genericHasher which references the extracted technology entity, mobile devices.
Example 4: An Extracted Entity of the Type City
In this example, the Instance, Entity Markup, and Relevance tags were generated when Intelligent Tagging found text strings that it identified as references to the same City. The associated Disambiguation (er/Geo/City) tag was generated when Intelligent Tagging successfully mapped the extracted city, Cupertino, to the corresponding city in the Refinitiv dataset.
Entity markup tag for the extracted City entity, Cupertino:
"http://d.opencalais.com/genericHasher-1/752be8ce-c588-3bbe-8526-af3b60708561": {
"_typeGroup": "entities",
"_type": "City",
"forenduserdisplay": "false",
"name": "Cupertino",
"_typeReference": "http://s.opencalais.com/1/type/em/e/City",
"resolutions": [{
"name": "Cupertino,California,United States",
"shortname": "Cupertino",
"latitude": "37.3231",
"longitude": "-122.0311",
"containedbystate": "California",
"containedbycountry": "United States"
}],
City Resolution Tag Attributes
Instance tags generated for two found mentions of Cupertino in the text.
"instances": [{
"detection": "[with the discussions said on Saturday. \n \nThe ]Cupertino[, California-based maker of phones, computers]",
"prefix": "with the discussions said on Saturday. \n \nThe ",
"exact": "Cupertino",
"suffix": ", California-based maker of phones, computers",
"offset": 399,
"length": 9
},
{
"detection": "[ working a few miles from Apple's headquarters in ]Cupertino[. \n \nApple executives met with contract]",
"prefix": " working a few miles from Apple's headquarters in ",
"exact": "Cupertino",
"suffix": ". \n \nApple executives met with contract",
"offset": 2411,
"length": 9
}],
"relevance": 0.2
},
The relevance score indicates that the city, Cupertino, is not highly centric to the story.
Example 5: An Extracted Relation of the Type CompanyLocation
The following tags were generated when Intelligent Tagging found a text string that it identified as a relationship between a company and a location (i.e. a mention, of the type CompanyLocation):
"http://d.opencalais.com/genericHasher-1/f64cef62-b4a7-39f1-b92a-ef8834053ff1": {
"_typeGroup": "relations",
"_type": "CompanyLocation",
"forenduserdisplay": "true",
"companylocationtype": "N/A",
"_typeReference": "http://s.opencalais.com/1/type/em/r/CompanyLocation",
"company": "http://d.opencalais.com/comphash-1/705cd5cf-93e1-323c-8d4e-1ea3200d37e4",
"city": "http://d.opencalais.com/genericHasher-1/752be8ce-c588-3bbe-8526-af3b60708561",
"instances": [{
"detection": "[with the discussions said on Saturday. \n \n]The Cupertino, California-based maker[ of phones, computers and, soon, watches is]",
"prefix": "with the discussions said on Saturday. \n \n",
"exact": "The Cupertino, California-based maker",
"suffix": " of phones, computers and, soon, watches is",
"offset": 395,
"length": 37
}]
},
Note that the company attribute value is the comphash that references the extracted company, Apple, Inc., and the city attribute value is the genericHasher that references the extracted city, Cupertino.
Miscellaneous - General Document Information
Info
The Info node presents the original input text (inside the body tag).
Note the dochash, which appears in many of the tags in the output file; it is the unique ID of the containing document.
"info": {
"calaisRequestID": "f73e91c1-6812-5522-14c4-0d762ca66849",
"id": "http://id.opencalais.com/lI-1l*-GlzU4-tLm773vCg",
"ontology": "http://och1-lb/owlschema/8.2/onecalais.owl.allmetadata.xml",
"docId": "http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630",
"document": "<Document> \n\t<Title>Apple studies self-driving car, auto industry source says</Title> \n\t<Date>2015-03-09</Date> \n\t<Body> \n(Reuters) - Technology giant Apple (AAPL.O) is looking beyond mobile devices to learn how to make a self-driving electric car, and is talking to experts at carmakers and automotive suppliers, a senior auto industry source familiar with the discussions said on Saturday. \n \nThe Cupertino, California-based maker of phones, computers and, soon, watches is exploring how to make an entire vehicle, not just designing automotive software or individual components, the auto industry source said. \n \n\"They don't appear to want a lot of help from carmakers,\" said the source, who declined to be named. \n \nApple is gathering advice on parts and production methods, focusing on electric and connected-car technologies, while studying the potential for automated driving, the source said. \n \n\"Fully automated driving is an evolution. Carmakers will slowly build the market for autonomous cars by first releasing connected and partially automated cars,\" the auto industry source said. \"Apple is interested in all the potential ways you can evolve the car; that includes autonomous driving.\" \n \nWhether it will build and release an electric car or a more evolved autonomous vehicle remains to be seen, the source said. \n \nBut clearly Apple has sharply raised its ambitions in automotive technology. Car technology has become a prime area of interest for Silicon Valley companies ranging from Google Inc (GOOGL.O), which has built a prototype self-driving car, to electric car-maker Tesla Motors Inc (TSLA.O). \n \nAn Apple spokesman in London on Saturday declined to comment on \"rumors or speculation\". \n \nTrying to build an actual car would mark a dramatic shift for the maker of the iPhone and iPad. Apple often researches projects which are then discarded, but has so far mainly stuck to its core expertise in mobile and electronic devices. \n \nThe Wall Street Journal reported on Friday that Apple had set up a secret lab working on the creation of an Apple-branded electric car, citing people familiar with the matter. The lab was set up late last year, soon after Apple revealed its forthcoming smart watch and latest iPhones, the Financial Times said. \n \nThe Journal said that the Apple project, code-named \"Titan\", employed several hundred people working a few miles from Apple's headquarters in Cupertino. \n \nApple executives met with contract manufacturers including Magna Steyr in Austria, a unit of Magna International (MG.TO), the Journal said. A Magna spokeswoman declined to comment. \n \nTHE PATH TO SELF-DRIVING CARS \n \nAutonomous driving is likely to emerge progressively as driver assistance systems become more sophisticated. \n \nAlready, carmakers such as Daimler (DAIGn.DE), BMW (BMWG.DE) and Volkswagen's (VOWG_p.DE) Audi (NSUG.DE) have revealed cars that can travel long distances without human intervention. \n \nAnalysts at Exane BNP Paribas have said they see a $25 billion market for automated driving technology by 2020, with vehicle intelligence becoming “the key differentiating factor”. But the brokerage does not expect fully automated cars to hit the road until 2025 or 2030, in part due to regulatory hurdles. \n \nShort of building entire cars, there is money to be made from the software to run a self-driving vehicle, as well as the services associated with autonomous driving, such as mapping, car-sharing and car recharging services, the auto source said. \n \n\"It's a software game. It's all about autonomous driving,\" the industry source said. \n \nApple may be pursuing mainly auto industry expertise rather than full-scale partnerships with established car companies. \n \nWith its soon-to-be-launched Apple Watch, the company had held limited discussions with Swiss watchmakers, but no broad-based alliance emerged from the talks. \n \nInstead of partnerships, Apple pursued a go-it-alone strategy and turned to poaching talent from top watch brands. \n \nTwo different sources have told Reuters that Apple has tried to recruit auto industry experts in areas such as robotics. \n \n(Additional reporting by Eric Auchard in Frankfurt; Editing by Noah Barkin/Hugh Lawson) \n\t</Body> \n</Document>",
"docTitle": "Apple studies self-driving car, auto industry source says",
"docDate": "2015-03-09 00:00:00"
},
"meta": {
"contentType": "text/xml",
"processingVer": "AllMetadata",
"serverVersion": "OneCalais_8.2-RELEASE:360",
"stagsVer": "OneCalais_8.2-RELEASE-b6-2015-02-14_17:44:23",
"submissionDate": "2015-03-22 11:36:39.626",
"submitterCode": "d9d88048-1255-f96b-87c2-22d93db1bd23",
"signature": "digestalg-1|PmYxlNM8avWDT0QjMhMrOmTVPPQ=|gQMTTrBIwMTq0MbDkobw5xmxi01rVEhBOYs3cvQUVJAE528OL7s0zg==",
"language": "English"
}
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/ComponentVersions": {
"_typeGroup": "versions",
"version": ["Deals Index:201503220400:201503220400",
"OA Index:201503211840:201503211840",
"NextTags:OneCalais_8.2-RELEASE:108",
"SpanishIM:OneCalais_8.2-RELEASE:195",
"config-sca-DataPackage:34:34",
"SECHeaderMetadataIM:OneCalais_8.2-RELEASE:195",
"com.clearforest.infoext.dial4j.plugins-basistechconfig:OneCalais_8.2-RELEASE:222",
"People Index:201503212335:201503212335",
"Collector:OneCalais_8.2-RELEASE:108",
"Dial4J:OneCalais_8.2-RELEASE:195",
"AutocoderRuntimeIM:OneCalais_8.2-RELEASE:195",
"OA Override:258:258",
"People Override:247:247",
"BrokerResearchIM:OneCalais_8.2-RELEASE:195",
"config-refineries:247:247",
"config-cse:247:247",
"OneCalaisIM:OneCalais_8.2-RELEASE:195",
"config-vessels:247:247",
"OneCalais:OneCalais_8.2-RELEASE:360",
"Housekeeper:OneCalais_8.2-RELEASE:108",
"WatchDog:OneCalais_8.2-RELEASE:108",
"SocialTags Index:201503080540:201503080540",
"BlackList:247:247",
"FrenchIM:OneCalais_8.2-RELEASE:195",
"config-physicalAssets-ports:247:247",
"config-drugs:247:247"]
},
DefaultLangID
This tag indicates the input text language identified by Intelligent Tagging, or specified by the x-calais-language request header if it's defined.
Based on the input text language, Intelligent Tagging invokes the appropriate metadata extraction module.
In the following example, the indicated input text language is English.
"http://d.opencalais.com/dochash-1/268b4e49-098d-389d-9d76-816cb722a630/lid/DefaultLangId": {
"_typeGroup": "language",
"language": "http://d.opencalais.com/lid/DefaultLangId/English",
"forenduserdisplay": "false",
"permid": "505062"
},
Error Messages
Intelligent Tagging returns messages when it cannot process or complete a transaction due to format or load issues. Such requests are returned in the body of the HTTP response with an HTTP error code.
There are two types of error messages:
Client Errors (4XX)
Server Errors (5XX)
Client Errors
If the submitted request contains an error, a client error message is generated; check the message and adapt the request according to the error message.
The errors generated for the different Intelligent Tagging deployment options are different and are listed in separate tables.
- Intelligent Tagging On Premise - Client Errors
- Intelligent Tagging for internal customers who connect through API Gateway - Client Errors
Client Errors - Relevant to Hosted Intelligent Tagging, Free Open Calais, and Internal customers who connect throught API Gateway
HTTP Response Code |
Error Reason |
Error Message |
Remarks |
400 |
Bad content-type header value: <VALUE> |
|
|
400 |
Invalid content |
Null or empty content submitted. |
|
400 |
Unsupported-Language |
You've submitted a document in <LANGUAGE>, which is not currently supported. |
|
400 |
Unrecognized-Language |
Unrecognized language.
|
Intelligent Tagging may not properly identify the language if the input text is too short. In this case, define a valid x-calais-language input header. |
401 |
Invalid API key |
oauth.v2.InvalidApiKey |
Indicates an invalid license key. Please verify that you have entered the correct key, or contact support. |
401 |
Invalid API key for given resource |
oauth.v2.InvalidApiKeyForGivenResource |
The license key does not match the POST URL. Please check that the POST address and license key are correct. |
406 |
Unsupported-Output-Format-Requested |
Unsupported output format: <VALUE> |
|
413 |
Request Entity Too Large |
Your Calais request has exceeded the max allowed document size. |
|
415 |
Unsupported Media Type |
javax.ws.rs.WebApplicationException. |
The input format sent is not supported |
429 |
Too many requests |
You exceeded the concurrent request limit for your license key. Please try again later or contact support to upgrade your license. |
This error is recoverable. Try resubmitting the document (maximum three retries) with a sleep of 750 milliseconds between resubmissions.) |
429 |
Too many requests |
You exceeded the allowed quota of <VALUE> requests per day. Please try again at: <DATE_TIME> |
This error is recoverable but is an indication that you have reached your daily quota. Wait to resubmit the document at least until the next day at 00:00:00 GMT time. To increase the quota (the daily document upload limit), please contact us. |
Client Errors - Relevant to Intellligent Tagging On Premise
HTTP Response Code |
Error Reason |
Error Message |
Remarks |
400 |
Invalid content |
Null or empty content submitted. |
|
400 |
Missing-Header |
Missing a mandatory <header_parameter_name> Header: '%s' |
|
400 |
Content-Does-Not-Fit-Content-Type |
Unsupported content-type |
|
400 |
Unsupported-Language |
You've submitted a document in <LANGUAGE>, which is not currently supported. |
|
400 |
Unrecognized-Language |
Unrecognized language.
|
Intelligent Tagging may not properly identify the language if the input text is too short. In this case, define a valid x-calais-language input header. |
400 |
No license was activated. |
No active license. |
|
401 |
Invalid license. |
Invalid user token. Please contact support to obtain a valid token. |
|
401 |
Maximum concurrency exceeded. |
You have exceeded the maximum request concurrency allowed for your user token. |
To increase the number of allowed concurrent requests, contact us. |
406 |
Unsupported-Output-Format-Requested |
Unsupported output format: <VALUE> |
|
413 |
Max-Document-Length-Exceeded |
The document length has exceeded the allowed size for content of type <contenttype>. |
|
415 |
Unsupported-Content-Type-For-Server |
PDF conversion is not supported on this server node. |
|
415 |
Illegal-Content-Type |
The value <value> supplied for Content-Type is not supported. |
|
415 |
Illegal-Content-Class |
Illegal x-calais-contentClass header field value:’<value>’. |
|
Client Errors - Relevant to Internal Intelligent Tagging (for internal customers who do not connect throught API Gateway)
| HTTP Response Code | Error Reason | Error Message | Remarks |
| 400 | Invalid content | Null or empty content submitted. | |
400 |
Invalid-Body-Tag |
The body tag ‘<tagname>’, supplied in the x-calais-bodyTag header field, was not found in the submitted document. |
|
400 |
Content-Does-Not-Fit-Content-Type |
Your content appears to be of type <value> but was not submitted as such. Please specify this content-type in the header field. |
|
400 |
Missing-Header |
Missing a mandatory <header_parameter_name> Header: '%s' |
|
400 |
Content-Does-Not-Fit-Content-Type |
Unsupported content-type |
|
400 |
No-Content-Type-Specified |
Content type is mandatory |
|
400 |
Bad-Content-Length |
Content length header does not match the actual content size |
|
400 |
Unsupported-Language |
You've submitted a document in <LANGUAGE>, which is not currently supported. |
|
400 |
Unrecognized-Language |
Unrecognized language.
|
Intelligent Tagging may not properly identify the language if the input text is too short. In this case, define a valid x-calais-language input header. |
401 |
Rate-Limit-Rate-Exceeded |
Your file submission rate has exceeded the limit allowed for your user token. |
|
401 |
Rate-Limit-Invalid-Pool |
You are not authorized to access this server pool with this user token. Please contact support. |
|
401 |
Rate-Limit-User-Blocked |
Access has been blocked for this customer. Please contact support. |
|
401 |
Rate-Limit-Token-Blocked |
Access has been blocked for this user token. Please contact support |
|
401 |
Rate-Limit-Traffic-Exceeded |
Your submission rate has exceeded the traffic limit allowed for your user token. |
|
401 |
Rate-Limit-Concurrency-Exceeded |
You have exceeded the maximum request concurrency allowed for your user token. |
|
406 |
Unsupported-Output-Format-Requested |
Unsupported output format: <VALUE> |
|
413 |
Max-Document-Length-Exceeded |
The document length has exceeded the allowed size for content of type <contenttype>. |
|
415 |
Unsupported-Content-Type-For-Server |
PDF conversion is not supported on this server node. |
|
415 |
Illegal-Content-Type |
The value <value> supplied for Content-Type is not supported. |
|
415 |
Illegal-Content-Class |
Illegal x-calais-contentClass header field value:’<value>’. |
|
415 |
Illegal-Source-Header |
Illegal x-calais-source header: ‘<value>’. |
|
Server Errors
Server errors are generated when there is a problem at the server; resubmitting the request might solve the problem.
The errors generated for the different Intelligent Tagging deployment options are different and are listed in separate tables.
- Intelligent Tagging On Premise - Server Errors
- Intelligent Tagging for internal customers who connect through API Gateway - Server Errors
Server Errors - Relevant to Hosted Intelligent Tagging, Free Open Calais, and internal customes who connect throught API Gateway
HTTP Response Code |
Error Reason |
Error Message |
Remarks |
500 |
Request-Timeout |
Timeout reached while processing the document. |
This error may be recoverable, if the timeout was due to heavy utilization of the system. Try resubmitting the document (maximum three retries) with a sleep of 750 milliseconds between resubmissions.) If the resubmission does not work, it may be that the input document is too complex (contains too many entities and relations) to be processed within the defined time limit. In this case, you can try splitting the document into smaller parts for processing. Premium Intelligent Tagging customers may contact us at https://my.refinitiv.com regarding any unresolved request timeouts. Please include document examples. |
500 |
Request-Terminated |
Calais server terminated the job. |
|
500 |
Internal-Error |
<The actual exception from the server.> |
|
503 |
Server-Too-Busy |
Calais server is busy. Please try again later. |
This error is recoverable. Try resubmitting the document (maximum three retries) with a sleep of 750 milliseconds between resubmissions.) |
503 |
Service Unavailable |
No server is available to handle this request. |
|
Server Errors - Relevant to Intelligent Tagging On Premise
HTTP Response Code |
Error Reason |
Error Message |
Remarks |
500 |
Request-Timeout |
Timeout reached while processing the document. |
This error may be recoverable, if the timeout was due to heavy utilization of the system. Try resubmitting the document (maximum three retries) with a sleep of 750 milliseconds between resubmissions.) If the resubmission does not work, it may be that the input document is too complex (contains too many entities and relations) to be processed within the defined time limit. In this case, you can try splitting the document into smaller parts for processing. Premium Intelligent Tagging customers may contact us at https://my.refinitiv.com regarding any unresolved request timeouts. Please include document examples. |
500 |
Request-Terminated |
Calais server terminated the job. |
|
500 |
Html-Cleanup-Error |
The following error occurred while performing HTML cleanup: <errortext> |
|
500 |
Internal-Error |
<The actual exception from the server.> |
|
503 |
Server-Too-Busy |
Calais server is busy. Please try again later. |
This error is recoverable. Try resubmitting the document (maximum three retries) with a sleep of 750 milliseconds between resubmissions.) |
503 |
Server-Still-Initializing |
System is initializing. Please try again later. |
|
Server Errors - Relevant to Internal Intelligent Tagging (for internal customers who do not connect throught API Gateway)
HTTP Response Code |
Error Reason |
Error Message |
Remarks |
500 |
Request-Timeout |
Timeout reached while processing the document. |
This error may be recoverable, if the timeout was due to heavy utilization of the system. Try resubmitting the document (maximum three retries) with a sleep of 750 milliseconds between resubmissions.) If the resubmission does not work, it may be that the input document is too complex (contains too many entities and relations) to be processed within the defined time limit. In this case, you can try splitting the document into smaller parts for processing. |
500 |
Request-Terminated |
Calais server terminated the job. |
|
500 |
Html-Cleanup-Error |
The following error occurred while performing HTML cleanup: <errortext> |
|
500 |
Internal-Error |
<The actual exception from the server.> |
|
503 |
Server-Too-Busy |
Calais server is busy. Please try again later. |
This error is recoverable. Try resubmitting the document (maximum three retries) with a sleep of 750 milliseconds between resubmissions.) |
503 |
Server-Still-Initializing |
System is initializing. Please try again later. |
|
List of All Supported Metadata Tags
Intelligent Tagging is designed to extract a rich set of metadata tags from your input text. In this section we provide a comprehensive list of all the tag types and concepts which may be found in the Intelligent Tagging response. For detailed tag and attribute definitions, see Intelligent Tagging Semantic Metadata Tags.
Supported Tag Types:
- Instance
- Entity Markup Tags (Entity tags and Relationship tags)
- RelevanceInfo
- Confidence
- Disambiguation
- SocialTag
- Topic (DocCat)
- Slugline (premium feature)
- Industry (premium feature)
Anniversary City Continent Editor EmailAddress EntertainmentAwardEvent Facility FaxNumber Holiday IndustryTerm
|
Journalist MedicalCondition MedicalTreatment Movie MusicAlbum MusicGroup NaturalFeature OperatingSystem Organization PharmaceuticalDrug PhoneNumber PoliticalEvent Position
|
Product ProgrammingLanguage ProvinceOrState PublishedMedium RadioProgram RadioStation Region SportsEvent SportsGame SportsLeague Technology TVShow TVStation URL |
*These metadata types are actively enhanced and supported. Learn more about actively enhanced and supported metadata types.
Acquisition Alliance AnalystEarningsEstimate AnalystRecommendation ArmedAttack ArmsPurchaseSale Arrest Bankruptcy BonusSharesIssuance BusinessRelation Buybacks CandidatePosition CompanyAccountingChange CompanyAffiliates CompanyCompetitor CompanyCustomer CompanyEarningsAnnouncement CompanyEarningsGuidance CompanyEmployeesNumber CompanyExpansion CompanyForceMajeure CompanyFounded CompanyInvestigation CompanyInvestment CompanyLaborIssues CompanyLayoffs CompanyLegalIssues CompanyListingChange CompanyLocation |
CompanyMeeting CompanyNameChange CompanyProduct CompanyReorganization CompanyRestatement CompanyTechnology CompanyTicker CompanyUsingProduct ConferenceCall ContactDetails Conviction CreditRating Deal DebtFinancing DelayedFiling DiplomaticRelations Dividend EmploymentChange EmploymentRelation EnvironmentalIssue EquityFinancing Extinction FamilyRelation FDAPhase IndicesChanges Indictment IPO JointVenture |
ManMadeDisaster Merger MilitaryAction MovieRelease MusicAlbumRelease NaturalDisaster PatentFiling PatentIssuance PersonAttributes PersonCareer PersonCommunication PersonEducation PersonEmailAddress PersonLocation PersonParty PersonRelation PersonTravel PoliticalEndorsement PoliticalRelationship PollsResult ProductIssues ProductRecall ProductRelease Quotation SecondaryIssuance StockSplit Trial VotingResult |
TIP: Improve the search results of your application by mapping common search strings to entity types. See Synonyms for Entity Relation Types.
Note to Internal Intelligent Tagging (for internal customers who do not connect through API Gateway): Please see the Supplementary Guide for Internal Intelligent Tagging (for internal customers who do not connect through API Gateway), for the relevant list of supported entities and relations, and for a summary of the differences in the tagging output.
Learn more:
How does Intelligent Tagging work? - A conceptual overview of these tags with output examples.
Intelligent Tagging Semantic Metadata Tags (detailed tag definitions and examples) - A complete reference guide to all Intelligent Tagging semantic metadata tags and their attributes. Provides detailed tag definitions and examples and a list of the metadata tags supported for French and Spanish language input.
Intelligent Tagging for Non-English Languages (Chinese, French, German, Japanese, Spanish)
Topic Tagging (Classification)
During processing, Intelligent Tagging identifies the topics discussed in the document, and outputs the relevant DocCat (topic) tags. The list of possible topics is drawn from the RCS (Refinitiv Classification Services) taxonomy and/or by the International Press Telecommunications Council (IPTC) news taxonomy.
The Intelligent Tagging classification engine supports over 1500 topics from the RCS (Refinitiv Classification Services) taxonomy. Access to RCS topics is available to premium users.
Detailed information about RCS Topic Tagging
Download the list of Supported RCS Topics (This list is available to premium users.)
Learn how to use the x-calais-selectiveTags header to trigger topic tagging.
Intelligent Tagging supports a small set of high-level news topics defined by the International Press Telecommunications Council (IPTC) news taxonomy.
| Intelligent Tagging IPTC topic tag | Description | Represents this IPTC taxonomy topic |
| Business_Finance | corporate financial results, joint business ventures, global currencies, prices and markets, stocks and bonds, prices, economic forums | economy, business and finance |
| Disaster_Accident | man-made and natural events resulting in damage to objects, loss of life or injury | disaster, accident and emergency |
| Education | topics related to aspects of furthering knowledge of humans | education |
| Entertainment_Culture | media, movies and TV, literature and journalism, music, celebrities, entertainment products, internet culture, youth culture | arts, culture, entertainment and media |
| Environment | topics related to the condition of our planet such as natural disasters, protection, and their effect on living species as well as inanimate objects or property | environment |
| Health_Medical_Pharma | hospitals and healthcare, medical research, diseases, drugs, pharmaceutical industry, health insurance, diet and nutrition. | health |
| Hospitality_Recreation | eating and travel, leisure/recreational facilities and general activities undertaken for pleasure and relaxation | lifestyle and leisure |
| Human Interest | lighter topics of general interest for humans | human interest |
| Labor | topics related to the employment of individuals, support of the unemployed | labor |
| Law_Crime | topics relating to the enforcement of rules of behavior in society, breaches of these rules and the resulting punishments; law firms, legal practice and lawsuits | crime, law and justice |
| Politics | government policies and actions, politicians and political parties, elections, war and acts of aggression between countries | politics |
| Religion_Belief | theology, philosophy, ethics and spirituality | relition and belief |
| Social Issues | topics related to aspects of the behavior of humans affecting the quality of life | society |
| Sports | sports competitions and tournaments, athletes, Olympic games | sport |
| Technology_Internet | technological innovations, technology-related companies, hardware and software products, internet products and web sites, telecom industry | information technology and computer science |
| Weather | topics relating to meteorological phenomena | weather |
| War_Conflict | topics related to acts of socially- or politically- motivated protest and/or violence | conflict, war and peace |
Contact Us
Open Calais, Hosted Intelligent Tagging, and Intelligent Tagging On Premise:
Sales Related Enquiries: https://www.refinitiv.com/en/forms/standard-form-overlay
All Intelligent Tagging users, including Free Open Calais users may contact Sales for enquiries about:
- Obtaining a license key
- Increasing processing capacity
- Premium features
- Data security (Hosted Intelligent Tagging)
- Any other query relating to Intelligent Tagging
Technical Support: https://my.refinitiv.com
If you are a licensed Intelligent Tagging user with a technical issue, please contact Technical Support.
Engagement: pgotam@refinitiv.com
If you are evaluating Intelligent Tagging and require technical support, please contact Engagement.
Questions about working with the API
The "View Q&A forum" link appears on every Developer Portal page. Go to the Q&A forum page to "Ask a question." When prompted to select a forum, choose Open Calais or Intelligent Tagging.
Additional Resources:
Additional resources and documentation for Intelligent Tagging are available throughout the Developer Community.
The OWL schema and the Abstraction Layer Libraries are found on the Downloads tab.
Internal Customers: