Concept Details Services

The services in this section are dedicated to special concept extraction possibilities:

  • You can request detailed information about a concept from the extraction model or

  • receive concept suggestions, where labels of the concept match the search string.

Find details in the following topics:

Concept Suggestion Request Service

Description

This method allows you to send a string to the service and receive concept suggestions where labels of the concept match the search string.

URL: /extractor/api/suggest

Content-Type

application/x-www-form-urlencoded

Request

Supported Methods

GET

POST

HTTP Parameters

Parameter

Type

Required

Description

conceptSchemeFilters

Array of String

false

Concept scheme URI filters.

customAttributes

Array of CustomProperty

false

Filter: List of custom attributes (their URIs and values) to be used as filter for the search request.

customClasses

Array of String

false

Filter: List of custom classes (their URIs) to be used as filter for the search request.

customRelations

Array of CustomProperty

false

Filter: List of custom relations (property URI and object URI) to be used as filter for the search request.

filterOperator

String

false

The operator type (and|or) to connect the different custom class/attribute/property filters (default = or)

language

String

true

Language of the results (en|de|es|fr|...)

numberOfConcepts

int

false

Number of results (default = 10)

offset

int

false

Row offset

projectId

String

true

Thesaurus projectId

properties

Array of String

false

Array of custom class attributes and relations that will be fetched by providing their property URIs as input. Furthermore it supports http://www.w3.org/1999/02/22-rdf-syntax-ns#type.

Set to all to fetch all properties.

searchParameters

Array of SearchParameter

false

Advanced search parameters allowing to specify the label type, boost factor, and matching strategy. Is used together with searchString.

searchString

String

false

Text fragment to search concepts for. If searchString and searchParameters are not set, all concepts are returned which can be combined with filters.

showMatchingDetails

boolean

false

Shows matching details for searchParameters, default = false

useBlacklisted

boolean

false

Include blacklisted concepts (default = false)

useCompoundWord

boolean

false

Only include concepts where the searchString is a compound word (default = false)

useSkosBoost

boolean

false

Use custom scoring for ordering the results.

Array of Custom Property for Parameter customAttributes

Attribute

Type

Comment

property

String

Property

value

String

Value

Array of Custom Property for Parameter searchParameters

Attribute

Type

Comment

boost

Float

Solr boost factor. (Optional - if boost factor is set, consider to set useCustomScoring to false to disable internal custom sorting)

customLabel

String

In case labelType CUSTOM_LABEL is used. (Optional)

labelType

LabelType

Type of the label. Use PREF_LABEL, ALT_LABEL, HIDDEN_LABEL, or ALL (Default: ALL) - use CUSTOM_LABEL for custom properties which requires the parameter customLabel to be set. prefLabel | altLabel | hiddenLabel | customLabel | label

matchingStrategy

MatchingStrategy

Matching Strategy for indexed fields. Use DEFAULT, REGEX, REGEX_I, SENSITIVE, or EXACT. (Default: DEFAULT) DEFAULT | REGEX | REGEX_I | SENSITIVE | EXACT

Use REGEX_I for case insensitive matching.

searchString

String

Search string. (Mandatory)

ResponseContent-Type

application/json

Returns

Attribute

Type

Comment

suggestedConcepts

Array of SuggestedConcepts

Message

success

boolean

Success

message

String

Reports the exection time of the query

total

long

The number of results returned

Array of SuggestedConcepts

Click here to expand...

Attribute

Type

Comment

altLabels

Array of String

Alternative labels

broaderConcepts

Array of String

URIs of all direct broader concepts.

conceptSchemes

Array of ThesaurusConceptScheme

The concept schemes this concept resides in.

corporaScore

double

Relevance score - e.g. when extracted from a text.

customAttributes

Array of CustomAttribute

Custom attributes

customRelations

Array of CustomRelation

Custom relations

customSchemeTypes

Array of CustomSchemeType

URIs of the custom types assigned to the concept.

frequencyInDocument

int

Frequency of the concept in the text.

frequencyInDocuments

int

Frequency of the concept in the text.

hiddenLabels

Array of String

Hidden labels

highlights

Array of Highlight

The matching text returned by the index.

id

String

Concept ID

language

String

Language of the prefLabel, altLabels and hiddenLabels of this localized view of the concept.

matchingLabel

String

The concept label that has matched the search label.

matchingLabels

Array of MatchingLabel

Matching labels

prefLabel

String

Preferred label

project

String

UUID of the containing PoolParty project.

relatedConcepts

Array of String

URIs of all related concepts

score

double

Normalized relevance score - e.g. when extracted from a text

shadowConceptTerms

Array of ExtractedTerm

transitiveBroaderConcepts

Array of String

URIs of all transitive broader concepts.

transitiveBroaderTopConcepts

Array of String

URIs of all top concepts that this concept is connected to via a transitive broader-chain.

uri

String

Uniform resource identifier

wordForms

Array of String

Lemmatized word forms

Arrays

Click here to expand...

ThesaurusConceptScheme

ConceptScheme from a PoolParty thesaurus project - acts as a container for concepts

Attribute

Type

Comment

title

String

The localized title of this concept scheme

uri

String

Uniform resource identifier

CustomAttribute

Attribute

Type

Comment

literal

Literal

Literal

property

String

Property

CustomRelation

Attribute

Type

Comment

object

String

Object

property

String

Property

CustomSchemeType

(PoolParty) concept scheme - acts as a container for concepts

Attribute

Type

Comment

title

String

The name of this custom scheme type

uri

String

Uniform resource identifier

ExtractedTerm

Phrase extracted from a text that does not match any Concepts

Attribute

Type

Comment

corporaScore

double

Corpora score

frequencyInDocument

int

Frequency within the document where it was extracted

frequencyInDocuments

int

Frequency within the documents where it was extracted

score

double

Relevance score

textValue

String

The term phrase

Example

Request:

http://test.semantic-web.at/extractor/api/suggest?projectId=1DAB156D-F01F-0001-ABCE-16301D4023C0&language=en&searchString=Aspirin

JSON Result:

{
        "success": true,
        "suggestedConcepts": [
                {
                        "matchingLabel": "<em>Aspirin</em>-Induced Asthmas",
                        "score": 10,
                        "uri": "http://www.nlm.nih.gov/mesh/D055963",
                        "conceptSchemes": [
                                {
                                        "title": "Diseases",
                                        "uri": "http://www.nlm.nih.gov/mesh/Diseases"
                                }
                        ],
                        "prefLabel": "Asthma, Aspirin-Induced",
                        "altLabels": [
                                "Aspirin-Induced Asthmas",
                                "Asthmas, NSAID-induced",
                                "Asthma, Aspirin Induced",
                                "Asthma Syndrome, Aspirin-Induced",
                                "Induced Asthmas, Aspirin",
                                "Asthmas, Aspirin-Induced",
                                "Induced Asthma, Aspirin",
                                "Syndrome, Aspirin-Induced Asthma",
                                "Asthma Syndromes, Aspirin-Induced",
                                "Aspirin Induced Asthma Syndrome",
                                "Aspirin Induced Asthma",
                                "Aspirin-Induced Asthma Syndromes",
                                "Asthma, NSAID-induced",
                                "Aspirin-Induced Asthma",
                                "Syndromes, Aspirin-Induced Asthma",
                                "Aspirin Induced Asthmas",
                                "Asthmas, Aspirin Induced",
                                "Aspirin-Induced Asthma Syndrome",
                                "NSAID-induced Asthmas",
                                "NSAID-induced Asthma",
                                "Asthma, NSAID induced"
                        ],
                        "project": "1DAB156D-F01F-0001-ABCE-16301D4023C0",
                        "language": "en",
                        "id": "1DAB156D-F01F-0001-ABCE-16301D4023C0:http://www.nlm.nih.gov/mesh/D055963@en"
                },
                {
                        "matchingLabel": "<em>Aspirin</em> Tolerance Tests",
                        "score": 7,
                        "uri": "http://www.nlm.nih.gov/mesh/D001760",
                        "conceptSchemes": [
                                {
                                        "title": "Phenomena and Processes",
                                        "uri": "http://www.nlm.nih.gov/mesh/Phenomena_and_Processes"
                                },
                                {
                                        "title": "Analytical, Diagnostic and Therapeutic Techniques and Equipment",
                                        "uri": "http://www.nlm.nih.gov/mesh/Analytical_Diagnostic_and_Therapeutic_Techniques_and_Equipment"
                                }
                        ],
                        "prefLabel": "Bleeding Time",
                        "altLabels": [
                                "Bleeding Time, Template",
                                "Bleeding Times, Template",
                                "Method, Ivy",
                                "Bleeding Times",
                                "Aspirin Tolerance Tests",
                                "Tolerance Tests, Aspirin",
                                "Tolerance Test, Aspirin",
                                "Method, Duke",
                                "Time, Template Bleeding",
                                "Template Bleeding Time",
                                "Times, Template Bleeding",
                                "Times, Bleeding",
                                "Time, Bleeding",
                                "Template Bleeding Times",
                                "Ivy Method",
                                "Tests, Aspirin Tolerance",
                                "Test, Aspirin Tolerance",
                                "Duke Method",
                                "Aspirin Tolerance Test"
                        ],
                        "project": "1DAB156D-F01F-0001-ABCE-16301D4023C0",
                        "language": "en",
                        "id": "1DAB156D-F01F-0001-ABCE-16301D4023C0:http://www.nlm.nih.gov/mesh/D001760@en"
                },
                {
                        "matchingLabel": "<em>Aspirin</em>",
                        "score": 4,
                        "uri": "http://www.nlm.nih.gov/mesh/D001241",
                        "conceptSchemes": [
                                {
                                        "title": "Chemicals and Drugs",
                                        "uri": "http://www.nlm.nih.gov/mesh/Chemicals_and_Drugs"
                                }
                        ],
                        "prefLabel": "Aspirin",
                        "altLabels": [
                                "Micristin",
                                "Polopirin",
                                "Magnecyl",
                                "Zorprin",
                                "Ecotrin",
                                "Solupsan",
                                "Acetylsalicylic Acid",
                                "Solprin",
                                "Dispril",
                                "Acid, Acetylsalicylic",
                                "Aloxiprimum",
                                "Endosprin",
                                "2-(Acetyloxy)benzoic Acid",
                                "Easprin",
                                "Polopiryna",
                                "Acetysal",
                                "Colfarit",
                                "Acylpyrin"
                        ],
                        "project": "1DAB156D-F01F-0001-ABCE-16301D4023C0",
                        "language": "en",
                        "id": "1DAB156D-F01F-0001-ABCE-16301D4023C0:http://www.nlm.nih.gov/mesh/D001241@en"
                },
                {
                        "matchingLabel": "<em>Aspirin</em> Like Agents",
                        "score": 3,
                        "uri": "http://www.nlm.nih.gov/mesh/D000894",
                        "conceptSchemes": [
                                {
                                        "title": "Chemicals and Drugs",
                                        "uri": "http://www.nlm.nih.gov/mesh/Chemicals_and_Drugs"
                                }
                        ],
                        "prefLabel": "Anti-Inflammatory Agents, Non-Steroidal",
                        "altLabels": [
                                "Analgesics, Anti Inflammatory",
                                "Analgesics, Anti-Inflammatory",
                                "Non-Steroidal Antirheumatic Agents",
                                "Agents, Nonsteroidal Anti-Inflammatory",
                                "Non Steroidal Anti Inflammatory Agents",
                                "NSAIDs",
                                "Antiinflammatory Agents, Non Steroidal",
                                "Agents, Non-Steroidal Anti-Inflammatory",
                                "Antirheumatic Agents, Non Steroidal",
                                "Agents, Aspirin-Like",
                                "Anti Inflammatory Agents, Non Steroidal",
                                "Nonsteroidal Anti Inflammatory Agents",
                                "Aspirin-Like Agents",
                                "Antirheumatic Agents, Non-Steroidal",
                                "Antiinflammatory Agents, Nonsteroidal",
                                "Agents, Non-Steroidal Antirheumatic",
                                "Agents, Nonsteroidal Antiinflammatory",
                                "Anti-Inflammatory Agents, Nonsteroidal",
                                "Nonsteroidal Antiinflammatory Agents",
                                "Nonsteroidal Anti-Inflammatory Agents",
                                "Anti Inflammatory Agents, Nonsteroidal",
                                "Anti-Inflammatory Analgesics",
                                "Anti-Rheumatic Agents, Non-Steroidal",
                                "Anti Rheumatic Agents, Non Steroidal",
                                "Agents, Non-Steroidal Anti-Rheumatic",
                                "Non-Steroidal Anti-Inflammatory Agents",
                                "Non-Steroidal Anti-Rheumatic Agents",
                                "Aspirin Like Agents"
                        ],
                        "project": "1DAB156D-F01F-0001-ABCE-16301D4023C0",
                        "language": "en",
                        "id": "1DAB156D-F01F-0001-ABCE-16301D4023C0:http://www.nlm.nih.gov/mesh/D000894@en"
                }
        ],
        "total": 4,
        "message": "query time: 80 ms"
}

