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 byISO639-1
language ID or by a locale of the formISO639-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 byISO639-1
language ID or by a locale of the formISO639-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 ofskill
.
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.