Suggest Professions🔗

The /skills/suggest_professions endpoint suggests professions based on an input set of skills.

Endpoint🔗

Method	Media	URL
POST	`application/json`	`{{domain}}/skills/suggest_professions`

Input parameters🔗

Parameter	Type	Default	Description
`code_ids`	list `str` OR list `Skill`	None (required)	The skill code IDs for which the service should return suggested professions. The list can contain up to 50 skill codes. 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.
`return_missing_skills`	`boolean`	`false`	Flag to enable returning a list of missing skills per suggested profession. These skills are missing from the skill set and need to be acquired for the suggested profession.
`limit`	`int`	10	The maximum amount of suggested professions returned. This parameter can be set either as URL parameter (as in the example below) or in the request body. The URL parameter will take precedence over the value set in the request body.
`output_language`	`str`	None (optional)	Parameter to set the language of the returned descriptions. If not set, the service will return no descriptions. Expects a language in ISO 639-1 format (e.g. "en", "nl").

`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: `suggested_professions`: the list of related skills with their relation strength `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 valid code IDs in the Textkernel skill taxonomy.

Example🔗

Using skill codes as a list of str:

curl -X POST POST https://api.textkernel.nl/skills/v2/suggest_professions?limit=2 \
        -H "Authorization: Bearer $TOKEN" \
        -H "accept: application/json" \
        -H "Content-Type: application/json" \
        -d "{\"code_ids\":[\"KS120076FGP5WGWYMP0F\", \"KS125HH5XDBPZT3RFGZZ\", \"KS124PR62MV42B5C9S9F\"]}"

Using a list of Skill objects:

curl -X POST POST https://api.textkernel.nl/skills/v2/suggest_professions \
        -H "Authorization: Bearer $TOKEN" \
        -H "accept: application/json" \
        -H "Content-Type: application/json" \
        -d "{\"code_ids\": [
                {\"code_id\": \"KS123KG6DL8N3D5ZW036\", \"score\": 0.8}, {\"code_id\": \"KS123CW67MS8YB3L3FP3\", \"score\": 0.2}
            ],
            \"output_language\": \"en\",
            \"limit\":\"2\"}"

Response:

{
  "meta": {
    "service_version": "1.0.0",
    "taxonomy_release": "2021-07-05"
  },
  "suggested_professions": [
    {
      "code_id": "696",
      "score": 0.9763952055685978
    },
    {
      "code_id": "109",
      "score": 0.9664422072950023
    }
  ]
}

Response fields🔗

Field	Type	Value
`suggested_professions.code_id`	`str`	The code ID of the related Profession in the Textkernel Profession taxonomy.
`suggested_professions.score`	`float`	An association score indicating the relationship strength between profession and skill. The score is a value in the range [0 - 1].
`suggested_professions.missing_skills.code_id`	`str`	(Only if `return_missing_skills=true`) The code ID of the missing skill for the related profession.
`suggested_professions.missing_skills.score`	`str`	(Only if `return_missing_skills=true`) The associated score for the skill with the target profession.
`suggested_professions.missing_skills.description`	`str`	The skill description as per the TK taxonomy in the specified `output_language`. Will only be returned if `output_language` is specified.

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