Query Examples - Concept Suggestion Request Service

Simple Search QueriesExample 1

The following call shows the default using just the "searchString" parameter with a search for the text 'aspirin':

<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=25&searchString=aspirin
Example 2

This example shows the same thing but uses the extended notation.

Although there is just one parameter you have to use an index value for the array of parameters. We use '0' here but you can use any integer value.

<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=25&searchParameters[0].searchString=aspirin
Example 3

The last example in this section applies boosting to the labels and returns similar results to the previous examples.

Three search parameters are used for preferred label, alternative label and hidden label respectively. The search string is the same in all cases, but the boost factors are different. This simulates the SKOS boost scoring which is used by default. The SKOS boosting itself thus is switched of so the boosts can take effect.

<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].labelType=PREF_LABEL&searchParameters[0].boost=3&searchParameters[0].searchString=aspirin&searchParameters[1].labelType=ALT_LABEL&searchParameters[1].boost=2&searchParameters[1].searchString=aspirin&searchParameters[2].labelType=HIDDEN_LABEL&searchParameters[2].boost=1&searchParameters[2].searchString=aspirin&useSkosBoost=false
Queries With Multiple Search Strings and BoostingExample 1

As shown in the last example of the previous section multiple search strings can be used. When they are different, then concepts will be returned that contain any of the search strings. The scoring will take into account how much the query matches the retrieved concepts, which means, if you search for two terms then concepts that contain both of them, will be returned at higher positions. The parameters are combined using a logical OR, so also concepts containing only one of the search strings will be returned (but with lower scores).

<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=100&searchParameters[0].searchString=Alzheimer&searchParameters[1].searchString=Vaccines
Example 2

With boosting the order of the returned results can be further influenced, here 'Alzheimer' gets a higher boost than 'Vaccines'. Thus concepts that contain this search string will appear at higher positions:

<server>/extractor/api/suggest?projectId=<ID>&language=en&numberOfConcepts=100&searchParameters[0].searchString=Alzheimer&searchParameters[0].boost=5&searchParameters[1].searchString=Vaccines&searchParameters[1].boost=1&useSkosBoost=false
Using Different Matching Strategies

The interpretation of the search string can be influenced with the parameter "matchingStrategy".

Regular Expressions

The option "REGEX" lets you use regular expressions.

The following will search all concepts with labels that contain "alpha" + "-" + "at least two numbers". Internally the Solr regex functionality is used, see for example the following page of the Solr documentation for further information.

<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].matchingStrategy=REGEX&searchParameters[0].searchString=.*%5BaA%5D%5BlL%5D%5BpP%5D%5BhH%5D%5BaA%5D%5C-%5B0-9%5D%5B0-9%5D.*

Note

Parameters have to be URL encoded. In many cases this is not relevant, but for regular expressions this is essential for the query to work. The actual regular expression is ".*[aA][lL][pP][hH][aA]\-[0-9][0-9].*".

Expressions are interpreted case sensitive. In order to obtain a case insensitive search you can use the notation shown here while providing upper and lower case characters.

Sensitive

Using the "SENSITIVE" strategy, characters will be used in the search that are usually ignored, for example "-".

Example 1

The following example will search concepts that contain the string 'aci-':

<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].matchingStrategy=SENSITIVE&searchParameters[0].searchString=aci-
Example 2

The default behaviour will also return concepts that contain for example 'acid', because "-" is ignored:

<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].searchString=aci-
Exact

The "EXACT" strategy only matches concepts that contain a label that is exactly the same as the search string (no sub-string search).

This will only retrieve concepts that contain a label 'Aspirin' yet combinations with 'Aspirin' inside the label are ignored:

<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].matchingStrategy=EXACT&searchParameters[0].searchString=Aspirin
Queries Over Custom Labels

You can use the "labelType" and "customLabel" parameters to search over custom labels.

Example 1

The call below returns concepts that contain

  • 'chlor' in the altLabel

  • 'methyl' in the custom label with URI <http://id.nlm.nih.gov/mesh/vocab#casn1_label>

  • 'insects' in the custom label with URI <http://id.nlm.nih.gov/mesh/vocab#annotation>

<server>/extractor/api/suggest?projectId=<ID>0&language=en&numberOfConcepts=100&searchParameters[0].labelType=CUSTOM_LABEL&searchParameters[0].customLabel=http://id.nlm.nih.gov/mesh/vocab%23casn1_label&searchParameters[0].searchString=methyl&searchParameters[1].labelType=ALT_LABEL&searchParameters[1].searchString=chlor&searchParameters[2].labelType=CUSTOM_LABEL&searchParameters[2].customLabel=http://id.nlm.nih.gov/mesh/vocab%23annotation&searchParameters[2].searchString=insects&useSkosBoost=false

Note

Parameters need to be URL encoded which also affects the character "#" in the URIs.

Example 2

It is also possible to only search in custom labels, the parameter "searchString" is optional.

<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].labelType=CUSTOM_LABEL&searchParameters[0].customLabel=http://id.nlm.nih.gov/mesh/vocab%23casn1_label&searchParameters[0].searchString=methyl
Example 3

You can also combine this with different matching strategies, for example regular expressions:

<server>/extractor/api/suggest?projectId=<ID>&language=en&searchParameters[0].labelType=CUSTOM_LABEL&searchParameters[0].customLabel=http://id.nlm.nih.gov/mesh/vocab%23relatedRegistryNumber&searchParameters[0].matchingStrategy=REGEX&searchParameters[0].searchString=.*50-.*-2.*
Retrieve Without Search Parameters

You can retrieve any concepts from a project: just specify the project ID and the language. This way no restrictions are applied and all concepts (up to what is set in "numberOfConcepts") are returned:

<server>/extractor/api/suggest?projectId=<ID>&language=en

Concept Details Information Service

Description

Returns the details of a concept from the extraction model.

URL: /extractor/api/concepts

Request

Supported Methods

POST

GET

Content-Type

application/x-www-form-urlencoded

HTTP Parameter

Parameter

Description

Type

Required

concept

String

true

projectId

String

true

language

String

true

Response

This method returns execution results in JSON format.

ThesaurusConcept

Concept from a PoolParty thesaurus project

Attribute

Type

Comment

altLabels

Array of String

Alternative labels

broaderConcepts

Array of String

URIs of all direct broader concepts

conceptSchemes

Array of ThesaurusConceptScheme

The concept schemes this concept resides

corporaScore

double

Relevance score - e.g. when extracted from a text

customAttributes

Array of CustomAttribute

Custom attributes

customRelations

Array of CustomRelation

Custom relations

customSchemeTypes

Array of CustomSchemeType

URIs of the custom types assigned to the concept

frequencyInDocument

int

Frequency of the concept in the text

frequencyInDocuments

int

Frequency of the concept in the text

hiddenLabels

Array of String

Hidden labels

id

String

Concept id

language

String

Language of the prefLabel, altLabels and hiddenLabels of this localized view of the concept

matchingLabels

Array of MatchingLabel

Matching labels

prefLabel

String

Preferred label

project

String

UUID of the containing PoolParty project

relatedConcepts

Array of String

URIs of all related concepts

score

double

Normalized relevance score - e.g. when extracted from a text

shadowConceptTerms

Array of ExtractedTerm

transitiveBroaderConcepts

Array of String

URIs of all transitive broader concepts

transitiveBroaderTopConcepts

Array of String

URIs of all top concepts that this concept is connected to via a transitive broader-chain

uri

String

Uniform resource identifier

wordForms

Array of String

Lemmatized word forms

ThesaurusConceptScheme

ConceptScheme from a PoolParty thesaurus project - acts as a container for concepts

Attribute

Type

Comment

title

String

The localized title of this concept scheme

uri

String

Uniform resource identifier

CustomAttribute

Custom attribute

Attribute

Type

Comment

literal

Literal

Literal

property

String

Property

CustomRelation

Custom Relation

Attribute

Type

Comment

object

String

Object

property

String

Property

CustomSchemeType

(PoolParty) concept scheme - acts as a container for concepts

Attribute

Type

Comment

title

String

The name of this custom scheme type

uri

String

Uniform resource identifier

ExtractedTerm

Phrase extracted from a text that does not match any Concepts

Attribute

Type

Comment

corporaScore

double

Corpora score

frequencyInDocument

int

Frequency within the document where it was extracted

frequencyInDocuments

int

Frequency within the documents where it was extracted

score

double

Relevance score

textValue

String

The term phrase