Similarity score for skill sets

The /skills/similarity_score endpoint provides skills related to a given skill or a set of skills. The service returns closely related skills in a sense that knowing the provided skills either implies knowledge about the returned related skills, or should make it considerably easier to acquire knowledge about them.

Endpoint

Method	Media	URL
POST	application/json	{{domain}}/skills/similarity_score

Input parameters

Parameter	Type	Default	Description
code_ids_a	list str OR list Skill	None (required)	The skill codes in skill set A for comparison against skill set B. The skills can be either a list of str, or a list of Skill objects, as described in the section below. The Skill object allows to add a skill score that will be applied as weight.
code_ids_b	list str OR list Skill	None (required)	The skill codes in skill set B for comparison against skill set A. The skills can be either a list of str, or a list of Skill objects, as described in the section below. The Skill object allows to add a skill score that will be applied as weight.

Skill object

The Skill object is an object that contains a code_id, a score and optionally a description. This object is used in all skill-based requests and responses of the Ontology Service. Therefore, the response skills of one endpoint are immediately portable to the request for the next.

Property	Type	Required?	Description
code_id	str	Yes	The code ID of the skill. This should be a valid code ID from the TK taxonomy.
score	float	Yes	The score or weight of a skill. In responses this means the score of the output. In requests this means the weight that will be applied to the skill. This must be a value in the range [0 - 1]
description	str	No	Description label of the skill. Does not have any effect in requests.

Using the score property to weight input skills

The score property in requests determines the weight of a skill in the input. A logical use case of this property would for example be to translate a candidate's proficiency level for that skill to a weight. When the request contains a list of Skill objects, supplying scores for all skills is mandatory. When the request contains a list of str objects, all skills are weighted equally.

The score values need to be in the range [0 - 1]. For example, if your data model uses proficiency levels [1, 2, 3, 4, 5], they should be translated into weights [0.2, 0,4, 0.6, 0.8, 1.0].

The weights are relative, so SKILL_A.weight = 0.2 and SKILL_B.weight = 0.4 is equivalent to SKILL_A.weight = 0.5 and SKILL_B.weight = 1.0.

Response

Status	Content type	Content description
200 (OK)	application/json	A JSON object containing: similarity_score: the similarity score between skill set A and skill set B. The score is between 0 and 1. meta: meta information of the service version
400 (Bad request)		The input request body is incorrect
422 (Validation error)		The input code IDs are not a valid code IDs in the Textkernel profession taxonomy.

Example

Using skill codes as a list of str:

curl -X POST https://api.textkernel.nl/skills/v2/similarity_score \
    -H "Authorization: Bearer $TOKEN" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
            "code_ids_a": ["KS120076FGP5WGWYMP0F", "KSB0O0RTR4GBUS9C1FV7"],
            "code_ids_b": ["KS125LS6N7WP4S6SFTCK", "KS440QS66YCBN23Y8K25"]
        }'

Response:

{
  "meta": {
    "service_version": "1.0.6",
    "taxonomy_release": "2023-06-26T15:31:57.202249"
  },
  "similarity_score": 0.35198178985931916
}

Using a list of Skill objects:

curl -X POST https://api.textkernel.nl/skills/v2/similarity_score \
    -H "Authorization: Bearer $TOKEN" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{"code_ids_a": [{"code_id": "KS120076FGP5WGWYMP0F", "score": 0.8}, {"code_id": "KSB0O0RTR4GBUS9C1FV7", "score": 0.2}],
         "code_ids_b": [{"code_id": "KS125LS6N7WP4S6SFTCK", "score": 0.8}, {"code_id": "KS440QS66YCBN23Y8K25", "score": 0.2}]}'

Response:

{
  "meta": {
    "service_version": "1.0.6",
    "taxonomy_release": "2023-06-26T15:31:57.202249"
  },
  "similarity_score": 0.35198178985931916
}

Response fields

Field	Type	Value
similarity_score	float	A score representing the relatedness of skill set A and skill set B, based on the relations between skills

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).