Inference Tagging API Calls Overview

This section uses some of the sample calls we configured using the Workbench and copied then to clipboard. You need to keep in mind that these are sample API request calls along with those parameters we previously set up using the Workbench.

We will now test those sample calls (previously copied to clipboard as cURL requests). As you know you will have to specify the server running your instance of Inference Tagging - this path may look like this [https://yourServer]/InferenceTagging.

Note

Keep in mind that our example is comprised of two queries - extraction and expansion.

Caution

Normally, you must be authenticated and authorized to make these API calls on your inference tagging instance.

However, if the search space is set to "public" the user can send these two calls to the extractor without having been previously authorized.

Web Service Method: Extract concepts from an input text

This endpoint takes a text input together with specified configuration parameters and then returns concepts found in this text.

URL: https://your.server/extractor/api/extract
Content type is application/json.
Method: POST.

The request body

Content type is application/json.
The request configuration parameters are the search space ID, language, minimum score and input. You also need the corpus ID if you want to include corpus scoring and extract shadow concepts.
Other request configuration parameters are: filterNestedConcepts, useCorpusScoring, useShadowConcepts, useDisambiguation and showMatchingInformation.

When configuring Inference Tagging using on the Workbench we saved both requests (extraction and expansion) as cURL requests;

curl -L 'https://your.server/extractor/api/extract'\ 
  -H 'Content-Type: application/json'\ -H 'Authorization: Bearer AUTHENTICATION_TOKEN'\ 
  -d '{"input":"Receptors with diminished functionality may cause vision impairments. The latest WHO report underlines 
  the significance of proper nutrition when it comes to proper development of vision.", 
      "searchSpaceId":"22f7c24a-c3b2-4eaa-bc97-2bc8beb5327b", 
      "locale":"en", 
      "conceptSchemeFilters":[], 
      "conceptMinScore":30, 
      "corpusIds":[], 
      "maxNumberOfConcepts":10, 
      "filterNestedConcepts":false, 
      "useShadowConcepts":false, 
      "useDisambiguation":true}'

Responses

This call should return for our example the concepts: "Vision, Ocular 100", "World Health Organization 66", and "Research Report 61".

The response codes are 200 for correctly formed request, respectively 400 for bad request (user side) or 5xx indicating an unexpected error (server side).
The response format is application/json.

Web Service Method: Create a semantic footprint for a list of concepts

This endpoint takes a list of concepts and an expansion query and creates a semantic footprint for those two. This means, the result will be a list of concepts which are related to the input concepts, whereby the relation between those is defined by the expansion query.

URL: https://your.server/tagging/api/expand
Content type is application/json.
Method: POST.

The request body

Content type is application/json.
The request configuration parameters are the search space ID, language, expansion query along with the concepts retrieved during the extraction.

Let us use the query we saved on the Workbench.

curl -L 'https://your.server/tagging/api/expand'\ 
-H 'Content-Type: application/json'\ -H 'Authorization: Bearer AUTHENTICATION_TOKEN'\ 
-d '{"searchSpaceId":"22f7c24a-c3b2-4eaa-bc97-2bc8beb5327b",
"expansionQuery":"prefix skos:\u003chttp://www.w3.org/2004/02/skos/core#\u003e\nselect ?uri ?label ?finalScore\n
where 
{\n  ?uri skos:prefLabel ?label . FILTER ( lang(?label) \u003d \u0027en\u0027 )
 {\n    
    select ?uri (MAX(?expansionScore) as ?finalScore) where { VALUES (?x ?inScore)\n
      { \u003cinputConcepts\u003e }\n
      { BIND(?x AS ?uri) BIND(STRDT(\u00271.00\u0027,xsd:float) AS ?distScore) }\n
      UNION { ?x skos:narrower ?y . BIND(STRDT(\u00270.8\u0027,xsd:float) AS ?distScore) }\n
      UNION { ?x skos:narrower/skos:narrower ?y . BIND(STRDT(\u00270.4\u0027,xsd:float) AS ?distScore) }\n
      UNION { ?x skos:broader/skos:narrower ?y . filter(!sameTerm(?x,?y)) BIND(STRDT(\u00270.2\u0027,xsd:float) AS ?distScore) }\n
      BIND(IF(BOUND(?y), ?y, ?x) AS ?uri) .\n
      BIND(?distScore * ?inScore AS ?expansionScore) . \n
    }\n
GROUP BY ?uri order by desc(?finalScore)\n
  }\n
}\n
limit \u003cnumberOfConcepts\u003e",
"concepts":[{"uri":"http://id.nlm.nih.gov/mesh/2016/D014785","score":100.0},
{"uri":"http://id.nlm.nih.gov/mesh/2016/D014944","score":66.0},
{"uri":"http://id.nlm.nih.gov/mesh/2016/D058028","score":61.0}],
"maxNumberOfConcepts":10}'

Responses

This call should return for our example the concepts: "Color Vision 80", "Mesopic Vision 80", and "Night Vision 80", "Phosphenes 80", "Vision, Entiopic 80", and "Pan American Health Organization 53", "Rode-Cone Interaction 40" .

The response codes are 200 for correctly formed request, respectively 400 for bad request (user side) or 5xx indicating an unexpected error (server side).
The response with code 200 delivers the identified concepts matching the expansion query criteria with their label, uri and score (if queried).
The response format is application/json.

Note

Refer to Overview of Schemata for Inference Tagging API Calls for more details on the mandatory and optional call parameters.

In this section: