CTS2-LE REST API: Concept Search

CTS2-LE offers different search functionalities for retrieving concepts.

Operation

• Path: /WebCts2LE/service/crud/cts2/search
• Method: POST
• Path Parameters: -
• Query Parameters:
  • withCSUriAndVersionId: boolean value to indicate whether results shall include versionOf- and versionId-attributes
• returns: search results in JSON format

POST Body (simple and restricted search)

{
	"searchExpression":[string],
	"grouped":[boolean],			
	"positiveRestriction":[boolean],	
	"groups":[
			{"groupName":[string]}
	],	
	"csvs":[
			{"resourceID":[string]}	
	]		
}

Meaning of the comprised attributes:

• searchExpression: search term

is the only mandatory attribute. When the JSON object contained in the POST body only has this attribute, a basic search (non-grouped) across all terminologies is performed.

• grouped: whether results shall be grouped by codesystem or not (optional, default: false)
• positiveRestriction: whether results shall be restricted to the codesystem versions referenced in groups and csvs (true) or whether only results that do not belong to the referenced codesystems shall be retrieved (false) (optional, default: false)
• groups.groupName: group name of the restricted codesystem versions further referenced in "csvs" (optional)
• csvs.resourceID: resourceIDs of restricted codesystem version (optional)

The same call can be used to retrieve similar search results. The request body is slightly different.

POST Body (similarity search)

{
	"searchExpression":[string],
	"similarConcepts":true,
        "resourceID":[string],
        "groupSize":[number],
	"groups":[
			{"groupName":[string]}
	],	
	"csvs":[
			{"resourceID":[string]}	
	]		
}

Meaning of the comprised attributes:

• searchExpression: references the URI of the concept for which similar concepts shall be retrieved
• similarConcepts: set to true for similarity search
• resourceID: is the resourceID of the codesystem version the concept (referenced in searchExpression) belongs to
• groupSize: (optional, default: 3)
• groups.groupName: group name of the restricted codesystem versions further referenced in "csvs" (optional)
• csvs.resourceID: resourceID of restricted codesystem version (optional)

Response Structure

{
	"complete": [boolean], 		
	"numberOfHits": [number], 			
	"circaHits": [number],			
	"elapsedTime": [number],			
	"results": [
				{
	 				"preferredTerm":[string],	
	 				"name":[string],		
	 				"displayedCode:[string],	
	 				"resourceID":[string],	
	 				"hasParent":[boolean],	
	 				"hasChildren":[boolean],
	 				"versionOf":[string],	
      				        "versionId":[string]
	 			}
	 		]
}

Meaning of the comprised attributes:

• complete: true if all results are contained in response, false if not
• numberOfHits: number of results contained in response
• circaHits: number of all results
• elapsedTime: the time it took to perform the search operation
• results.preferredTerm: the preferred term of the concept
• results.name: the name/code of the concept
• results.displayedCode: the name/code that shall be presented
• results.resourceID: the resourceID of the codesystem version the concept belongs to
• results.hasParent: indicates whether the concept has parents
• results.hasChildren: indicates whether the concept has children
• results.versionOf: the versionOf of the codesystem version the concept belongs to - only present if query parameter 'withCSUriAndVersionId' is true (optional)
• results.versionId: the versionId of the codesystem version the concept belongs to - only present if query parameter 'withCSUriAndVersionId' is true (optional)

When fetching similar concepts, the response is almost equal to the JSON structure presented above. There is one more attribute "similarTo" which comprises the name/code, the preferred term and the resourceID of the origin concept.