Concepts API

collection of API endpoints which enable various functions related to the concept graph.

A pure javascript example which shows browsing capabilities is created here: https://www.janzz.jobs/japi/explorer/

concept list

If the user has entered a text and you want to convert this to a concept, you can use the concepts api endpoint which works like the labels search but does not return duplicate concepts. There is no guarantee that the entered text will appear in the result (the preferred label of a concept is returned, not the search term entered), therefore this might not be suitable for certain typeahead applications. With this tool you can also search in one language and output the results in another language.

URL

https://www.janzz.jobs/japi/concepts

parameters

• search_lang

  • format: ISO 369-1, 2 character language code, example: de, en, fr, … Choose ‘all’ to search in all languages
  • default value: ‘all’
  • effect: search for concept labels only in this language.

• output_lang

  • format: ISO 369-1, 2 character language code, example: de, en, fr, …
  • default value: browser locale
  • effect: Return preferred label for results in this language if available.

• country

  • format: ISO 3166-1 numeric code. Example: 756 for Switzerland, 040 for Austria, etc.
  • default value: 0 (no preferred country)
  • effect: Labels with the given country code set on them will be chosen over regular or preffered labels

• q

  • format: any string
  • default value: ‘*’ (search for everything)
  • effect: performs a search for concepts that have labels which partially match this query string

• exact_match

  • format: true|false
  • default value: false
  • effect: search for this exact string. When false, search for q

• best_label

  • format: true|false
  • default value: false
  • effect: if true, return the preferred label of the concept, otherwise return label most closely matching search query

• branch

  • format: comma separated list of branches to limit search to.
  • allowable branches: ‘occupation’, ‘specialization’, ‘function’, ‘skill’, ‘softskill’, ‘language’, ‘industry’, ‘contract_type’, ‘education’, ‘education2’, ‘authorization’, ‘filter__xx’ (where xx is the name of the filter, example filter__location_no)
  • default value: none, and no serach is performed. At least one branch must be specified.

• CLASS_{CLASSIFICATION_NAME}

  • search for concepts having a given classification. Use * for the value to indicate all concepts which have that classification name, regardless of the value
  • example: ?q=*&CLASS_BIS/AMS=647520 (normally you would set q=* when searching by specific classification ID)
  • example: ?q=painter&CLASS_BIS/AMS=*
  • list of available classifications: Classifications and Taxonomies

• exclude_nss

  • format: | separated list of “person class” concept labels
  • effect: does not include concepts in results having a relation “not suitable for” where arg1 matches one of provided concepts.

• output_classifications

  • format: | separated list of classifications
  • effect: return all classification values related to the concept_id of each returned value
  • list of available classifications: Classifications and Taxonomies

• normalized:

  • format: true|false
  • default value: false
  • effect: normalize the input string, ü->ue, A->a, collapse multiple spaces, etc.

• override_limit_level:

  • format: true|false
  • default value: false
  • effect: when searching in industry or contract type, default searches only 1 level deep. This allows you to remove this limit - for internal use only.

returns

list of concepts with the following attributes

• id: the numeric id of the concept
• preferred_label: the preferred label of the concept
• classifications: optionally, an object containing a list of classification values for each classification rquested in output_classifications

examples

find concepts containing the word painter in english: https://www.janzz.jobs/japi/concepts?search_lang=en&branch=occupation&q=painter

find concepts containing the word maler in german, output the results in english: https://www.janzz.jobs/japi/concepts?search_lang=de&output_lang=en&branch=occupation&q=maler

find concepts containing the word maler in german, output the results in english: https://www.janzz.jobs/japi/concepts?search_lang=de&output_lang=en&branch=occupation&q=maler

find concepts containing the word maler in german, output the results in english, include all ISCO-08 codes in the output: https://www.janzz.jobs/japi/concepts?search_lang=de&output_lang=en&branch=occupation&q=maler&output_classifications=ISCO-08

find concepts containing the word carpenter in english, output the result in the preferred label for Austria: https://www.janzz.jobs/japi/concepts?search_lang=en&branch=occupation&q=carpenter&output_lang=de&country=040

find concepts containing the word carpenter in english, output the result in the preferred label for Switzerland: https://www.janzz.jobs/japi/concepts?search_lang=en&branch=occupation&q=carpenter&output_lang=de&country=041

