add new endpoints

Author: JW Wesson

src/main/java/com/sovren/SovrenClient.java

@@ -19,13 +19,16 @@
 import com.sovren.models.api.dataenrichment.professions.response.GetProfessionsTaxonomyResponseValue;
 import com.sovren.models.api.dataenrichment.ontology.request.CompareProfessionsRequest;
 import com.sovren.models.api.dataenrichment.ontology.request.CompareSkillsToProfessionRequest;
+import com.sovren.models.api.dataenrichment.ontology.request.SkillsSimilarityScoreRequest;
 import com.sovren.models.api.dataenrichment.ontology.request.SuggestProfessionsRequest;
 import com.sovren.models.api.dataenrichment.ontology.request.SuggestSkillsFromProfessionsRequest;
+import com.sovren.models.api.dataenrichment.ontology.request.SuggestSkillsFromSkillsRequest;
 import com.sovren.models.api.dataenrichment.ontology.response.CompareProfessionsResponse;
 import com.sovren.models.api.dataenrichment.ontology.response.CompareSkillsToProfessionResponse;
 import com.sovren.models.api.dataenrichment.ontology.response.SuggestProfessionsResponse;
 import com.sovren.models.api.dataenrichment.ontology.response.SuggestSkillsResponse;
 import com.sovren.models.api.dataenrichment.ontology.response.SkillScore;
+import com.sovren.models.api.dataenrichment.ontology.response.SkillsSimilarityScoreResponse;
 import com.sovren.models.api.dataenrichment.professions.request.LookupProfessionCodesRequest;
 import com.sovren.models.api.dataenrichment.professions.request.NormalizeProfessionsRequest;
 import com.sovren.models.api.dataenrichment.professions.response.GetProfessionsTaxonomyResponse;
