Concept Details Services

Abstract

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

Abstract

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. 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

Abstract

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

Abstract

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	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

In this section: