MATCH API

janzz search json

API endpoint to search using a janzz body, creating a temporary janzz when necessary. A hash of the json object will be created to check if a suitable janzz already exists in the system to use for matching.

URL

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

ALLOWABLE METHODS

POST

SAMPLE REQUEST BODY

The request body is the same as a janzz body. Only the fields relevant for matching will be used when creating the hash key. match_factor can be changed without creating a new janzz, as it will be set before performing the search.

Optionally, adding keyword to the JANZZ body will search for this text in the concept graph and add corresponding features to the JANZZ if the text is found.

example

{
  "keyword": "french"
}

results in

{
  "skill_list": ["French"],
  "language_list": [{"language": "French", "proficiency": 1, "proficiency2": 1}]
}

PARAMETERS

All parameters are the same as for janzz_search

  • keyword_limit_used_concepts - boolean (true or 1 for true, anything else for false, default false) - When using keyword, you can limit searching the concepts to ones used in your account. Generally this should be left disabled because related concepts may be valuable in the search, even if the exact concept found has not been used.

SAMPLE RESPONSE

{
  "num_results": 3171,
  "total_ungrouped": 4361,
  "janzz_id": 1545381,
  "internal_id": "janzz-internal-095371a7bd009e43ce0ca5a6bce8c4d16abf70be",
  "created": false,
  "results": [{
      "id": 584157,
      "internal_id": "init_offer2",
      "status": 1,
      "janzz_type": 11,
      "title": "job offer 2, czech teacher",
      "language_captured": "en",
      "score": 100
  }]
}

RESPONSE FIELDS

  • results - matched results. A minimal list of fields of each janzz is provided. Retrieve the janzz by id or internal_id for full list of details.

  • num_results - number of results returned

  • total_ungrouped - same as num_results if grouped is not true, otherwise the total number of results before applying grouping

  • janzz_id - the ID of the janzz used for the search, can be used for match_explain

  • internal_id - the internal ID of the janzz used for search

  • created - whether or not a new janzz was created for this search

match explain janzz

API endpoint which describes how a match is made between two janzzs, janzz1 and janzz2

URL

https://www.janzz.jobs/japi/match_explain/
https://www.janzz.jobs/japi/match_explain_internal/

ALLOWABLE METHODS

GET

REQUEST PARAMETERS

  • janzz1 - the janzz id from which the search was initiated, or the internal_id if using _internal

  • janzz2 - the janzz from the search results, or the internal_id if using _internal

  • lang - The language in which to show the concept labels in the match description

  • simple - boolean (true or 1 for true, anything else for false) - Only include first occurrence of c1id in sorted _concepts_matched_ list

EXAMPLE

https://www.janzz.jobs/japi/match_explain/?janzz1=584160&janzz2=584157&lang=en

SAMPLE RESPONSE

{
  "j2_not_matched": [{
      "name": "Czech (Language)",
      "id": 26471
  }],
  "concepts_matched": [{
      "c2name": "Language Teacher",
      "c2id": 20633,
      "cor": 1.0,
      "c1id": 20633,
      "c1name": "Language Teacher"
  }],
  "j1_not_matched": [],
  "j1_internal_comments": "",
  "j2_internal_comments": ""
}

RESPONSE FIELDS

  • concepts_matched - list of concepts matched

    • c1id - searched concept id

    • c1name - searched concept best label

    • c2id - matched concept id

    • c2name - matched concept best label

    • cor - correlation between concept1 and concept2, from 0.0 to 1.0

  • j1_not_matched - list of janzz1 concepts which were not matched in janzz2

  • j2_not_matched - list of concepts from janzz2 which were not matched in janzz1

  • j1_internal_comments - internal comments for janzz1

  • j2_internal_comments - internal comments for janzz2

janzz search elastic

Searching endpoints similar to janzz_search_json and janzz_search, using an implementation based on Elastic Search which provides additional functionality over the other implementation.

The main differences are:

  • allows JANZZs to be indexed with multiple occupations without a score penalty during search

  • must criteria on fields is respected

  • scoring is based only on what has been searched for

  • compound fields are handled better, like education (level + degree) and experience (time + profession)

  • explanation of result scores can be returned directly in the search results, with exact labels used in target janzz for each field.

  • it is possible to specify custom weights for each branch

  • grouping results by group_key is not possible anymore, but this feature was normally used when it was not ideal to use multiple occupations per JANZZ.

  • since explain=true with many results can slow down the response considerably, it is also possible to use explain=false, then repeat the exact same request with explain=true and limit_result=<janzz_id> for an explanation for that single result only.

URL

(append an _e to other janzz_search URLs)
https://www.janzz.jobs/japi/janzz_search_e/[janzz_id]
https://www.janzz.jobs/japi/janzz_search_internal_e/[internal_id]
https://www.janzz.jobs/japi/janzz_search_json_e/

ALLOWABLE METHODS

POST for json interface, GET for non-json interface

SAMPLE REQUEST BODY

The request body is the same as a janzz body. Only the fields relevant for matching will be used when creating the hash key. match_factor can be changed without creating a new janzz, as it will be set before performing the search.

PARAMETERS

  • 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

  • filter_profile

    • format: string

    • default value: empty

    • effect: only show janzzes having only the matching Company profile name

  • status

    • format: integer, can me provided multiple times. 0:draft 1:published 3:withdrawn 4:paused

    • default value: empty, do not filter on status

    • effect: only show janzzes which have a status

  • include_tag

    • format: string

    • effect: only show janzzes which have this tag

    • multiple: repeating parameter will OR all tags together

  • include_tag_all

    • format: string

    • effect: only show janzzes which have this tag

    • multiple: repeating parameter will AND all tags together

  • exclude_tag

    • format: string

    • effect: only show janzzes which do not have this tag

    • multiple: repeating parameter will OR all tags together

  • highest_education_level_from, highest_education_level_to

    • format: integer

    • effect: only show janzzes which are indexed with highest_education_level in this range

    • valid values: an integer between 0 (no education) and 7 (PhD level)

  • total_experience_level_from, total_experience_level_to

    • format: integer

    • effect: only show janzzes which are indexed with total_experience_level in this range

    • valid values: an integer between 0 (no experience) and 17 (10+ years experience)

  • total_experience_months_from, total_experience_months_to

    • format: integer

    • effect: only show janzzes which are indexed with total_experience_years in this range of provided months/12.0

    • valid values: an integer between 0 (no experience) and 1000 (the maximum number of supported months, approximately 83 years)

  • explain

    • format: boolean (true or 1 for true, anything else for false)

    • default value: false

    • effect: explain all match results

  • limit_result

    • format: integer, the janzz ID of the result

    • default value: empty

    • effect: used in conjunction with explain=true, only return score and explanation for a single result

  • ignore_glocations

    • format: boolean (true or 1 for true, anything else for false)

    • default value: false

    • effect: do not use the values in location_list when searching

  • ignore_slocations

    • format: boolean (true or 1 for true, anything else for false)

    • default value: false

    • effect: do not use the values in slocation_list when searching

  • weight_<branch>

    • format: float from 0.0 - 99.9

    • default value: empty

    • effect: you may specify a weight for each branch, from the following list:

      • occupation

      • function

      • specialization

      • industry

      • authorization

      • skill

      • softskill

      • language

      • education

      • experience

      If not provided, the default weights will be used, which may be dependent on the chosen occupation. A good base for this is weight_occupation=10 and weight_<everything else>=5

SAMPLE RESPONSE

{
  "num_results": 3171,
  "janzz_id": 1545381,
  "internal_id": "janzz-internal-095371a7bd009e43ce0ca5a6bce8c4d16abf70be",
  "created": false,
  "results": [{
      "id": 584157,
      "internal_id": "init_offer2",
      "status": 1,
      "janzz_type": 11,
      "title": "job offer 2, czech teacher",
      "language_captured": "en",
      "score": 100,
      "explain": {}
  }]
}

RESPONSE FIELDS

  • results - matched results. A minimal list of fields of each janzz is provided. Retrieve the janzz by id or internal_id for full list of details.

  • num_results - number of results returned

  • janzz_id - the ID of the janzz used for the search, can be used for match_explain

  • internal_id - the internal ID of the janzz used for search

  • created - whether or not a new janzz was created for this search

  • explain - when explain query parameter is used, each result will contain a score explanation in the following format:

    {
  "matched": {<branches>},
  "not_matched_source": {<branches>},
  "not_matched_target": {<branches>},
  "extra": {<extra>}
}

    where branches are of the format:

    <branch>: [
  <field>,
  <field>,
  ...
]

    where each field is of the format:

    {
  "score": 1.0,
  "type": "concept",
  "label_source": "Responsabilidad"
  "label_target": "Responsible",
}

    where type can be one of:

    • concept

    • highest_education_level

    • total_experience_level

    The score is always a value from 0.0 to 1.0 (0-100%). Only scores in the matched fields are > 0.

    In the following cases, label_source and label_target may be null:

    • not_matched_source: label_target will be null, since there is no matching field on the target side

    • not_matched_target: label_source will be null, since there is no matching field on the source side

    • type is highest_education_level or total_experience_level: label_source and label_target are both null, since this is not concept field

    extra is of the format:

    {
  "total_experience_level": {
    "source": 2,
    "target": 6
  },
  "highest_education_level": {
    "source": 2,
    "target": 5
  }
}

    • source is null if no experience or education was searched for

    • target is null if the result has no experience or education set

    • total_experience_level adds up all experience in all units and normalizes it to a total value in years. The following mapping is then used:

      • 1: <= 0.1y

      • 2: <= 0.2y

      • 3: <= 0.25y

      • 4: <= 0.3y

      • 5: <= 0.5y

      • 6: <= 1y

      • 7: <= 1.5y

      • 8: <= 2y

      • 9: <= 3y

      • 10: <= 4y

      • 11: <= 5y

      • 12: <= 6y

      • 13: <= 7y

      • 14: <= 8y

      • 15: <= 9y

      • 16: <= 10y

      • 17: > 10y

      For example, total_experience_level 8 could be described as betweeen 1 1/2 and 2 years total experience.

    • highest_education_level collects the ‘level’ field in all education objects and takes the one having the highest value, where the values are integers representing the following:

      • 0: No qualifications/No A-Level/No International Baccalaureate (IB)/No high school diploma

      • 1: In training (e.g. school, college, apprenticeship, etc.), On-the-job training, Course, …

      • 2: A Level/High School Diploma/International Baccalaureate (IB), University studies (not completed), …

      • 3: Vocational qualification (e.g. Swiss Federal VET Diploma)

      • 4: Certificate/Credentials/Diploma/Title, Higher vocational degree/Higher technical degree, …

      • 5: Bachelor’s degree/University primary qualification/Undergraduate degree

      • 6: Master’s degree/Postgraduate degree

      • 7: Doctorate/PhD

      These values are not a fixed list and can be translated into many languages. Multiple concepts can also represent the same level, therefore it is not possible to determine exactly the level used in the janzz.

    Full example of match explain (for performance reasons, empty lists will be ommitted from the result):

    {
    "extra": {
      {
        "total_experience_level": {
          "source": 2,
          "target": 6
        },
        "highest_education_level": {
          "source": 2,
          "target": 5
        }
      }
    },
    "matched": {
        "function": [],
        "specialization": [],
        "language": [],
        "industry": [],
        "softskill": [{
            "score": 1.0,
            "type": "concept",
            "label_target": "Responsable",
            "label_source": "Responsabilidad"
        }, {
            "score": 1.0,
            "type": "concept",
            "label_target": "Honesta",
            "label_source": "Honradez"
        }, {
            "score": 0.5,
            "type": "concept",
            "label_target": "Responsable",
            "label_source": "Seriedad"
        }, {
            "score": 1.0,
            "type": "concept",
            "label_target": "Relación interpersonal",
            "label_source": "Buen manejo de relaciones interpersonales"
        }],
        "custom": [],
        "experience": [{
            "score": 1.0,
            "type": "total_experience_level",
            "label_target": null,
            "label_source": null
        }],
        "contract_type": [],
        "skill": [{
            "score": 1.0,
            "type": "concept",
            "label_target": "Atencion y servicio a clientes",
            "label_source": "Atención a cliente"
        }],
        "education": [{
            "score": 1.0,
            "type": "highest_education_level",
            "label_target": null,
            "label_source": null
        }],
        "authorization": [],
        "occupation": [{
            "score": 0.5,
            "type": "concept",
            "label_target": "Mesero",
            "label_source": "Barman"
        }]
    },
    "not_matched_source": {
        "function": [],
        "specialization": [],
        "language": [],
        "industry": [],
        "softskill": [{
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Paciencia"
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Agilidad"
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Respeto"
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Concentración"
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Positivismo"
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Buena memoria"
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Amabilidad"
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "Objetividad"
        }],
        "custom": [],
        "experience": [],
        "contract_type": [],
        "skill": [],
        "education": [{
            "score": 0.0,
            "type": "concept",
            "label_target": null,
            "label_source": "bachiller "
        }],
        "authorization": [],
        "occupation": []
    },
    "not_matched_target": {
        "function": [],
        "specialization": [],
        "language": [],
        "industry": [],
        "softskill": [{
            "score": 0.0,
            "type": "concept",
            "label_target": "Puntual",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Persuasión",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Dinámica",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Fluidez verbal",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Agil",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Líder",
            "label_source": null
        }],
        "custom": [],
        "experience": [{
            "score": 0.0,
            "type": "concept",
            "label_target": "Administrador punto de venta",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Mesero",
            "label_source": null
        }],
        "contract_type": [],
        "skill": [{
            "score": 0.0,
            "type": "concept",
            "label_target": "Manejo de caja",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Manejo de dinero",
            "label_source": null
        }],
        "education": [{
            "score": 0.0,
            "type": "concept",
            "label_target": "Abogado",
            "label_source": null
        }],
        "authorization": [],
        "occupation": [{
            "score": 0.0,
            "type": "concept",
            "label_target": "Asistente de abogado",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Cajero",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Asistente de juzgado",
            "label_source": null
        }, {
            "score": 0.0,
            "type": "concept",
            "label_target": "Auxiliar de salas de cine",
            "label_source": null
        }]
    }
}

occupation correlations

API endpoint to display correlation between janzz’s occupation and the “position” fields of its experience

URL

https://www.janzz.jobs/japi/occupation_correlations/{id}
https://www.janzz.jobs/japi/occupation_correlations_internal/{id}

ALLOWABLE METHODS

GET

SAMPLE RESPONSE

{
    "occupation": {
        "label": "Rengjøringshjelp (bedrift)",
        "cid": 20477
    },
    "correlations": [
        {
            "cor": 1,
            "best_label": "Renholdsarbeider (bedrift)",
            "cid": 20477
        },
        {
            "cor": 0.15,
            "best_label": "Hjelpearbeider (industri)",
            "cid": 153637
        }
    ],
    "max_correlation": 1
}

RESPONSE FIELDS

  • occupation - details about the concept corresponding to the janzz occupation

  • correlations - list of concepts corresponding to “position” field of a janzz and their correlation to the occupation

  • max_correlation - helper which shows the maximum correlation in the results, or 0 if no correlations are found

concept search - DEPRECATED

API endpoint to search for janzzs using concept labels. This endpoint has been deprecated and replaced by janzz search json.

URL

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

match explain concepts - DEPRECATED

API endpoint which describes how a match is made given a list of concepts which were searched for. This endpoint has been deprecated. The janzz search json endpoint returns a janzz id which can be used for match explain.

URL

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