TheySay PreCeive API Documentation
Introduction
TheySay PreCeive API is a platform-agnostic service which enables developers to access and mix-and-match our powerful text analysis processors that cover sentiment analysis, speculation detection, part-of-speech tagging, dependency parsing, and others. If you're building an application that cannot do without serious, state-of-the-art text analytics but don't want to delve deep into natural language processing, then this is the API for you.
Getting started with PreCeive API is easy. Test-drive our live public API demo, explore its end points below, and contact us to receive a development key. Need help or want to give feedback? Contact us - we'd love to hear from you!
API Clients
To help you get started, Open Source API clients are currently available for Java (1), Java (2), Scala, Python, Ruby, Node.js, R, and PHP. [PreCeive-Batch](https://github.com/theysay/preceive-batch) is a Java based tool that is suitable for batch processing and evaluations.
Authentication
TheySay PreCeive API uses HTTP Basic authentication over HTTPS.
User Levels
While most end points are available to all users, some can be accessed only by premium users (denoted as ☆☆☆PREMIUM USER☆☆☆ in the documentation).
Multilingual Support
The API expects you to submit English text to it. Beyond English, multilingual support is provided in the form of specific language-analysis pairs. Multilingual support currently covers German and Spanish sentiment analysis.
HTTP Methods
PreCeive API follows REST principles. The following HTTP request methods are supported for analysis requests:
POST
(recommended)- Query fields are in the request body and expressed as JSON.
- Example payload:
{ "text":"Patchy rain, sleet or snow in parts...", "level":"sentence" }
GET
- Query fields are expressed as parameters in the URL and must be URL-encoded. Note that
GET
exposes only a limited subset of available query fields. - Example URL:
/v1/sentiment?text=how%20cool%20is%20that!&level=sentence
- Query fields are expressed as parameters in the URL and must be URL-encoded. Note that
HTTP Response Codes
- 200
OK
- The request was successful. - 201
Created
- The request was successful and a resource was created. - 400
Bad Request
- The request could not be interpreted correctly or some required parameters were missing. - 401
Unauthorized
- Authentication failed - double-check your username and/or password. - 405
Method Not Allowed
- The requested method is not supported. Only GET and POST are allowed. - 429
Too Many Requests
- Quota or rate limit exceeded (see below). - 500
Internal Server Error
- Something is broken. Please contact us and we'll investigate.
Quotas and Rate Limits
We enforce two request quotas: requests per day and requests per minute. Your quotas depend on your API subscription. By default, the following rates apply:
- Maximum
500
requests per day, reset at midnight UTC. - Maximum
30
requests per minute.
Responses returned by the API contain information about your quota in the following response header fields:
-
X-RequestLimit-Limit
- # of requests that you can send in a day. Example:15000
. -
X-RequestLimit-Remaining
- # of requests that you can send before you will exceed your daily request limit. Example:12323
. -
X-RequestLimit-Reset
- When your next daily quota will be reset (in UTC [epoch milliseconds](http://en.wikipedia.org/wiki/Unix_time)). Example:1360281599708
. -
X-RateLimit-IntervalSecs
- The length of your rate limit window. Example:60
. -
X-RateLimit-Limit
- # of requests that can send within your rate limit window. Example:30
. -
X-RateLimit-Remaining
- # of requests that you can send before you will exceed your rate limit. Example:25
. -
X-RateLimit-Reset
- When your next rate limit window will be reset (in UTC [epoch milliseconds](http://en.wikipedia.org/wiki/Unix_time)). Example:1360254866709
.
You can also see your current rate limit status by calling /rate_limit
. Example: https://api.theysay.io/rate_limit.
For more information about quotas, rate limits, and subscriptions, contact us.
Maximum Request Length
The maximum length of the text body in each request is 20000
characters.
JSONP Support
Use the callback
request parameter to add a [JSONP](http://en.wikipedia.org/wiki/JSONP) wrapper. The returned Content-Type
will be application/javascript
.
GZIP Compression
Add Accept-Encoding: gzip
to your request headers if you want the API to deliver a gzipped stream.
Server Version
To view build and version information about the current API, call /version
. Example:
https://api.theysay.io/version
Version 1 API
Sentiment: English
/v1/sentiment
Sentiment, a dimension of non-factuality in language that is closely related to subjectivity/affect/emotion/moods/feelings, reflects psychological evaluation with the following fundamental poles:
-
positive
(~ good / pros / favourable / desirable / recommended / thumbs up /...) vs -
negative
(~ bad / cons / unfavourable / undesirable / not recommended / thumbs down /...)
You can use the Sentiment Analysis service to discover and score deep, fine-grained sentiments and opinions in text. The analysis, output by a human-like sentiment reasoning algorithm, captures both explicit "author sentiment" as well as general, implicit "reader-sentiment" beyond opinions that ultimately stems from affective commons sense as well as issues and events that are generally considered to be good vs. bad in the world.
The returned analysis includes majority sentiment labels, fine-grained 3-way positive/neutral/negative percentage scores, and other useful auxiliary fields.
POST /v1/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v1/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v1/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | entity | string, required | Enables entity-level sentiment analysis. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
targets | market|business|opportunity|cost | string, optional | Match expression for target entities. |
matching | head | string, optional | Matching mode. |
Response 200
POST /v1/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | entityaggregate | string, required | Enables sentiment analysis for entity aggregates. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v1/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | entityrelation | string, required | Enables relational entity-level sentiment analysis. |
Response 200
POST /v1/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | word | string, required | Enables document-level sentiment flow analysis. |
Response 200
Sentiment: Multilingual
/v1/multilingual/sentiment
Beyond English, the API offers sentiment analysis for German (de
) and Spanish (es
) at the document and the sentence levels.
POST /v1/multilingual/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
language | de | string, required | The ISO 639-1 natural language code for the input text. See http://www.loc.gov/standards/iso639-2/php/code_list.php for the codes. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v1/multilingual/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
language | de | string, required | The ISO 639-1 natural language code for the input text. See http://www.loc.gov/standards/iso639-2/php/code_list.php for the codes. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
Emotions: Unbounded
/v1/emotion
Beyond positive vs. negative sentiment polarity, a vast range of psychological dimensions exist in the realm of emotions/moods/feelings/affect. You can use the Emotion Analysis service to project the text onto a fine-grained, multi-dimensional emotion space which is more natural than a singular majority label. By default, all emotion scores are unbounded (unnormalised, unscaled). The returned analysis lists emotion dimension labels, each with a confidence value from the prediction, and covers the following basic emotion dimensions:
-
anger1D
- 1-dimensional anger scale (> 0). -
fear1D
- 1-dimensional fear scale (> 0). -
shame1D
- 1-dimensional shame scale (> 0). -
surprise1D
- 1-dimensional surprise scale (> 0). -
calm2D
- 2-dimensional scale between calmness (> 0) vs. agitation (< 0). -
happy2D
- 2-dimensional scale between happiness (> 0) vs. sadness (< 0). -
like2D
- 2-dimensional scale between liking (> 0) vs. disliking/disgust (< 0). -
sure2D
- 2-dimensional scale between certainty/sureness (> 0) vs. uncertainty/unsureness (< 0).
POST /v1/emotion
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/emotion
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
Response 200
Emotions: Banded
/v1/emotion/bands
This alternative emotion analysis end point returns all emotion scores in a banded (normalised, discretised) form. The normalised bands are accompanied by scores (0, 5). The returned analysis lists emotion dimensions, each with one of the following labels and scores:
-
ABSENT
- Score:1
. Range: (0, 0). Indicates that no emotion signal was detected. -
WEAK
- Score:1
. Range: (0.0, 0.2). Indicates extremely weak emotion signals. -
FAIR
- Score:2
. Range: (0.2, 0.4). Indicates weak emotion signals. -
MODERATE
- Score:3
. Range: (0.4, 0.6). Indicates fair (neither weak nor strong) emotion signals. -
CONSIDERABLE
- Score:4
. Range: (0.6, 0.8). Indicates strong emotion signals. -
STRONG
- Score:5
. Range: (0.8, 1.0). Indicates extremely strong emotion signals.
POST /v1/emotion/bands
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/emotion/bands
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
Response 200
Topics
/v1/topic
This end point generates for a piece of text a fine-grained topic profile that comprises 40 generic, general-purpose topics and subject headings.
With some topics, more specific subtopics are denoted with the dot operator (.
) (e.g. FINANCE.FOREX
).
The returned topic distribution includes topics whose confidence levels were at least 0.5, and covers the following topic labels:
Topic Label | Description |
ACCIDENTS | All accidents |
ACCIDENTS.AVIATION | Plane accidents |
ACCIDENTS.TRAFFIC | Traffic accidents |
ARTS_CULTURE | arts, culture, cultural events, artists |
BOOKS_LITERATURE | books, literature, authors, bestsellers |
BUSINESS | business |
BUSINESS.EARNINGS | Business earnings and results |
BUSINESS.IPO | Initial public offerings |
BUSINESS.MERGERS_AND_ACQUISITIONS | corporate mergers and acquisitions |
CELEBRITIES | celebrities, celebrity culture, reality shows, talent shows |
COMPUTING | computing, computers, IT, software, hardware, networks, IoT, operating systems, programming |
COMPUTING.AI | Artifical Intelligence |
COMPUTING.BLOCKCHAIN | Blockchain computing |
COMPUTING.CLOUD | Cloud computing |
COMPUTING.IOT | Internet of things |
COMPUTING.SECURITY | Cybersecurity and hacking |
CRIME | crime, policing |
DEFENCE_MILITARY | defence, military, army, war |
EDUCATION | education, schools, universities |
ELECTRONICS | electronics, consumer electronics, gadgets |
EMERGENCIES_DISASTERS | emergencies, catastrophes, natural disasters, man-made disasters, epidemics |
EMPLOYMENT_WORK | employment, work, careers |
ENERGY | General energy topics |
ENERGY.NUCLEAR | Nuclear energy |
ENERGY.OILGAS | Fossiil fuel, oil and gas topics |
ENERGY.RENEWABLE | Green energy amd renewables |
ENTERTAINMENT | entertainment, showbiz, cinema, TV |
ENVIRONMENT | environment, environmental issues, environmentalism |
FASHION_STYLE | fashion, fashion designers, fashion brands, style |
FINANCE | finance, investment, accounting |
FINANCE.ALTCURRENCY | Alternative currencies and cryptocurrencies |
FINANCE.FOREX | foreign exchange, currencies |
FINANCE.MOVEMENT | Movement in investments |
FINANCE.RATING | Rating upgrades and downgrades |
FOOD_COOKING | food, drink, cooking, cuisine |
GAMING | gaming, video games, PC games, gaming platforms |
HEALTHCARE_MEDICINE | health, healthcare, medicine medical conditions, diseases |
HEALTH_FITNESS | health, fitness, well-being, physical exercise |
IMMIGRATION | immigration, immigrants, refugees |
INTELLECTUAL_PROPERTY | ntellectual property, copyright, patents, trademarks |
LAW | law, legal issues, litigation |
MOTORING | motoring, cars, motorcycles |
PERSONAL_FINANCE | Personal finance |
PHARMACEUTICALS | Pharmaceutical Industry issues |
POLITICS | politics, politicians, elections, governments |
REAL_ESTATE_PROPERTY | real estate, property, housing |
RELIGION | religion, religious issues |
RELIGION.CHRISTIANITY | |
RELIGION.ISLAM | |
RELIGION.JUDAISM | |
RETAIL | Retail business topics |
SCIENCE | Sciences |
SCIENCE.BIOTECH | Biotechnology |
SCIENCE.NANOTECH | Nanotechnology |
SOCIAL_MEDIA | Social Media |
SPORTS | Sports |
TECHNOLOGY | General technology |
TERRORISM | terrorism |
TRANSPORTATION | general transportation, traffic, logistics |
TRANSPORTATION.AIR | Airlines and airfreight |
TRANSPORTATION.MARITIME | Shipping |
TRANSPORTATION.RAILWAY | Railways |
TRANSPORTATION.ROAD | Traffic and road logistics |
WEATHER | Weather |
POST /v1/topic
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Consumer Vulnerability
/v1/vulnerability
Consumer Vulnerability is a key concern for a number of industries, especially personal finance services. This end point detects potential signals that the author is in a vulnerable situation. Examples of such signals are engagement with healthcare services or illness, bereavement and relationship break-down.
POST /v1/vulnerability
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/vulnerability
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
Response 200
Speculation
/v1/speculation
Speculative language describes or refers directly or indirectly to irrealis events that are yet to happen.
Speculative expressions can hence cover concepts as diverse as future, certainty, doubt, prediction, wanting, wishes, and waiting, to name a few.
This service detects speculative expressions at the sentence level.
The response contains only 'positive' matches: if no speculative content is detected, the response is []
, accordingly.
Any identified subtypes of speculation are denoted with the dot operator (.
) (e.g. SPECULATION.SUBTYPE
).
POST /v1/speculation
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Risks
/v1/risk
This sentence-level service detects expressions that describe or refer to risk and danger, either directly or indirectly.
The response contains only 'positive' matches: if no risk expressions are detected, the response is hence []
.
Any identified subtypes of risk are denoted with the dot operator (.
) (e.g. RISK.SUBTYPE
).
POST /v1/risk
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Intent
/v1/intent
This sentence-level service detects expressions pertaining to intent, intentions, plans, and decisions that can be detected in text.
The response contains only 'positive' matches: if no intent expressions are detected, the response is []
.
Any identified subtypes of intent are denoted with the dot operator (.
) (e.g. INTENT.SUBTYPE
).
POST /v1/intent
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Advertisements
/v1/ad
Due to the fact that advertisements are spammy and almost invariably positive, they can skew sentiment measurements in a harmful way.
This service allows you to detect texts that are or resemble advertisements.
The returned analysis offers advertisement type labels (AD
vs. NOT_AD
) as well as confidence values from the predictions.
POST /v1/ad
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Comparisons
/v1/comparison
This sentence-level service detects comparative expressions.
The response contains only 'positive' matches: if no comparative expressions are detected, the response is []
.
Any identified finer-grained comparative expressions are denoted with the dot operator (.
) (e.g. COMPARISON.SUBTYPE
).
POST /v1/comparison
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Named Entities
/v1/namedentity
This service detects expressions in the text snippet that refer explicitly or implicitly to
- people and humans in general (
PEOPLE
) - places and locations (
LOCATION
) - organisations and companies (
ORGANISATION
) - times and dates (
TIMEDATE
) - monetary issues (
MONEY
)
For each identified expression (which can be a simple or complex Noun Phrase, Adjective Phrase, or Adverb Phrase), the detected Named Entity types are ranked by their salience (most salient first).
POST /v1/namedentity
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Part-of-Speech Tags
/v1/postag
This service assigns word class types to individual words in the text snippet. The tagset used is largely compatible with the Penn Treebank Tagset.
POST /v1/postag
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Phrase Chunks
/v1/chunkparse
This service detects the boundaries of basic shallow syntactic phrases in the text snippet. For each sentence, simple non-recursive Noun Phrase (NP) and Verb Group (VG) constituents are provided.
POST /v1/chunkparse
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Dependency Parses
/v1/depparse
This service analyses the grammatical structure of each sentence in the text snippet. For each sentence, typed syntactic dependencies between individual words are provided. The parses and the typed dependencies used resemble the labels and types described in the Cambridge Grammar of the English Language.
POST /v1/depparse
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Text Summaries
/v1/summary
This service generates a summary from the input text. The summary consists of sentences delimited by \n
.
POST /v1/summary
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
ratio | 0.6 | number, optional | The size of the summary (i.e. the proportion of the full input text) that is included in the summary. The range is 0 ≤ ratio ≤ 1.0 where 0 returns all sentences and 1.0 includes only the most salient sentence(s) in the input text. |
Response 200
Language Detection
/v1/langdetect
This service returns an ISO 639-1 natural language code for the input text.
POST /v1/langdetect
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Analysis Recipes
/v1/analysis-recipes
☆☆☆PREMIUM USER☆☆☆
Using this end point you can access a library of predefined composite analysis recipes (cf. presets, patches, combos) which fuse multiple analysis requests into a single one (cf. multicall requests, joint requests, multibody responses). For example, you could execute both sentiment and emotion analysis with a single joint request instead of calling the sentiment and emotion end points individually.
Coverage
The recipes support analysis combinations that are popular amongst our users. If you require custom recipes beyond what is listed in the present API documentation, please contact us.
Analysis Groups
The analysis recipes combine individual single-call analysis end points in the form of higher-level, thematically organised analysis groups as follows:
Analysis Group | Single-call End Points Subsumed | Description |
affect
|
/emotion
/sentiment
| All analyses that involve subjective, non-factual, and affective information. |
future
|
/intent
/risk
/speculation
| All analyses that involve irrealis expressions and future-looking statements. |
referents
|
/namedentity
| All analyses that involve entity mentions and references at the term/keyword/entity level. |
topics
|
/topic
| All analyses that involve higher-level topics, subject headings, and themes. |
The names of the analysis recipes are composed of these analysis group names.
Response Fields
The response fields are compatible with those returned by the single-call end points described elsewhere in the present API documentation. However, because the responses from joint multicall requests may include data spanning multiple structural levels in text, the following additional structural wrapper fields are used across the analyses (where relevant):
Structural Wrapper in Response | Description |
document
| The document-level analyses executed. |
entity
| A list of entity mentions, each containing the entity-level analyses executed. |
namedentity
| A list of Named Entities, each containing the entity-level analyses executed. |
sentence
| A list of sentences, each containing the sentence-level analyses executed. |
POST /v1/analysis-recipes/affect-1
Analyses Executed | Structural Wrappers |
---|---|
emotion sentiment | document |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/analysis-recipes/affect-2
Analyses Executed | Structural Wrappers |
---|---|
emotion sentiment | document entity sentence |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/analysis-recipes/affect-referents-1
Analyses Executed | Structural Wrappers |
---|---|
namedentity sentiment | document namedentity |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/analysis-recipes/affect-referents-topics-1
Analyses Executed | Structural Wrappers |
---|---|
emotion namedentity sentiment topic | document namedentity |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/analysis-recipes/affect-topics-1
Analyses Executed | Structural Wrappers |
---|---|
sentiment topic | document |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/analysis-recipes/affect-topics-2
Analyses Executed | Structural Wrappers |
---|---|
emotion sentiment topic | document |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/analysis-recipes/future-1
Analyses Executed | Structural Wrappers |
---|---|
intent risk speculation | sentence |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v1/analysis-recipes/referents-topics-1
Analyses Executed | Structural Wrappers |
---|---|
namedentity topic | document namedentity |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Resources: Sentiment
/v1/resources/lexicons/sentiment/{lexicon}
This end point allows you to manage the underlying lexical resources that are used for the sentiment analysis on your account. By fine-tuning and customising sentiment lexica (adjectives, adverbs, nouns, verbs), you can adapt the sentiment analysis to a particular genre, domain, topic, or use case beyond the default, generic, general-purpose resources.
POST /v1/resources/lexicons/sentiment/{lexicon}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | quasicool | string, required | The entry to be stored in the lexicon. |
polarity | pos | string, required | Sentiment polarity p of the lexicon entry where p ∈ { pos | ntr | neg }. |
reverse | equ | string, required | Sentiment reversal r of the lexicon entry where r ∈ { rev | equ }. |
Response 201
GET /v1/resources/lexicons/sentiment/{lexicon}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
Response 200
"text": "quasi-intelligent",
"polarity": "pos",
"id": "51b0630a7a233d39005ecc1e"
}, {
"text": "unemployment",
"polarity": "ntr",
"id": "51b0630a7a233d39005ecc1e"
}]
GET /v1/resources/lexicons/sentiment/{lexicon}/{objectID}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
objectID | string, required | Unique ID of resource. |
Response 200
"text": "quasi-intelligent",
"polarity": "pos",
"id": "51b0630a7a233d39005ecc1e"
}
DELETE /v1/resources/lexicons/sentiment/{lexicon}/{objectID}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
objectID | string, required | Unique ID of resource. |
Response 200
Resources: Topics
/v1/resources/topics/keywords
This end point allows you to expand the underlying resources that are used for the topic classification services on your account.
To go beyond the default, generic, general-purpose topic classifiers (see the /topic
section), you can upload simple weighted expressions for specific words and phrases to guarantee crisp, unconditional topic tags.
POST /v1/resources/topics/keywords
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | roasted peanuts | string, required | The expression (word or phrase) to match. |
classLabel | YUMMY | string, required | The label (tag) to apply to the matched text. |
weight | 65 | number, optional | The weight of the matched text. Positive values boost and negative values suppress the importance of the class label in topic tagging. |
Response 201
GET /v1/resources/topics/keywords
Response 200
"id": "57a08990954324034f92fe0e",
"classLabel": "YUMMY",
"text": "roasted peanuts",
"weight": 400
}, {
"id": "57a089ab954324034f92fe10",
"classLabel": "YUCKY",
"text": "salted peanuts",
"weight": 12
}]
GET /v1/resources/topics/keywords/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
"id": "57a08990954324034f92fe0e",
"classLabel": "YUMMY",
"text": "roasted peanuts",
"weight": 400
}
DELETE /v1/resources/topics/keywords/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
Resources: Named Entities
/v1/resources/namedentity/assertions
This end point allows you to manage the resources that are used for the Named Entity recognition services on your account.
The resources support simple assertions that match specific words and phrases to guarantee crisp, unconditional Named Entity tags.
Assertion-based matching takes priority over the default, generic, general-purpose Named Entity classifiers (see the /namedentity
section).
POST /v1/resources/namedentity/assertions
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | text analytics | string, required | The text (word or phrase) to match. |
classLabel | TECH.COOL | string, required | The label (tag) to apply to all Named Entities that match the specified text. |
Response 201
GET /v1/resources/namedentity/assertions
Response 200
"id": "5784e2759543246479a8633e",
"classLabel": "TECH.COOL",
"text": "text analytics"
}, {
"id": "5784e24d9543246479a8633a",
"classLabel": "ORG.COMPANY.EXCELLENT",
"text": "TheySay"
}]
GET /v1/resources/namedentity/assertions/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
"id": "5784e2759543246479a8633e",
"classLabel": "TECH.COOL",
"text": "text analytics"
}
DELETE /v1/resources/namedentity/assertions/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
Resources: Entity Taxonomies
/v1/resources/taxonomies/entity
This end point allows you to manage the taxonomic resources that are used in the entity categorisation on your account. By adding pattern matching rules for taxonomic categories, you can categorise entity mentions into any desired taxonomic levels beyond the default head noun-based grouping.
POST /v1/resources/taxonomies/entity
Attributes
Name | Example | Type | Description |
---|---|---|---|
matchPattern | (price(s)?|bill(s)?|offer(s)?|expensive|rip(-| )?off) | string, required | A regex pattern for capturing entity mentions. |
category | PRICE | string, required | The taxonomic category under which matched entity mentions should be categorised. |
Response 201
GET /v1/resources/taxonomies/entity
Response 200
"matchPattern": "(beer|lager|bitter)",
"category": "FOOD.DRINK",
"id": "51b0781f7a233d48005ecc20"
}, {
"matchPattern": "pizza(s)?",
"category": "FOOD.PIZZA",
"id": "51b0780a7a233d4e005ecc1f"
}]
GET /v1/resources/taxonomies/entity/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
"matchPattern": "(beer|lager|bitter)",
"category": "FOOD.DRINK",
"id": "51b0781f7a233d48005ecc20"
}
DELETE /v1/resources/taxonomies/entity/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
Account Usage
/v1/usagestats
You can monitor your API usage within a specific time period between two time stamps. The timestamps expect values that are compliant with the [W3C](http://www.w3.org/TR/NOTE-datetime) date and time format.
GET /v1/usagestats
Parameters
Name | Example | Type | Description |
---|---|---|---|
from | 2013-02-01 | string, required | The W3C start value for the query. |
to | 2013-02-13 | string, optional | The W3C end value for the query. If omitted, defaults to now .
|
groupby | date | string, optional | Specify the fields to group the results by. Possible values: date , method , path , status , ip . These can be combined
as a comma separated list, e.g. groupby=date,ip . The all value can be used a shorthand. Defaults to date .
|
aggregate | duration | string, optional | Specify the aggregates. Possible values count , length , duration . These can be combined as a comma separated list, e.g.
aggregate=length,duration . The all value can be used a shorthand. Defaults to count .
|
Response 200
Version 2 API
Sentiment: English
/v2/sentiment
Sentiment, a dimension of non-factuality in language that is closely related to subjectivity/affect/emotion/moods/feelings, reflects psychological evaluation with the following fundamental poles:
-
positive
(~ good / pros / favourable / desirable / recommended / thumbs up /...) vs -
negative
(~ bad / cons / unfavourable / undesirable / not recommended / thumbs down /...)
You can use the Sentiment Analysis service to discover and score deep, fine-grained sentiments and opinions in text. The analysis, output by a human-like sentiment reasoning algorithm, captures both explicit "author sentiment" as well as general, implicit "reader-sentiment" beyond opinions that ultimately stems from affective commons sense as well as issues and events that are generally considered to be good vs. bad in the world.
The returned analysis includes majority sentiment labels, fine-grained 3-way positive/neutral/negative percentage scores, and other useful auxiliary fields.
POST /v2/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v2/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v2/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | entity | string, required | Enables entity-level sentiment analysis. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
targets | market|business|opportunity|cost | string, optional | Match expression for target entities. |
matching | head | string, optional | Matching mode. |
Response 200
POST /v2/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | entityaggregate | string, required | Enables sentiment analysis for entity aggregates. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v2/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | entityrelation | string, required | Enables relational entity-level sentiment analysis. |
Response 200
POST /v2/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | word | string, required | Enables document-level sentiment flow analysis. |
Response 200
Sentiment: Multilingual
/v2/multilingual/sentiment
Beyond English, the API offers sentiment analysis for German (de
) and Spanish (es
) at the document and the sentence levels.
POST /v2/multilingual/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
language | de | string, required | The ISO 639-1 natural language code for the input text. See http://www.loc.gov/standards/iso639-2/php/code_list.php for the codes. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
POST /v2/multilingual/sentiment
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
language | de | string, required | The ISO 639-1 natural language code for the input text. See http://www.loc.gov/standards/iso639-2/php/code_list.php for the codes. |
bias | {"positive"3.5, "neutral":2.7, "negative":18 } | object, optional | Sentiment coefficient d (0 ≤ d ≤ 100) to control the (in)sensitivity of the sentiment analysis towards sentiment polarity p where p ∈ { positive | neutral | negative }). |
Response 200
Emotions: Unbounded
/v2/emotion
Beyond positive vs. negative sentiment polarity, a vast range of psychological dimensions exist in the realm of emotions/moods/feelings/affect. You can use the Emotion Analysis service to project the text onto a fine-grained, multi-dimensional emotion space which is more natural than a singular majority label. By default, all emotion scores are unbounded (unnormalised, unscaled). The returned analysis lists emotion dimension labels, each with a confidence value from the prediction, and covers the following basic emotion dimensions:
-
anger1D
- 1-dimensional anger scale (> 0). -
fear1D
- 1-dimensional fear scale (> 0). -
shame1D
- 1-dimensional shame scale (> 0). -
surprise1D
- 1-dimensional surprise scale (> 0). -
calm2D
- 2-dimensional scale between calmness (> 0) vs. agitation (< 0). -
happy2D
- 2-dimensional scale between happiness (> 0) vs. sadness (< 0). -
like2D
- 2-dimensional scale between liking (> 0) vs. disliking/disgust (< 0). -
sure2D
- 2-dimensional scale between certainty/sureness (> 0) vs. uncertainty/unsureness (< 0).
POST /v2/emotion
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/emotion
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
Response 200
Emotions: Banded
/v2/emotion/bands
This alternative emotion analysis end point returns all emotion scores in a banded (normalised, discretised) form. The normalised bands are accompanied by scores (0, 5). The returned analysis lists emotion dimensions, each with one of the following labels and scores:
-
ABSENT
- Score:1
. Range: (0, 0). Indicates that no emotion signal was detected. -
WEAK
- Score:1
. Range: (0.0, 0.2). Indicates extremely weak emotion signals. -
FAIR
- Score:2
. Range: (0.2, 0.4). Indicates weak emotion signals. -
MODERATE
- Score:3
. Range: (0.4, 0.6). Indicates fair (neither weak nor strong) emotion signals. -
CONSIDERABLE
- Score:4
. Range: (0.6, 0.8). Indicates strong emotion signals. -
STRONG
- Score:5
. Range: (0.8, 1.0). Indicates extremely strong emotion signals.
POST /v2/emotion/bands
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/emotion/bands
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
Response 200
Topics
/v2/topic
This end point generates for a piece of text a fine-grained topic profile that comprises 40 generic, general-purpose topics and subject headings.
With some topics, more specific subtopics are denoted with the dot operator (.
) (e.g. FINANCE.FOREX
).
The returned topic distribution includes topics whose confidence levels were at least 0.5, and covers the following topic labels:
Topic Label | Description |
ACCIDENTS | All accidents |
ACCIDENTS.AVIATION | Plane accidents |
ACCIDENTS.TRAFFIC | Traffic accidents |
ARTS_CULTURE | arts, culture, cultural events, artists |
BOOKS_LITERATURE | books, literature, authors, bestsellers |
BUSINESS | business |
BUSINESS.EARNINGS | Business earnings and results |
BUSINESS.IPO | Initial public offerings |
BUSINESS.MERGERS_AND_ACQUISITIONS | corporate mergers and acquisitions |
CELEBRITIES | celebrities, celebrity culture, reality shows, talent shows |
COMPUTING | computing, computers, IT, software, hardware, networks, IoT, operating systems, programming |
COMPUTING.AI | Artifical Intelligence |
COMPUTING.BLOCKCHAIN | Blockchain computing |
COMPUTING.CLOUD | Cloud computing |
COMPUTING.IOT | Internet of things |
COMPUTING.SECURITY | Cybersecurity and hacking |
CRIME | crime, policing |
DEFENCE_MILITARY | defence, military, army, war |
EDUCATION | education, schools, universities |
ELECTRONICS | electronics, consumer electronics, gadgets |
EMERGENCIES_DISASTERS | emergencies, catastrophes, natural disasters, man-made disasters, epidemics |
EMPLOYMENT_WORK | employment, work, careers |
ENERGY | General energy topics |
ENERGY.NUCLEAR | Nuclear energy |
ENERGY.OILGAS | Fossiil fuel, oil and gas topics |
ENERGY.RENEWABLE | Green energy amd renewables |
ENTERTAINMENT | entertainment, showbiz, cinema, TV |
ENVIRONMENT | environment, environmental issues, environmentalism |
FASHION_STYLE | fashion, fashion designers, fashion brands, style |
FINANCE | finance, investment, accounting |
FINANCE.ALTCURRENCY | Alternative currencies and cryptocurrencies |
FINANCE.FOREX | foreign exchange, currencies |
FINANCE.MOVEMENT | Movement in investments |
FINANCE.RATING | Rating upgrades and downgrades |
FOOD_COOKING | food, drink, cooking, cuisine |
GAMING | gaming, video games, PC games, gaming platforms |
HEALTHCARE_MEDICINE | health, healthcare, medicine medical conditions, diseases |
HEALTH_FITNESS | health, fitness, well-being, physical exercise |
IMMIGRATION | immigration, immigrants, refugees |
INTELLECTUAL_PROPERTY | ntellectual property, copyright, patents, trademarks |
LAW | law, legal issues, litigation |
MOTORING | motoring, cars, motorcycles |
PERSONAL_FINANCE | Personal finance |
PHARMACEUTICALS | Pharmaceutical Industry issues |
POLITICS | politics, politicians, elections, governments |
REAL_ESTATE_PROPERTY | real estate, property, housing |
RELIGION | religion, religious issues |
RELIGION.CHRISTIANITY | |
RELIGION.ISLAM | |
RELIGION.JUDAISM | |
RETAIL | Retail business topics |
SCIENCE | Sciences |
SCIENCE.BIOTECH | Biotechnology |
SCIENCE.NANOTECH | Nanotechnology |
SOCIAL_MEDIA | Social Media |
SPORTS | Sports |
TECHNOLOGY | General technology |
TERRORISM | terrorism |
TRANSPORTATION | general transportation, traffic, logistics |
TRANSPORTATION.AIR | Airlines and airfreight |
TRANSPORTATION.MARITIME | Shipping |
TRANSPORTATION.RAILWAY | Railways |
TRANSPORTATION.ROAD | Traffic and road logistics |
WEATHER | Weather |
POST /v2/topic
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Consumer Vulnerability
/v2/vulnerability
Consumer Vulnerability is a key concern for a number of industries, especially personal finance services. This end point detects potential signals that the author is in a vulnerable situation. Examples of such signals are engagement with healthcare services or illness, bereavement and relationship break-down.
POST /v2/vulnerability
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/vulnerability
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
level | sentence | string, required | Enables sentence-level analysis. |
Response 200
Speculation
/v2/speculation
Speculative language describes or refers directly or indirectly to irrealis events that are yet to happen.
Speculative expressions can hence cover concepts as diverse as future, certainty, doubt, prediction, wanting, wishes, and waiting, to name a few.
This service detects speculative expressions at the sentence level.
The response contains only 'positive' matches: if no speculative content is detected, the response is []
, accordingly.
Any identified subtypes of speculation are denoted with the dot operator (.
) (e.g. SPECULATION.SUBTYPE
).
POST /v2/speculation
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Risks
/v2/risk
This sentence-level service detects expressions that describe or refer to risk and danger, either directly or indirectly.
The response contains only 'positive' matches: if no risk expressions are detected, the response is hence []
.
Any identified subtypes of risk are denoted with the dot operator (.
) (e.g. RISK.SUBTYPE
).
POST /v2/risk
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Intent
/v2/intent
This sentence-level service detects expressions pertaining to intent, intentions, plans, and decisions that can be detected in text.
The response contains only 'positive' matches: if no intent expressions are detected, the response is []
.
Any identified subtypes of intent are denoted with the dot operator (.
) (e.g. INTENT.SUBTYPE
).
POST /v2/intent
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Advertisements
/v2/ad
Due to the fact that advertisements are spammy and almost invariably positive, they can skew sentiment measurements in a harmful way.
This service allows you to detect texts that are or resemble advertisements.
The returned analysis offers advertisement type labels (AD
vs. NOT_AD
) as well as confidence values from the predictions.
POST /v2/ad
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Comparisons
/v2/comparison
This sentence-level service detects comparative expressions.
The response contains only 'positive' matches: if no comparative expressions are detected, the response is []
.
Any identified finer-grained comparative expressions are denoted with the dot operator (.
) (e.g. COMPARISON.SUBTYPE
).
POST /v2/comparison
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Named Entities
/v2/namedentity
This service detects expressions in the text snippet that refer explicitly or implicitly to
- people and humans in general (
PEOPLE
) - places and locations (
LOCATION
) - organisations and companies (
ORGANISATION
) - times and dates (
TIMEDATE
) - monetary issues (
MONEY
)
For each identified expression (which can be a simple or complex Noun Phrase, Adjective Phrase, or Adverb Phrase), the detected Named Entity types are ranked by their salience (most salient first).
POST /v2/namedentity
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Part-of-Speech Tags
/v2/postag
This service assigns word class types to individual words in the text snippet. The tagset used is largely compatible with the Penn Treebank Tagset.
POST /v2/postag
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Phrase Chunks
/v2/chunkparse
This service detects the boundaries of basic shallow syntactic phrases in the text snippet. For each sentence, simple non-recursive Noun Phrase (NP) and Verb Group (VG) constituents are provided.
POST /v2/chunkparse
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Dependency Parses
/v2/depparse
This service analyses the grammatical structure of each sentence in the text snippet. For each sentence, typed syntactic dependencies between individual words are provided. The parses and the typed dependencies used resemble the labels and types described in the Cambridge Grammar of the English Language.
POST /v2/depparse
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Text Summaries
/v2/summary
This service generates a summary from the input text. The summary consists of sentences delimited by \n
.
POST /v2/summary
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
ratio | 0.6 | number, optional | The size of the summary (i.e. the proportion of the full input text) that is included in the summary. The range is 0 ≤ ratio ≤ 1.0 where 0 returns all sentences and 1.0 includes only the most salient sentence(s) in the input text. |
Response 200
Language Detection
/v2/langdetect
This service returns an ISO 639-1 natural language code for the input text.
POST /v2/langdetect
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Analysis Recipes
/v2/analysis-recipes
☆☆☆PREMIUM USER☆☆☆
Using this end point you can access a library of predefined composite analysis recipes (cf. presets, patches, combos) which fuse multiple analysis requests into a single one (cf. multicall requests, joint requests, multibody responses). For example, you could execute both sentiment and emotion analysis with a single joint request instead of calling the sentiment and emotion end points individually.
Coverage
The recipes support analysis combinations that are popular amongst our users. If you require custom recipes beyond what is listed in the present API documentation, please contact us.
Analysis Groups
The analysis recipes combine individual single-call analysis end points in the form of higher-level, thematically organised analysis groups as follows:
Analysis Group | Single-call End Points Subsumed | Description |
affect
|
/emotion
/sentiment
| All analyses that involve subjective, non-factual, and affective information. |
future
|
/intent
/risk
/speculation
| All analyses that involve irrealis expressions and future-looking statements. |
referents
|
/namedentity
| All analyses that involve entity mentions and references at the term/keyword/entity level. |
topics
|
/topic
| All analyses that involve higher-level topics, subject headings, and themes. |
The names of the analysis recipes are composed of these analysis group names.
Response Fields
The response fields are compatible with those returned by the single-call end points described elsewhere in the present API documentation. However, because the responses from joint multicall requests may include data spanning multiple structural levels in text, the following additional structural wrapper fields are used across the analyses (where relevant):
Structural Wrapper in Response | Description |
document
| The document-level analyses executed. |
entity
| A list of entity mentions, each containing the entity-level analyses executed. |
namedentity
| A list of Named Entities, each containing the entity-level analyses executed. |
sentence
| A list of sentences, each containing the sentence-level analyses executed. |
POST /v2/analysis-recipes/affect-1
Analyses Executed | Structural Wrappers |
---|---|
emotion sentiment | document |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/analysis-recipes/affect-2
Analyses Executed | Structural Wrappers |
---|---|
emotion sentiment | document entity sentence |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/analysis-recipes/affect-referents-1
Analyses Executed | Structural Wrappers |
---|---|
namedentity sentiment | document namedentity |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/analysis-recipes/affect-referents-topics-1
Analyses Executed | Structural Wrappers |
---|---|
emotion namedentity sentiment topic | document namedentity |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/analysis-recipes/affect-topics-1
Analyses Executed | Structural Wrappers |
---|---|
sentiment topic | document |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/analysis-recipes/affect-topics-2
Analyses Executed | Structural Wrappers |
---|---|
emotion sentiment topic | document |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/analysis-recipes/future-1
Analyses Executed | Structural Wrappers |
---|---|
intent risk speculation | sentence |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
POST /v2/analysis-recipes/referents-topics-1
Analyses Executed | Structural Wrappers |
---|---|
namedentity topic | document namedentity |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | ...your...text... | string, required | The text that you want to analyse. |
Response 200
Resources: Sentiment
/v2/resources/lexicons/sentiment/{lexicon}
This end point allows you to manage the underlying lexical resources that are used for the sentiment analysis on your account. By fine-tuning and customising sentiment lexica (adjectives, adverbs, nouns, verbs), you can adapt the sentiment analysis to a particular genre, domain, topic, or use case beyond the default, generic, general-purpose resources.
POST /v2/resources/lexicons/sentiment/{lexicon}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | quasicool | string, required | The entry to be stored in the lexicon. |
polarity | pos | string, required | Sentiment polarity p of the lexicon entry where p ∈ { pos | ntr | neg }. |
reverse | equ | string, required | Sentiment reversal r of the lexicon entry where r ∈ { rev | equ }. |
Response 201
GET /v2/resources/lexicons/sentiment/{lexicon}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
Response 200
"text": "quasi-intelligent",
"polarity": "pos",
"id": "51b0630a7a233d39005ecc1e"
}, {
"text": "unemployment",
"polarity": "ntr",
"id": "51b0630a7a233d39005ecc1e"
}]
GET /v2/resources/lexicons/sentiment/{lexicon}/{objectID}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
objectID | string, required | Unique ID of resource. |
Response 200
"text": "quasi-intelligent",
"polarity": "pos",
"id": "51b0630a7a233d39005ecc1e"
}
DELETE /v2/resources/lexicons/sentiment/{lexicon}/{objectID}
Parameters
Name | Type | Description |
---|---|---|
lexicon | string, required | Possible values: adjectives , adverbs , nouns , verbs . |
objectID | string, required | Unique ID of resource. |
Response 200
Resources: Topics
/v2/resources/topics/keywords
This end point allows you to expand the underlying resources that are used for the topic classification services on your account.
To go beyond the default, generic, general-purpose topic classifiers (see the /topic
section), you can upload simple weighted expressions for specific words and phrases to guarantee crisp, unconditional topic tags.
POST /v2/resources/topics/keywords
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | roasted peanuts | string, required | The expression (word or phrase) to match. |
classLabel | YUMMY | string, required | The label (tag) to apply to the matched text. |
weight | 65 | number, optional | The weight of the matched text. Positive values boost and negative values suppress the importance of the class label in topic tagging. |
Response 201
GET /v2/resources/topics/keywords
Response 200
"id": "57a08990954324034f92fe0e",
"classLabel": "YUMMY",
"text": "roasted peanuts",
"weight": 400
}, {
"id": "57a089ab954324034f92fe10",
"classLabel": "YUCKY",
"text": "salted peanuts",
"weight": 12
}]
GET /v2/resources/topics/keywords/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
"id": "57a08990954324034f92fe0e",
"classLabel": "YUMMY",
"text": "roasted peanuts",
"weight": 400
}
DELETE /v2/resources/topics/keywords/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
Resources: Named Entities
/v2/resources/namedentity/assertions
This end point allows you to manage the resources that are used for the Named Entity recognition services on your account.
The resources support simple assertions that match specific words and phrases to guarantee crisp, unconditional Named Entity tags.
Assertion-based matching takes priority over the default, generic, general-purpose Named Entity classifiers (see the /namedentity
section).
POST /v2/resources/namedentity/assertions
Attributes
Name | Example | Type | Description |
---|---|---|---|
text | text analytics | string, required | The text (word or phrase) to match. |
classLabel | TECH.COOL | string, required | The label (tag) to apply to all Named Entities that match the specified text. |
Response 201
GET /v2/resources/namedentity/assertions
Response 200
"id": "5784e2759543246479a8633e",
"classLabel": "TECH.COOL",
"text": "text analytics"
}, {
"id": "5784e24d9543246479a8633a",
"classLabel": "ORG.COMPANY.EXCELLENT",
"text": "TheySay"
}]
GET /v2/resources/namedentity/assertions/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
"id": "5784e2759543246479a8633e",
"classLabel": "TECH.COOL",
"text": "text analytics"
}
DELETE /v2/resources/namedentity/assertions/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
Resources: Entity Taxonomies
/v2/resources/taxonomies/entity
This end point allows you to manage the taxonomic resources that are used in the entity categorisation on your account. By adding pattern matching rules for taxonomic categories, you can categorise entity mentions into any desired taxonomic levels beyond the default head noun-based grouping.
POST /v2/resources/taxonomies/entity
Attributes
Name | Example | Type | Description |
---|---|---|---|
matchPattern | (price(s)?|bill(s)?|offer(s)?|expensive|rip(-| )?off) | string, required | A regex pattern for capturing entity mentions. |
category | PRICE | string, required | The taxonomic category under which matched entity mentions should be categorised. |
Response 201
GET /v2/resources/taxonomies/entity
Response 200
"matchPattern": "(beer|lager|bitter)",
"category": "FOOD.DRINK",
"id": "51b0781f7a233d48005ecc20"
}, {
"matchPattern": "pizza(s)?",
"category": "FOOD.PIZZA",
"id": "51b0780a7a233d4e005ecc1f"
}]
GET /v2/resources/taxonomies/entity/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
"matchPattern": "(beer|lager|bitter)",
"category": "FOOD.DRINK",
"id": "51b0781f7a233d48005ecc20"
}
DELETE /v2/resources/taxonomies/entity/{objectID}
Parameters
Name | Type | Description |
---|---|---|
objectID | string, required | Unique ID of resource. |
Response 200
Account Usage
/v2/usagestats
You can monitor your API usage within a specific time period between two time stamps. The timestamps expect values that are compliant with the [W3C](http://www.w3.org/TR/NOTE-datetime) date and time format.
GET /v2/usagestats
Parameters
Name | Example | Type | Description |
---|---|---|---|
from | 2013-02-01 | string, required | The W3C start value for the query. |
to | 2013-02-13 | string, optional | The W3C end value for the query. If omitted, defaults to now .
|
groupby | date | string, optional | Specify the fields to group the results by. Possible values: date , method , path , status , ip . These can be combined
as a comma separated list, e.g. groupby=date,ip . The all value can be used a shorthand. Defaults to date .
|
aggregate | duration | string, optional | Specify the aggregates. Possible values count , length , duration . These can be combined as a comma separated list, e.g.
aggregate=length,duration . The all value can be used a shorthand. Defaults to count .
|