Skip to content
Skills Intelligence
Complete-Normalized
latest

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/professions/v1/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. The Professions API does not distinguish categories. Therefore, the parameter can best be omitted. 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.
    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/professions/v1/complete_normalized?limit=10" \
        -H "Authorization: Bearer $TOKEN"\
        -H "accept: application/json" \
        -H "Content-Type: application/json" \
        -d "{\"prefix\":\"dev\",\"languages\":[\"en\"], \"output_language\":\"en\"}"



{
  "completions": [
    {
      "description": "Java Developer (m/f)",
      "category": "professions",
      "code_id": "696"
    },
    {
      "description": "Web Developer (m/f)",
      "category": "professions",
      "code_id": "2610"
    }
  ]
}

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.