return all concepts in a branch with fixed number of concepts (can be used for dropdown or multiselect lists): https://www.janzz.jobs/japi/concepts?output_lang=en&branch=contract_type&q=* https://www.janzz.jobs/japi/concepts?output_lang=en&branch=language&q=* https://www.janzz.jobs/japi/concepts?output_lang=en&branch=education&q=* https://www.janzz.jobs/japi/concepts?output_lang=en&branch=industry&q=*

concept detail

return details about a concept. concept_id must be an integer corresponding to the internal ID of the concept, which is returned in the listing call

URL

https://www.janzz.jobs/japi/concepts/{concept_id}

parameters

• lang

  • format: ISO 369-1, 2 character language code, example: de, en, fr, …
  • default value: browser locale
  • effect: Return preferred label for results in this language if available.

• country

  • format: ISO 3166-1 numeric code. Example: 756 for Switzerland, 040 for Austria, etc.
  • default value: 0 (no preferred country)
  • effect: Labels with the given country code set on them will be chosen over regular or preffered labels

• minimal

  • format: true|false
  • default: false
  • effect: when set to true, returns only id, preferred_label, classification_set. The response is much faster and smaller this way.

returns

• id: concept id
• preferred_label: Preferred label in the requested language

• label_set: list of all labels of a concept including the following attributes:

  • text: the label text
  • lang: the label language

  • tags: any optional tags for that concept. Tags can include:

    • e: exclude from results
    • p: use as preferred label
    • i: always include this label in external searches
    • c_###: when a country passed in a search, this label has a higher priority than “p” labels if the country code matches
    • a: label should be available in all languages

• descr_set: a list of descriptions in all languages, if available
• classification_set: all classifications for this concept, including the label of the classification values and descriptions, if available
• branches: the branches that this concept is in
• occupation_classes: the occupation classes (oc1, oc2, …), if this concept is an occupation.

labels list

Normally this would be used in a typeahead to encourage people to enter something which already exists in the ontology. It may return duplicate concepts. The input text will always appear in the results, making it suitable for most typeaheads applications.

URL

https://www.janzz.jobs/japi/labels/

parameters

• lang

  • format: ISO 369-1, 2 character language code, example: de, en, fr, … Choose ‘all’ to search in all languages
  • default value: ‘all’
  • effect: search for concept labels only in this language.

• q

  • format: any string
  • default value: ‘*’ (search for everything)
  • effect: performs a search for concepts that have labels which partially match this query string

• branch

  • format: comma separated list of branches to limit search to.
  • allowable branches: ‘occupation’, ‘specialization’, ‘function’, ‘skill’, ‘softskill’, ‘language’, ‘industry’, ‘contract_type’, ‘education’, ‘education2’, ‘authorization’, ‘filter__xx’ (where xx is the name of the filter, example filter__location_no
  • default value: none, and no serach is performed. At least one branch must be specified.

• CLASS_{CLASSIFICATION_NAME}

  • search for concepts having a given classification. Use * for the value to indicate all concepts which have that classification name, regardless of the value
  • example: ?q=*&CLASS_BIS/AMS=647520 (normally you would set q=* when searching by specific classification ID)
  • example: ?q=painter&CLASS_BIS/AMS=*
  • list of available classifications: Classifications and Taxonomies

• exclude_tags

  • format: character
  • default value: empty
  • effect: exclude labels which have this tag, such as ‘e’.

• include_umbrella

  • format: true|false
  • default: false
  • effect: when set to false, it will not return labels of any umbrella concepts

• word_breaks

  • format: string of characters, example %20,-*
  • default: ‘*’ - for compatibility, later will be changed to %20 (‘ ‘)
  • effect: only include labels where q is preceded by a word-break character in this string. ‘*’ allows any preceding characters, so searching for “er” will return “engineer”.

• exclude_nss

  • format: | separated list of “person class” concept labels
  • effect: does not include labels of concepts having a relation “not suitable for” where arg1 matches one of provided concepts.

• output_classifications

  • format: | separated list of classifications
  • effect: return all classification values related to the concept_id of each returned value
  • list of available classifications: Classifications and Taxonomies

• exact_match

  • format: true|false
  • default value: false
  • effect: search for this exact string. When false, search for q

• children_of

  • format: any string
  • default value: none
  • effect: search under a specific concept. The specific concept must exist with a label matching this value, in the provided branches, in language “lang”.
  • notes: This parameter is not compatible with the following branches and will be ignored: education, industry

• children_of_relation

  • format: one of: [‘and_descendants’, ‘descendants’, ‘and_children’, ‘children’]
  • default value: descendants
  • effect: used in conjunction with children_of. After matching concepts in children_of, search for q in the related concepts. and means include also the concept in children_of.

• limit

  • format: number of results to return, maximum 500
  • default value: 20

returns

list of labels with the following attributes

• label: the label text
• concept_id: the ID of the concept to which this labels belongs
• classifications: optionally, an object containing a list of classification values for each classification rquested in output_classifications

examples

find occupations https://www.janzz.jobs/japi/labels/?lang=en&branch=occupation&q=test

find skills https://www.janzz.jobs/japi/labels/?lang=en&branch=skill&q=test

find occupations or functions https://www.janzz.jobs/japi/labels/?lang=en&branch=occupation,function&q=test

find occupations which have an ISCO-08 code https://www.janzz.jobs/japi/labels/?lang=en&branch=occupation&CLASS_ISCO-08=*&q=test

find occupations which have an ISCO-08 code, output all ISCO-08 and STYRK 08 codes in results https://www.janzz.jobs/japi/labels/?lang=en&branch=occupation&CLASS_ISCO-08=*&q=test&output_classifications=ISCO-08|STYRK 08

typeahead

A more performant version of the labels list endpoint with some limitations. The main differences to /labels/ are:

• not all branches are available
• lang parameter is required
• exclude_tags is not needed because ‘e’ tags are always excluded and not configurable
• exact_match is not possible
• children_of and relations is not possible
• word_breaks are not configurable
• exclude_nss is not possible
• the results do not reflect the current state of the concept graph, they are up to 20 minutes delayed.

URL

https://www.janzz.jobs/japi/typeahead/

parameters

• lang

  • format: ISO 369-1, 2 character language code, example: de, en, fr, …
  • default value: None, a language must be specified
  • effect: search for concept labels only in this language.

• q

  • format: any string
  • default value: ‘*’ (search for everything)
  • effect: performs a search for concepts that have labels which partially match this query string

• branch

  • format: comma separated list of branches to limit search to.
  • allowable branches: occupation, function, skill, softskill, education, education level, specialization, language, industry, authorization
  • default value: none, and no serach is performed. At least one branch must be specified.

• CLASS_{CLASSIFICATION_NAME}

  • search for concepts having a given classification. Use * for the value to indicate all concepts which have that classification name, regardless of the value
  • example: ?q=*&CLASS_BIS/AMS=647520 (normally you would set q=* when searching by specific classification ID)
  • example: ?q=painter&CLASS_BIS/AMS=*
  • list of available classifications: Classifications and Taxonomies

• output_classifications

  • format: | separated list of classifications
  • effect: return all classification values related to the concept_id of each returned value
  • list of available classifications: Classifications and Taxonomies

• limit

  • format: number of results to return, maximum 500
  • default value: 20

• v2

  • format: boolean: 1 or true to enable
  • default value: false
  • effect: use v2 implementation which matches multiple words, for example “eng sof” will return “Software Engineer”

• want_branches

  • format: boolean: 1 or true to enable
  • default value: false
  • effect: include the branches which this concept is in

returns

list of labels with the following attributes

• label: the label text
• concept_id: the ID of the concept to which this labels belongs
• classifications: optionally, an object containing a list of classification values for each classification rquested in output_classifications

examples

find occupations https://www.janzz.jobs/japi/typeahead/?lang=en&branch=occupation&q=test

find skills https://www.janzz.jobs/japi/typeahead/?lang=en&branch=skill&q=test

find occupations or functions https://www.janzz.jobs/japi/typeahead/?lang=en&branch=occupation,function&q=test

find occupations which have an ISCO-08 code https://www.janzz.jobs/japi/typeahead/?lang=en&branch=occupation&CLASS_ISCO-08=*&q=test

find occupations which have an ISCO-08 code, output all ISCO-08 and STYRK 08 codes in results https://www.janzz.jobs/japi/typeahead/?lang=en&branch=occupation&CLASS_ISCO-08=*&q=test&output_classifications=ISCO-08|STYRK 08

concept relations

API endpoint used to explore relationships in the concept graph.

A pure javascript example which shows browsing capabilities is created here: https://www.janzz.jobs/japi/explorer/

URL

When concept id is known:

https://www.janzz.jobs/japi/concept_relation_by_id/?relation={relation_type}&concept_id={concept_id}

When concept id not known:

https://www.janzz.jobs/japi/concept_relation_by_branch/?relation={relation_type}&label={label}&branch={branch}

parameters

• concept_id (only required with _by_id call)

  • format: numeric id of the concept

• label (only required when with _by_branch call)

  • format: any string which is an exact match for a concept.
  • effect: if ambiguous labels exist matching this concept, it will return the first matched.
  • hint: use = before string to avoid normalizing during search to improve performance

• branch (only required when with _by_branch call)

  • format: string of a single branch to find label in.
  • allowable branches: ‘occupation’, ‘specialization’, ‘function’, ‘skill’, ‘softskill’, ‘education’

• relation_type

  • child/parent:

    • children: child concepts
    • parents: parent concepts

  • by relationship name

    • specializations: has specialization
    • functions: has function
    • skills: has skill
    • softskills: has softskill
    • skillsonet: has skill O*Net 1,2,3,4,5
    • softskillsonet: has softskill O*Net 1,2,3,4,5
    • skillsonet1: has skill O*Net 1
    • skillsonet2: has skill O*Net 2
    • skillsonet3: has skill O*Net 3
    • skillsonet4: has skill O*Net 4
    • skillsonet5: has skill O*Net 5
    • softskillsonet1: has softskill O*Net 1
    • softskillsonet2: has softskill O*Net 2
    • softskillsonet3: has softskill O*Net 3
    • softskillsonet4: has softskill O*Net 4
    • softskillsonet5: has softskill O*Net 5
    • specialized: is specialized in
    • education: has education
    • similar1: same but different
    • similar2: same but different 2
    • similar3: same but different 3
    • similar4: same but different 4
    • similar5: same but different 5
    • similar: same but different 1, 2, 3, 4, 5
    • nss: not suitable for
    • related_occupations: special case when on a non-occupation concept, find related occupations

  • effect:

    • display all relationships to the specified concept which use this relationship type

• lang

  • format: ISO 369-1, 2 character language code, example: de, en, fr,
  • default value: browser locale
  • effect: search for concepts in this language and display preferred label in this language

• limit_output_lang

  • format: true|false
  • default value: false
  • effect: Only display concepts having at least one label in the language provided in lang parameter

• country

  • format: ISO 3166-1 numeric code. Example: 756 for Switzerland, 040 for Austria, etc.
  • default value: 0 (no preferred country)
  • effect: Labels with the given country code set on them will be chosen over regular or preffered labels

• include_descendants

  • format: true|false
  • default: false
  • effect: when set to true, it will return all descendants of the related concepts. Does not apply to child/parent relations.

• include_umbrella

  • format: true|false
  • default: true
  • effect: when set to false, it will not return any umbrella concepts

• descendant_levels

  • format: 1,2,3
  • default: -1
  • effect: when set, include only n levels of descendants, not all. Does not apply to child/parent relations.

• child_level

  • format: 1,2,3
  • default: 1
  • effect: Applies only when relation_type is children, setting to 2 for example will return node.children.children, and no direct children of the current node.

• start_at

  • format: integer
  • default value: 0
  • effect: start at for pagination

• num_results

  • format: integer between 0 and 1000
  • default value: 100
  • effect: maximum number of results to return

• output_classifications

  • format: | separated list of classifications
  • effect: return all classification values related to the concept_id of each returned value
  • list of available classifications: Classifications and Taxonomies

returns

list of concepts with the following attributes

• id: the numeric id of the concept
• url: the url for the concept detail view
• preferred_label: the preferred label of the concept
• has_children: when children relation is used, shows if concept is a leaf node
• classifications: optionally, an object containing a list of classification values for each classification rquested in output_classifications

expand concept

API endpoint used for creating an expanded query using concept child-parent relationships, synonyms, and “similar” relationships

URL

When concept id is known:

https://www.janzz.jobs/japi/expand_concept_id?id=concept_id

When concept id not known:

https://www.janzz.jobs/japi/expand_concept?q=search-string

parameters

• id (only required with expand_concept_id call)

  • format: numeric id of the concept. The concept must be in one of the allowable branches: occupation, specialization, function, skill

• q (only required with expand_concept call)

  • format: string
  • effect: The string which must match the concept label in the search_lang

• branch (only required with expand_concept call)

  • format: comma separated list of branches to limit search to.
  • allowed values: occupation, specialization, function, skill
  • effect: search for concepts matching q in these branches

• search_lang (only required with expand_concept call)

  • format: 2 letter ISO code
  • effect: language for which to search for q in, or “all” to include all languages
  • default value: all

• output_lang

  • format: 2 letter ISO code for language to return the affinity table in
  • default value: de
  • effect: Return preferred label for results in this language if available.

• levels_up

  • format: integer
  • default value: 1
  • effect: represents the number of parent levels to go up from given concept

• levels_down

  • format: integer
  • default value: 1
  • effect represents the number of children levels to go up from given concept

• exclude_tags

  • format: character
  • default value: empty
  • effect: exclude labels which have this tag, such as ‘e’.

• with_cids

  • format: true/false
  • default value: false
  • effect: include the concept id with every result

returns

list of labels with the following attributes

• label: the label text
• rel: the type of similarity - can be synonym, parent, child or similar
• cid: optional concept id of this label

more specific

API endpoint used for finding concepts which are more specific than the one provided. This uses only strings to search and it can return duplicate concepts if more than one label exists in child concepts.

URL

https://www.janzz.jobs/japi/more_specific?q=search-string

parameters

• q: The string which must match the concept label in the search_lang

• branch

  • comma-separated list of branches in which to search for the given term. It is recommended to use a single branch to isolate the concept you are really looking for.
  • allowable branches: ‘occupation’, ‘specialization’, ‘function’, ‘skill’, ‘softskill’
  • default value: none, and no serach is performed. At least one branch must be specified.

• search_lang: 2 letter ISO code for language for which to search in, or “all” to include all languages, default: en
• output_lang: 2 letter ISO code for language to return the affinity table in, default: en
• exclude_tags: exclude labels which have this tag, such as ‘e’. default: e
• exclude_umbrella: exclude labels which belong to umbrella terms. default: False
• levels_down: integer representing number of children levels to go down from found concept, from 1 to 3, default: 1
• limit: integer representing maximum number of results, from 1 to 50, default: 25

returns

list of labels with the following attributes

• label: the label text
• cid: the concept id

classification details

API endpoint used for getting classification details

URL

https://www.janzz.jobs/japi/classification/{cls}/{val}?lang={lang}

url variables

• cls: the classification name, for example, ISCO-08. Any / characters in cls need to be escaped using a double-underscore, __
• val: the classification value

parameters

• lang: 2 letter ISO code for language for which to search and return results in, default: en

returns

an object with the following attributes:

• lang
• classification
• val
• label
• derived_label: true if label comes from a concept label rather than official classification label
• description

cross classification

API endpoint used for returning equivalent classifications

URL

https://www.janzz.jobs/japi/cross_classification/{cls}/{val}/{cls2}

url variables

• cls: the source classification name, for example, ISCO-08. Any / characters in cls need to be escaped using a double-underscore, __
• val: the source classification value
• cls2: the target classification name, for example, ISCO-08. Any / characters in cls need to be escaped using a double-underscore, __

query parameters

• cls1_lang: 2 letter ISO code for language for to provide a classification value for cls, default: en
• cls2_lang: 2 letter ISO code for language for to provide a classification value for cls2, default: en
• cid_lang: 2 letter ISO code for language for to provide a best label for returned cids, default: en
• cid_filter_cls: only consider concepts also having this classification default: empty
• cid_filter_val: when cid_filter_cls is used, filter concepts having this value for cid_filter_cls. Leave empty to include any value, as long as the cid_filter_cls classification is set. default: empty

returns

an object with the following attributes:

• source_cls: Source classification
• source_val: Input source classification value
• target_cls: Target classification
• target_vals: Target classification values, a distinct list
• concept_ids: Concept IDs which are responsible for this mapping, including a preferred label and classifications for those concepts where the classification is in cls, cls2

occupation suggest

API endpoint used for getting recommended functions, specializations, skills, soft skills for a given occupation

URL

https://www.janzz.jobs/japi/occupation_suggest?occupation={search_string}&relation={relation}

parameters

• occupation: The string which must match the concept label in the search_lang

• relation

  • allowable relations: ‘specialization’, ‘function’, ‘skill’, ‘softskill’
  • default value: none, and nothing is returned. At least one relation must be specified.

• lang: 2 letter ISO code for language for which to search and return results in, default: en
• exclude_tags: exclude labels which have this tag, such as ‘e’. default: e
• limit: integer representing maximum number of results, from 1 to 50, default: 25

returns

list of labels with the following attributes

• label: the label text

education level

This endpoint provides two ways of getting to an “education level” concept usable in a JANZZ’s education field. You can either provide a concept id, if you know it, or a classification and classification value. If the concept is found, then it will be searched up towards the root until it finds a suitable education level concept. More than one concept can be returned if the found concept is in multiple education levels.

URL

https://www.janzz.jobs/japi/education_level/{id}
https://www.janzz.jobs/japi/education_level/

parameters

• output_lang

  • format: ISO 369-1, 2 character language code, example: de, en, fr, …
  • default value: browser locale
  • effect: Return preferred label for results in this language if available.

• country

  • format: ISO 3166-1 numeric code. Example: 756 for Switzerland, 040 for Austria, etc.
  • default value: 0 (no preferred country)
  • effect: Labels with the given country code set on them will be chosen over regular or preffered labels

• CLASS_{CLASSIFICATION_NAME}

  • search for concepts having a given classification. Use * for the value to indicate all concepts which have that classification name, regardless of the value
  • example: ?q=*&CLASS_BIS/AMS=647520 (normally you would set q=* when searching by specific classification ID)
  • example: ?q=painter&CLASS_BIS/AMS=*
  • list of available classifications: Classifications and Taxonomies

returns

list of labels with the following attributes

• label: the label of the concept
• level: the level number, a higher number implies a higher level of education

examples

find all education levels for concept with id 57867: https://www.janzz.jobs/japi/education_level/57867?output_lang=no

find all education levels for concepts with NUS (No) code of 455239: https://www.janzz.jobs/japi/education_level/?output_lang=no&CLASS_NUS%20(No)=455239 Concepts

concept classifications and related

return classification values of a list of concepts. If the concept has no classification value, then return those of related concepts.

URL

https://www.janzz.jobs/japi/concept_classifications_and_related

parameters

• cid

  • format: integer
  • multiple values: repeat parameter (max 25 values)

• classification

  • format: string
  • multiple values: repeat parameter (max 5 classifications)
  • list of available classifications: Classifications and Taxonomies

• and_related

  • format: numeric value between 0 and 1.0
  • default: 0
  • effect: minimum threshold to consider related concepts.

returns

• for each cid and classification combination requested, returns a list of classification values and their score.
• the score represents the similarity between the cid and the concept which had this classification value. A score of 1.0 means that the concept itself had that value. Anything less than 1.0 means the concept did not have this classification, only related concepts did.

example

find all ISCO-08 and O*Net codes of 22399 and 197338.

https://www.janzz.jobs/japi/concept_classifications_and_related/?cid=22399&cid=197338&classification=O*Net&classification=ISCO-08&and_related=0.3

output:

{
  "22399": {
    "O*Net": [
      [
        "15-1131.00",
        1.0
      ],
      [
        "15-1132.00",
        1.0
      ],
      [
        "15-1133.00",
        1.0
      ]
    ],
    "ISCO-08": [
      [
        "2512",
        1.0
      ],
      [
        "2514",
        1.0
      ]
    ]
  },
  "197338": {
    "O*Net": [
      [
        "15-1131.00",
        0.6
      ],
      [
        "15-1132.00",
        0.6
      ],
      [
        "15-1133.00",
        0.6
      ],
      [
        "15-1111.00",
        0.6
      ],
      [
        "17-2071.00",
        0.6
      ]
    ],
    "ISCO-08": [
      [
        "2512",
        0.6
      ],
      [
        "2514",
        0.6
      ],
      [
        "2152",
        0.6
      ],
      [
        "2511",
        0.6
      ],
      [
        "2151",
        0.6
      ]
    ]
  }
}