@@ -1861,7 +1864,7 @@ public SuggestProfessionsResponse suggestProfessionsFromSkills(ParsedJob job) th
 
     /**
      * Suggest professions based on a given set of skills.
-     * @param skillIds The skills used to return the most relevant professions. The list can contain up to 50 skills.
+     * @param skills The skills used to return the most relevant professions. The list can contain up to 50 skills.
      * @param limit The maximum amount of professions returned. If not sure what value should be, provide 10 as default limit.
      * @param returnMissingSkills Flag to enable returning a list of missing skills per suggested profession.
      * @param outputLanguage The language to use for the returned descriptions. If not provided, no descriptions are returned. Must be one of the supported <a href="https://sovren.com/technical-specs/latest/rest-api/data-enrichment/overview/#professions-languages">ISO code</a>
@@ -1902,4 +1905,141 @@ public SuggestProfessionsResponse suggestProfessionsFromSkills(List<String> skil
             .collect(Collectors.toList());
         return suggestProfessionsFromSkills(skills, 10, false, outputLanguage);
     }
+
+    /**
+     * Returns skills related to a given skill or 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.
+     * @param skills The skills (and optionally, scores) for which the service should return related skills. The list can contain up to 50 skills.
+     * @param limit The maximum amount of suggested skills returned. The maximum is 25.
+     * @param outputLanguage The language to use for the returned descriptions. If not provided, no descriptions are returned. Must be one of the supported <a href="https://sovren.com/technical-specs/latest/rest-api/data-enrichment/overview/#skills-languages">ISO code</a>
+     * @return The API response body
+     * @throws SovrenException Thrown when an API error occurs
+     */
+    public SuggestSkillsResponse suggestSkillsFromSkills(
+        List<SkillScore> skills,
+        int limit,
+        String outputLanguage) throws SovrenException {
+        SuggestSkillsFromSkillsRequest request = new SuggestSkillsFromSkillsRequest();
+        request.Skills = skills;
+        request.Limit = limit;
+        request.OutputLanguage = outputLanguage;
+
+        RequestBody body = createJsonBody(request);
+        Request apiRequest = new Request.Builder()
+            .url(_endpoints.desOntologySuggestSkillsFromSkills())
+            .post(body)
+            .build();
+
+        HttpResponse<SuggestSkillsResponse> response = executeRequest(apiRequest, SuggestSkillsResponse.class, getBodyIfDebug(apiRequest));
+        return response.getData();
+    }
+
+    /**
+     * Returns skills related to a given skill or 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.
+     * @param skillIds The skill IDs for which the service should return related skills. The list can contain up to 50 skills.
+     * @param outputLanguage The language to use for the returned descriptions. If not provided, no descriptions are returned. Must be one of the supported <a href="https://sovren.com/technical-specs/latest/rest-api/data-enrichment/overview/#skills-languages">ISO code</a>
+     * @return The API response body
+     * @throws SovrenException Thrown when an API error occurs
+     */
+    public SuggestSkillsResponse suggestSkillsFromSkills(List<String> skillIds, String outputLanguage) throws SovrenException {
+        return suggestSkillsFromSkills(skillIds.stream().map(s -> new SkillScore(s)).collect(Collectors.toList()), 25, outputLanguage);
+    }
+
+    /**
+     * Suggests skills related to a job (but not in the job) based on the skills in the job. 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.
+     * @param job The job to suggest skills for (based on the skills in the job).
+     * @param limit The maximum amount of suggested skills returned. The maximum is 25.
+     * @param outputLanguage The language to use for the returned descriptions. If not provided, no descriptions are returned. Must be one of the supported <a href="https://sovren.com/technical-specs/latest/rest-api/data-enrichment/overview/#skills-languages">ISO code</a>
+     * @return The API response body
+     * @throws SovrenException Thrown when an API error occurs
+     */
+    public SuggestSkillsResponse suggestSkillsFromSkills(
+        ParsedJob job,
+        int limit,
+        String outputLanguage) throws SovrenException {
+        if(job != null && job.Skills != null && job.Skills.Normalized != null && job.Skills.Normalized.size() > 0){
+            List<SkillScore> skills = new ArrayList<SkillScore>();
+            int amountOfSkills = job.Skills.Normalized.size() > 50 ? 50 : job.Skills.Normalized.size();
+            for(int i = 0; i < amountOfSkills; i++) {
+                skills.add(new SkillScore(job.Skills.Normalized.get(i).Id));
+            }
+
+            return suggestSkillsFromSkills(skills, limit, outputLanguage);
+        }
+        throw new IllegalArgumentException("The job must be parsed with V2 skills selected, and with skills normalization enabled");
+    }
+
+    /**
+     * Suggests skills related to a job (but not in the job) based on the skills in the job. 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.
+     * @param job The job to suggest skills for (based on the skills in the job).
+     * @param outputLanguage The language to use for the returned descriptions. If not provided, no descriptions are returned. Must be one of the supported <a href="https://sovren.com/technical-specs/latest/rest-api/data-enrichment/overview/#skills-languages">ISO code</a>
+     * @return The API response body
+     * @throws SovrenException Thrown when an API error occurs
+     */
+    public SuggestSkillsResponse suggestSkillsFromSkills(ParsedJob job, String outputLanguage) throws SovrenException {
+        return suggestSkillsFromSkills(job, 25, outputLanguage);
+    }
+
+    /**
+     * Suggests skills related to a resume (but not in the resume) based on the skills in the resume. 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.
+     * @param resume The resume to suggest skills for (based on the skills in the resume).
+     * @param limit The maximum amount of suggested skills returned. The maximum is 25.
+     * @param outputLanguage The language to use for the returned descriptions. If not provided, no descriptions are returned. Must be one of the supported <a href="https://sovren.com/technical-specs/latest/rest-api/data-enrichment/overview/#skills-languages">ISO code</a>
+     * @param weightSkillsByExperience Whether or not to give a higher weight to skills that the candidate has more experience with.
+     * @return The API response body
+     * @throws SovrenException Thrown when an API error occurs
+     */
+    public SuggestSkillsResponse suggestSkillsFromSkills(
+        ParsedResume resume,
+        int limit,
+        String outputLanguage,
+        boolean weightSkillsByExperience) throws SovrenException {
+        return suggestSkillsFromSkills(getNormalizedSkillsFromResume(resume, weightSkillsByExperience), limit, outputLanguage);
+    }
+
+    /**
+     * Suggests skills related to a resume (but not in the resume) based on the skills in the resume. 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.
+     * @param resume The resume to suggest skills for (based on the skills in the resume).
+     * @param outputLanguage The language to use for the returned descriptions. If not provided, no descriptions are returned. Must be one of the supported <a href="https://sovren.com/technical-specs/latest/rest-api/data-enrichment/overview/#skills-languages">ISO code</a>
+     * @return The API response body
+     * @throws SovrenException Thrown when an API error occurs
+     */
+    public SuggestSkillsResponse suggestSkillsFromSkills(ParsedResume resume, String outputLanguage) throws SovrenException {
+        return suggestSkillsFromSkills(resume, 25, outputLanguage, true);
+    }
+
+    /**
+     * Determines how closely related one set of skills is to another. The service defines closely related skills
+     * such that knowing a skill either implies knowledge about another skill, or should make it considerably
+     * easier to acquire knowledge about that skill.
+     * @param skillSetA A set of skills (and optionally, scores) to score against the other set of skills. The list can contain up to 50 skills.
+     * @param skillSetB A set of skills (and optionally, scores) to score against the other set of skills. The list can contain up to 50 skills.
+     * @return The API response body
+     * @throws SovrenException Thrown when an API error occurs
+     */
+    public SkillsSimilarityScoreResponse skillsSimilarityScore(List<SkillScore> skillSetA, List<SkillScore> skillSetB) throws SovrenException {
+        SkillsSimilarityScoreRequest request = new SkillsSimilarityScoreRequest();
+        request.SkillsA = skillSetA;
+        request.SkillsB = skillSetB;
+        
+        RequestBody body = createJsonBody(request);
+        Request apiRequest = new Request.Builder()
+            .url(_endpoints.desOntologySkillsSimilarityScore())
+            .post(body)
+            .build();
+
+        HttpResponse<SkillsSimilarityScoreResponse> response = executeRequest(apiRequest, SkillsSimilarityScoreResponse.class, getBodyIfDebug(apiRequest));
+        return response.getData();
+    }
 }

src/main/java/com/sovren/models/api/dataenrichment/ontology/request/SkillsSimilarityScoreRequest.java

@@ -0,0 +1,18 @@
+// Copyright © 2020 Sovren Group, Inc. All rights reserved.
+// This file is provided for use by, or on behalf of, Sovren licensees
+// within the terms of their license of Sovren products or Sovren customers
+// within the Terms of Service pertaining to the Sovren SaaS products.
+
+package com.sovren.models.api.dataenrichment.ontology.request;
+
+import java.util.List;
+
+import com.sovren.models.api.dataenrichment.ontology.response.SkillScore;
+
+/** Request body for a 'SuggestProfessions' request  */
+public class SkillsSimilarityScoreRequest {
+    /** A set of skills (and optionally, scores) to score against the other set of skills. The list can contain up to 50 skills. */
+    public List<SkillScore> SkillsA;
+    /** A set of skills (and optionally, scores) to score against the other set of skills. The list can contain up to 50 skills. */
+    public List<SkillScore> SkillsB;
+}

src/main/java/com/sovren/models/api/dataenrichment/ontology/request/SuggestSkillsFromSkillsRequest.java

@@ -0,0 +1,20 @@
+// Copyright © 2020 Sovren Group, Inc. All rights reserved.
+// This file is provided for use by, or on behalf of, Sovren licensees
+// within the terms of their license of Sovren products or Sovren customers
+// within the Terms of Service pertaining to the Sovren SaaS products.
+
+package com.sovren.models.api.dataenrichment.ontology.request;
+
+import java.util.List;
+
+import com.sovren.models.api.dataenrichment.ontology.response.SkillScore;
+
+/** Request body for a 'SuggestProfessions' request  */
+public class SuggestSkillsFromSkillsRequest {
+    /** The skills for which the service should return related skills. The list can contain up to 50 skills. */
+    public List<SkillScore> Skills;
+    /** The maximum amount of suggested skills returned. If not specified this parameter defaults to 25. */
+    public int Limit = 25;
+    /** The language to use for the returned descriptions. */
+    public String OutputLanguage;
+}

src/main/java/com/sovren/models/api/dataenrichment/ontology/response/SkillsSimilarityScoreResponse.java

@@ -0,0 +1,12 @@
+// Copyright © 2020 Sovren Group, Inc. All rights reserved.
+// This file is provided for use by, or on behalf of, Sovren licensees
+// within the terms of their license of Sovren products or Sovren customers
+// within the Terms of Service pertaining to the Sovren SaaS products.
+
+package com.sovren.models.api.dataenrichment.ontology.response;
+
+import com.sovren.models.api.ApiResponse;
+
+/** The response body from a SuggestSkills API call*/
+public class SkillsSimilarityScoreResponse extends ApiResponse<SkillsSimilarityScoreResponseValue> {
+}

src/main/java/com/sovren/models/api/dataenrichment/ontology/response/SkillsSimilarityScoreResponseValue.java

@@ -0,0 +1,13 @@
+// Copyright © 2020 Sovren Group, Inc. All rights reserved.
+// This file is provided for use by, or on behalf of, Sovren licensees
+// within the terms of their license of Sovren products or Sovren customers
+// within the Terms of Service pertaining to the Sovren SaaS products.
+
+package com.sovren.models.api.dataenrichment.ontology.response;
+import com.sovren.models.api.ApiResponse;
+
+/** One entry in the {@link ApiResponse#Value} from a 'skills Similarity Score' response */
+public class SkillsSimilarityScoreResponseValue {
+    /** A value from [0 - 1] representing how closely related skill set A and skill set B are, based on the relations between skills. */
+    public float SimilarityScore;
+}

src/test/java/com/sovren/integration/DataEnrichmentServiceTests.java

@@ -135,6 +135,17 @@ public void testSuggestSkillsFromProfessions() {
         });
     }
 
+    @Test
+    public void testSuggestSkillsFromSkills() {
+        assertDoesNotThrow(() -> {
+            ArrayList<String> skillIds = new ArrayList<String>();
+            skillIds.add("KS120076FGP5WGWYMP0F");
+            skillIds.add("KS125HH5XDBPZT3RFGZZ");
+            skillIds.add("KS124PR62MV42B5C9S9F");
+            Client.suggestSkillsFromSkills(skillIds, null);
+        });
+    }
+
     @Test
     public void testSuggestProfessions() {
         assertDoesNotThrow(() -> {
@@ -145,4 +156,15 @@ public void testSuggestProfessions() {
             Client.suggestProfessionsFromSkills(skillIds, null);
         });
     }
+
+    @Test
+    public void testSkillsSimilarityScore() {
+        assertDoesNotThrow(() -> {
+            ArrayList<SkillScore> skillIds = new ArrayList<SkillScore>();
+            skillIds.add(new SkillScore("KS120076FGP5WGWYMP0F"));
+            skillIds.add(new SkillScore("KS125HH5XDBPZT3RFGZZ"));
+            skillIds.add(new SkillScore("KS124PR62MV42B5C9S9F"));
+            Client.skillsSimilarityScore(skillIds, skillIds);
+        });
+    }
 }