Complete-Normalized

The /complete_normalized endpoint provides prefix-based completion suggestions of normalized concepts, based on the chosen categories and language(s). Each concept is associated with multiple descriptions. If any of its descriptions ranks high as being a good completion of the given prefix, the concept itself is returned with its concept ID and translation.

Endpoint

Method	Media	URL
POST	application/json	https://api.textkernel.nl/skills/v2/complete_normalized

Input parameters

Request parameters are partly specified as URL parameters and partly in the request body.

Parameter	Type	Default	Description
prefix	str	None	The prefix to complete
limit	int	10	(Max) number of returned suggestions
categories	list str	['all']	The optional knowledge categories that should be searched for completions
languages	list str	None	The knowledge languages that should be searched for completions
output_language	str	EN	The language for retrieved concept descriptions

Parameter Details

• The service will try to find completions for the provided prefix string. The prefix string needs to contain minimally one character. For better recall, the service is allowing for prefix matches starting not only on the first word of multi-word terms and also includes fuzzy string matches, with a small edit distance to the given prefix.
• The limit parameter allows to control the number of suggestions returned by the service. It defaults to 10 and should be <= 100. Keep in mind that clearly larger numbers are computationally more costly to retrieve.
• The categories determine what categories of knowledge resources should be searched for completions. Max 5 categories can be selected. Available categories are: professional_skills, soft_skills, lang_skills, it_skills, all. Some categories have a hierarchical structure. In that case, specifying the top category will return suggestions from any of the sub categories. When multiple categories are listed, the best ranked suggestions from any of the listed categories will be returned. This can result in only retrieving suggestions for one of the categories.
• The languages specification entails for which languages suggestions should be returned. Max 5 languages can be selected. When multiple languages are listed, then normalization happens for all those languages and the returned concepts' names will be returned in the first language of this parameter's list.
  Languages should be specified either by ISO639-1 language ID or by a locale of the form ISO639-1_ISO3166-1 (case insensitive).
• The output_language allows to specify the language in which retrieved concept descriptions should be returned. This parameter defaults to English if omitted. The languages should be specified either by ISO639-1 language ID or by a locale of the form ISO639-1_ISO3166-1 (case insensitive).

Example Request

curl -X POST "https://api.textkernel.nl/skills/v2/complete_normalized?limit=10" \
        -H "Authorization: Bearer $TOKEN" \
        -H "accept: application/json" \
        -H "Content-Type: application/json" \
        -d "{\"prefix\":\"dev\",\"categories\":[\"it_skills\"],\"languages\":[\"en\"], \"output_language\":\"en\"}"



{
  "completions": [
    {
      "description": "DevOps",
      "category": "it_skills",
      "code_id": "KS122W96T2T9J5PZ0VMP"
    },
    {
      "description": "Scrum (Software Development)",
      "category": "it_skills",
      "code_id": "KS1282N6NQMZ95M1HJ7L"
    }
  ]
}        

Response

The service returns a ranked list of the top retrieved concepts where the ranking of concept descriptions is based on:

• string similarity: first exact prefix matches followed by fuzzy matches
• concept frequency: the concepts frequency in a large collection of documents is a good estimate for the likelihood of the concept being meant by the user

The service returns all found concepts in specified categories. All returned completion concepts are annotated with:

• the concepts code_id.
• the concepts description in the requested language. The name is the human-readable description of the concept. In the seldom case that we do not have a description in the requested language, the default English description will be returned for that particular code.
• the concepts category, in its most specific form, e.g. it_skill instead of skill.

Rate limits

Accounts have a limited request rate. If you exceed the limit you will receive 429 Too Many Requests HTTP responses.

Plan	Limit	Units
Standard	1000	Minute
Demo	30	Minute

Remember to send your authentication token with each request (see Authentication).

Notes

• The API does not support cross origin requests, and cannot be called directly from browsers. We recommend calling the autocomplete endpoints through a reverse proxy instead.
• If this endpoint is used for 'as-you-type' suggestions, we recommend wrapping the requests in a function that is debounced with a 300 millisecond timer.