Skip to main content

Sample Recommender API Calls

Abstract

Sample Recommender API Calls

This section uses some of the sample calls we configured using the Recommender 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 recommender - this path may look like this [https://yourServer]/recommender.

Note

Keep in mind that the recommendation is comprised of three queries - extraction, expansion and recommendation.

Caution

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

However, if the search space is set to "public" the user can send these three calls to the recommender 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/recommender/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 the recommender on the Recommender Workbench we saved all three requests (extraction, expansion and recommendation) as cURL requests;

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/recommender/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 Recommender Workbench.

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.

Web Service Method: Recommend content matching the list of concepts and/or input text

This endpoint takes a list of concepts and/or the input text along with configuration parameters and returns recommendations matching those concepts/input text.

Note

Elasticsearch index is required for the recommendation call.

  • URL: https://your.server/recommender/api/recommend

  • 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, concepts retrieved during extraction and expansion along with the their scoring, further the zero-based index of pages and number of recommendations shown on per page, for instance "page":0,"size":5 means that on the first page (page = 0) the first five results will be shown, on the second page (page = 1), the next five results (i.e. 6 through 10), etc.

Let us use the query we saved on the Recommender Workbench.

Responses

This call should return for our example a list with recommendation items (documents) including India's Policy and (...) .

  • 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 a short descriptive message, number of recommendations and a list with the recommendation results (i.e. recommendations) each with their ID, title, description, link, author, concepts and explanation (which is specific for every single recommendation) along with total score of such recommendation and matching concepts with their scores.

  • The response format is application/json.

Note

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

In this section: