Normalize skills

The /normalize endpoint is a REST service offered via a POST method.
The service expects JSON as input, with up to three input fields: the list of skills, the input language and the output_language. The input skills and language are mandatory fields.

It will normalize the input skills to the skill taxonomy:

• if a skill is present in the taxonomy (full or partial match), return its normalized fields.
• if a skill is not present in the taxonomy, return default unclassified values.

Endpoint

Method	Media	URL	Description
POST	application/json	{{domain}}/normalize	Normalize a list of skills

Input parameters

Parameter	Type	Default	Description
skills	array	None	The list of skills to normalize (up to 50 skills, each skill may not exceed 100 characters)
language	str	None	The language of the skill taxonomy in ISO 639-1 code
output_language	str	same as language	The language (ISO639-1 code) or locale (ISO639-1_ISO3166-1 code) of the normalized skills

Specify in the language field one of the supported languages (ISO 639-1 code format).

Set the output_language field only if you want to get skill descriptions in a different language than the input language.
If so, set it to one of the supported languages (ISO639-1 code format) or locales (ISO639-1_ISO3166-1 code format).
Whenever a skill can't be normalized in the requested language, it will be normalized by default in English.

See the Overview for the list of supported languages.

Response

Status	Content type	Content description
200 (OK)	application/json	A JSON object containing: skills: a list of normalized skills version: the API version meta: an object including the taxonomy version (release date)
400 (Bad request)		The input request body is incorrect
404 (Not Found)		The language is not supported

Example

$ curl -X POST https://api.textkernel.nl/skills/v2/normalize \
    -H "accept: application/json" -H "Content-Type: application/json" \
    -d '{"language": "en", "skills": ["English", "C/C++", "2004 lead auditor", "html6"]}'

{
  "meta": {
    "taxonomy_version": "2021-12-01T17:04:55.769277"
  },
  "skills": [
    {
      "category": "Language",
      "code_id": "KS123K75YYK8VGH90NCS",
      "confidence": 1.0,
      "description": "English",
      "iso_code": "en",
      "skill": "English"
    },
    {
      "category": "IT Skill",
      "code_id": "KS1219W70LY1GXZDSKW5",
      "confidence": 1.0,
      "description": "C++ (Programming Language)",
      "skill": "C/C++"
    },
    {
      "category": "Professional Skill",
      "code_id": "KS120RN6FDTS9FLCH3T0",
      "confidence": 0.412,
      "description": "Auditing",
      "skill": "2004 lead auditor"
    },
    {
      "category": "Professional Skill",
      "code_id": "UNCLASSIFIED",
      "confidence": 0.0,
      "description": "Unclassified",
      "skill": "html6"
    }
  ],
  "version": "2.1.0"
}

Response fields

Field	Type	Value
skill	str	The input skill
description	str	The description of the normalized skill concept from the taxonomy
code_id	str	The code id of the normalized skill from the Taxonomy (unique across all languages)
category	str	The category of the normalized skill. See the Overview for the list of supported categories.
confidence	float	Overall confidence that the input skill was normalized to the correct skill concept (substring overlap ratio)
iso_code	str	The language ISO 639-1 code (only for language skills)

Notes on the confidence normalization score

• a confidence score of 1.0 means that a full match has been found in the requested taxonomy
• a confidence score between 0.0 and 1.0 means that a partial match has been found in the requested taxonomy (only 1 partial match is returned, the longest one)
• a confidence score of 0.0 means that neither a full match, nor a partial match, had been found in the requested taxonomy; in this case, an Unclassified normalized skill is returned (default UNCLASSIFIED code id, Professional Skill category, a language-dependent normalized description)

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