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: :doc:`/classifications` - 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: :doc:`/classifications` - 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: :doc:`/classifications` - 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: :doc:`/classifications` - 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: :doc:`/classifications` - 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: :doc:`/classifications` - 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: :doc:`/classifications` 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: :doc:`/classifications` 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: :doc:`/classifications` - 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 ] ] } }