Custom Ranking

The custom ranking feature allows you to introduce your own business logic to control the ranking of jobs returned by Cloud Talent Solution. A job seeker searching on a site can set their search query and other filters as always, and you can add a ranking expression to the search request. Cloud Talent Solution determines the relevant jobs to the query defined by the job seeker, and ranks the results based on the custom ranking expression. This ranked list is then returned to you so that you can display it to the job seeker. A video tutorial on implementing custom ranking is also available .

Benefits

Custom ranking allows you to control on how the results are listed. Using a custom ranking lets you define weights you can assign to custom attributes. You can use a combination of weights and custom attributes to build a custom ranking expression to determine the order the returned listings.

Custom ranking is built on the existing search service. It leverages the values provided in any customer-defined combination of the custom attributes.

Example use case

The end user searches for "Software Engineer". Your business wants to showcase higher return listings for "Software Engineer". Using Custom Ranking allows you to place a value on these listings and show them to the end user in the order determined by the custom ranking expression.

For example, you have two nearly identical job listings with job-A having a higher cost per click (CPC) value than job-B. You can use custom ranking to increase the visibility of job-A by setting the adjusting the ranking of the CPC custom attribute with weights.

How to use

Custom ranking supports the following mathematical operators: + , - , * , / , ( , )

You can use the field names of custom attributes and these mathematical operators to define a custom ranking expression.

For example, consider that you have two custom attributes: CPC and freshness, where freshness is the number of days since the job was posted. You want to rank jobs by CPC and freshness, where CPC counts for 75% of the ranking and freshness counts for 25%. You can create a custom ranking expression as follows:

(0.75*CPC) + (0.25 *Freshness)

Code Sample

The following example creates a custom ranking expression using two custom attributes, cpc_value and freshness_value . It sets the custom ranking expression to (cpc_value / 2) - freshness_value .

Go

To learn how to install and use the client library for CTS, see CTS client libraries . For more information, see the CTS Go API reference documentation .

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 talent 
  
 "cloud.google.com/go/talent/apiv4beta1" 
  
 "cloud.google.com/go/talent/apiv4beta1/talentpb" 
 ) 
 // customRankingSearch searches for jobs based on custom ranking. 
 func 
  
 customRankingSearch 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectID 
 , 
  
 companyID 
  
 string 
 ) 
  
 error 
  
 { 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 // Initialize a jobService client. 
  
 c 
 , 
  
 err 
  
 := 
  
 talent 
 . 
  NewJobClient 
 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "taleng.NewJobClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 c 
 . 
 Close 
 () 
  
 // Construct a searchJobs request. 
  
 req 
  
 := 
  
& talentpb 
 . 
 SearchJobsRequest 
 { 
  
 Parent 
 : 
  
 fmt 
 . 
 Sprintf 
 ( 
 "projects/%s" 
 , 
  
 projectID 
 ), 
  
 // Make sure to set the RequestMetadata the same as the associated 
  
 // search request. 
  
 RequestMetadata 
 : 
  
& talentpb 
 . 
 RequestMetadata 
 { 
  
 // Make sure to hash your userID. 
  
 UserId 
 : 
  
 "HashedUsrID" 
 , 
  
 // Make sure to hash the sessionID. 
  
 SessionId 
 : 
  
 "HashedSessionID" 
 , 
  
 // Domain of the website where the search is conducted. 
  
 Domain 
 : 
  
 "www.googlesample.com" 
 , 
  
 }, 
  
 JobQuery 
 : 
  
& talentpb 
 . 
 JobQuery 
 { 
  
 Companies 
 : 
  
 [] 
 string 
 { 
 fmt 
 . 
 Sprintf 
 ( 
 "projects/%s/companies/%s" 
 , 
  
 projectID 
 , 
  
 companyID 
 )}, 
  
 }, 
  
 // More info on customRankingInfo. 
  
 // https://godoc.org/google.golang.org/genproto/googleapis/cloud/talent/v4beta1#SearchJobsRequest_CustomRankingInfo 
  
 CustomRankingInfo 
 : 
  
& talentpb 
 . 
 SearchJobsRequest_CustomRankingInfo 
 { 
  
 ImportanceLevel 
 : 
  
 talentpb 
 . 
  SearchJobsRequest_CustomRankingInfo_EXTREME 
 
 , 
  
 RankingExpression 
 : 
  
 "(someFieldLong + 25) * 0.25" 
 , 
  
 }, 
  
 OrderBy 
 : 
  
 "custom_ranking desc" 
 , 
  
 } 
  
 resp 
 , 
  
 err 
  
 := 
  
 c 
 . 
 SearchJobs 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "SearchJobs: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 for 
  
 _ 
 , 
  
 job 
  
 := 
  
 range 
  
 resp 
 . 
 GetMatchingJobs 
 () 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Job: %q\n" 
 , 
  
 job 
 . 
 GetJob 
 (). 
 GetName 
 ()) 
  
 } 
  
 return 
  
 nil 
 }

Java

To learn how to install and use the client library for CTS, see CTS client libraries . For more information, see the CTS Java API reference documentation .

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 com.google.cloud.talent.v4. Job 
 
 ; 
 import 
  
 com.google.cloud.talent.v4. JobServiceClient 
 
 ; 
 import 
  
 com.google.cloud.talent.v4. RequestMetadata 
 
 ; 
 import 
  
 com.google.cloud.talent.v4. SearchJobsRequest 
 
 ; 
 import 
  
 com.google.cloud.talent.v4. SearchJobsResponse 
 
 ; 
 import 
  
 com.google.cloud.talent.v4. TenantName 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 CustomRankingSearchJobs 
  
 { 
  
 public 
  
 static 
  
 void 
  
 searchCustomRankingJobs 
 () 
  
 throws 
  
 IOException 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 String 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ; 
  
 String 
  
 tenantId 
  
 = 
  
 "your-tenant-id" 
 ; 
  
 searchCustomRankingJobs 
 ( 
 projectId 
 , 
  
 tenantId 
 ); 
  
 } 
  
 // Search Jobs using custom rankings. 
  
 public 
  
 static 
  
 void 
  
 searchCustomRankingJobs 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 tenantId 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. After completing all of your requests, call 
  
 // the "close" method on the client to safely clean up any remaining background resources. 
  
 try 
  
 ( 
  JobServiceClient 
 
  
 jobServiceClient 
  
 = 
  
  JobServiceClient 
 
 . 
 create 
 ()) 
  
 { 
  
  TenantName 
 
  
 parent 
  
 = 
  
  TenantName 
 
 . 
 of 
 ( 
 projectId 
 , 
  
 tenantId 
 ); 
  
 String 
  
 domain 
  
 = 
  
 "www.example.com" 
 ; 
  
 String 
  
 sessionId 
  
 = 
  
 "Hashed session identifier" 
 ; 
  
 String 
  
 userId 
  
 = 
  
 "Hashed user identifier" 
 ; 
  
  RequestMetadata 
 
  
 requestMetadata 
  
 = 
  
  RequestMetadata 
 
 . 
 newBuilder 
 () 
  
 . 
  setDomain 
 
 ( 
 domain 
 ) 
  
 . 
  setSessionId 
 
 ( 
 sessionId 
 ) 
  
 . 
  setUserId 
 
 ( 
 userId 
 ) 
  
 . 
 build 
 (); 
  
  SearchJobsRequest 
 
 . 
  CustomRankingInfo 
 
 . 
  ImportanceLevel 
 
  
 importanceLevel 
  
 = 
  
  SearchJobsRequest 
 
 . 
 CustomRankingInfo 
 . 
 ImportanceLevel 
 . 
 EXTREME 
 ; 
  
 String 
  
 rankingExpression 
  
 = 
  
 "(someFieldLong + 25) * 0.25" 
 ; 
  
  SearchJobsRequest 
 
 . 
  CustomRankingInfo 
 
  
 customRankingInfo 
  
 = 
  
  SearchJobsRequest 
 
 . 
 CustomRankingInfo 
 . 
 newBuilder 
 () 
  
 . 
  setImportanceLevel 
 
 ( 
 importanceLevel 
 ) 
  
 . 
  setRankingExpression 
 
 ( 
 rankingExpression 
 ) 
  
 . 
 build 
 (); 
  
 String 
  
 orderBy 
  
 = 
  
 "custom_ranking desc" 
 ; 
  
  SearchJobsRequest 
 
  
 request 
  
 = 
  
  SearchJobsRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setParent 
 ( 
 parent 
 . 
  toString 
 
 ()) 
  
 . 
  setRequestMetadata 
 
 ( 
 requestMetadata 
 ) 
  
 . 
  setCustomRankingInfo 
 
 ( 
 customRankingInfo 
 ) 
  
 . 
  setOrderBy 
 
 ( 
 orderBy 
 ) 
  
 . 
 build 
 (); 
  
 for 
  
 ( 
  SearchJobsResponse 
 
 . 
  MatchingJob 
 
  
 responseItem 
  
 : 
  
 jobServiceClient 
 . 
 searchJobs 
 ( 
 request 
 ). 
 getMatchingJobsList 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "Job summary: %s%n" 
 , 
  
 responseItem 
 . 
 getJobSummary 
 ()); 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "Job title snippet: %s%n" 
 , 
  
 responseItem 
 . 
 getJobTitleSnippet 
 ()); 
  
  Job 
 
  
 job 
  
 = 
  
 responseItem 
 . 
 getJob 
 (); 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "Job name: %s%n" 
 , 
  
 job 
 . 
  getName 
 
 ()); 
  
 System 
 . 
 out 
 . 
 format 
 ( 
 "Job title: %s%n" 
 , 
  
 job 
 . 
  getTitle 
 
 ()); 
  
 } 
  
 } 
  
 } 
 }

Node.js

To learn how to install and use the client library for CTS, see CTS client libraries . For more information, see the CTS Node.js API reference documentation .

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  const 
  
 talent 
  
 = 
  
 require 
 ( 
 ' @google-cloud/talent 
' 
 ). 
 v4 
 ; 
 /** 
 * Search Jobs using custom rankings 
 * 
 * @param projectId {string} Your Google Cloud Project ID 
 * @param tenantId {string} Identifier of the Tenantd 
 */ 
 function 
  
 sampleSearchJobs 
 ( 
 projectId 
 , 
  
 tenantId 
 ) 
  
 { 
  
 const 
  
 client 
  
 = 
  
 new 
  
 talent 
 . 
  JobServiceClient 
 
 (); 
  
 // Iterate over all elements. 
  
 // const projectId = 'Your Google Cloud Project ID'; 
  
 // const tenantId = 'Your Tenant ID (using tenancy is optional)'; 
  
 const 
  
 formattedParent 
  
 = 
  
 client 
 . 
 tenantPath 
 ( 
 projectId 
 , 
  
 tenantId 
 ); 
  
 const 
  
 domain 
  
 = 
  
 'www.example.com' 
 ; 
  
 const 
  
 sessionId 
  
 = 
  
 'Hashed session identifier' 
 ; 
  
 const 
  
 userId 
  
 = 
  
 'Hashed user identifier' 
 ; 
  
 const 
  
 requestMetadata 
  
 = 
  
 { 
  
 domain 
 : 
  
 domain 
 , 
  
 sessionId 
 : 
  
 sessionId 
 , 
  
 userId 
 : 
  
 userId 
 , 
  
 }; 
  
 const 
  
 importanceLevel 
  
 = 
  
 'EXTREME' 
 ; 
  
 const 
  
 rankingExpression 
  
 = 
  
 '(someFieldLong + 25) * 0.25' 
 ; 
  
 const 
  
 customRankingInfo 
  
 = 
  
 { 
  
 importanceLevel 
 : 
  
 importanceLevel 
 , 
  
 rankingExpression 
 : 
  
 rankingExpression 
 , 
  
 }; 
  
 const 
  
 orderBy 
  
 = 
  
 'custom_ranking desc' 
 ; 
  
 const 
  
 request 
  
 = 
  
 { 
  
 parent 
 : 
  
 formattedParent 
 , 
  
 requestMetadata 
 : 
  
 requestMetadata 
 , 
  
 customRankingInfo 
 : 
  
 customRankingInfo 
 , 
  
 orderBy 
 : 
  
 orderBy 
 , 
  
 }; 
  
 client 
  
 . 
 searchJobs 
 ( 
 request 
 ) 
  
 . 
 then 
 ( 
 responses 
  
 = 
>  
 { 
  
 for 
  
 ( 
 const 
  
 resources 
  
 of 
  
 responses 
 ) 
  
 { 
  
 for 
  
 ( 
 const 
  
 resource 
  
 of 
  
 resources 
 . 
 matchingJobs 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Job summary: 
 ${ 
 resource 
 . 
 jobSummary 
 } 
 ` 
 ); 
  
 console 
 . 
 log 
 ( 
 `Job title snippet: 
 ${ 
 resource 
 . 
 jobTitleSnippet 
 } 
 ` 
 ); 
  
 const 
  
 job 
  
 = 
  
 resource 
 . 
 job 
 ; 
  
 console 
 . 
 log 
 ( 
 `Job name: 
 ${ 
 job 
 . 
 name 
 } 
 ` 
 ); 
  
 console 
 . 
 log 
 ( 
 `Job title: 
 ${ 
 job 
 . 
 title 
 } 
 ` 
 ); 
  
 } 
  
 } 
  
 }) 
  
 . 
 catch 
 ( 
 err 
  
 = 
>  
 { 
  
 console 
 . 
 error 
 ( 
 err 
 ); 
  
 }); 
 }

Python

To learn how to install and use the client library for CTS, see CTS client libraries . For more information, see the CTS Python API reference documentation .

To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  from 
  
 google.cloud 
  
 import 
 talent 
 def 
  
 search_jobs 
 ( 
 project_id 
 , 
 tenant_id 
 ): 
  
 """Search Jobs using custom rankings""" 
 client 
 = 
 talent 
 . 
  JobServiceClient 
 
 () 
 # project_id = 'Your Google Cloud Project ID' 
 # tenant_id = 'Your Tenant ID (using tenancy is optional)' 
 if 
 isinstance 
 ( 
 project_id 
 , 
 bytes 
 ): 
 project_id 
 = 
 project_id 
 . 
 decode 
 ( 
 "utf-8" 
 ) 
 if 
 isinstance 
 ( 
 tenant_id 
 , 
 bytes 
 ): 
 tenant_id 
 = 
 tenant_id 
 . 
 decode 
 ( 
 "utf-8" 
 ) 
 parent 
 = 
 f 
 "projects/ 
 { 
 project_id 
 } 
 /tenants/ 
 { 
 tenant_id 
 } 
 " 
 domain 
 = 
 "www.example.com" 
 session_id 
 = 
 "Hashed session identifier" 
 user_id 
 = 
 "Hashed user identifier" 
 request_metadata 
 = 
 talent 
 . 
  RequestMetadata 
 
 ( 
 domain 
 = 
 domain 
 , 
 session_id 
 = 
 session_id 
 , 
 user_id 
 = 
 user_id 
 ) 
 importance_level 
 = 
 ( 
 talent 
 . 
  SearchJobsRequest 
 
 . 
  CustomRankingInfo 
 
 . 
  ImportanceLevel 
 
 . 
 EXTREME 
 ) 
 ranking_expression 
 = 
 "(someFieldLong + 25) * 0.25" 
 custom_ranking_info 
 = 
 { 
 "importance_level" 
 : 
 importance_level 
 , 
 "ranking_expression" 
 : 
 ranking_expression 
 , 
 } 
 order_by 
 = 
 "custom_ranking desc" 
 # Iterate over all results 
 results 
 = 
 [] 
 request 
 = 
 talent 
 . 
  SearchJobsRequest 
 
 ( 
 parent 
 = 
 parent 
 , 
 request_metadata 
 = 
 request_metadata 
 , 
 custom_ranking_info 
 = 
 custom_ranking_info 
 , 
 order_by 
 = 
 order_by 
 , 
 ) 
 for 
 response_item 
 in 
 client 
 . 
  search_jobs 
 
 ( 
 request 
 = 
 request 
 ) 
 . 
 matching_jobs 
 : 
 print 
 ( 
 f 
 "Job summary: 
 { 
 response_item 
 . 
 job_summary 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Job title snippet: 
 { 
 response_item 
 . 
 job_title_snippet 
 } 
 " 
 ) 
 job 
 = 
 response_item 
 . 
 job 
 results 
 . 
 append 
 ( 
 job 
 . 
 name 
 ) 
 print 
 ( 
 f 
 "Job name: 
 { 
 job 
 . 
 name 
 } 
 " 
 ) 
 print 
 ( 
 f 
 "Job title: 
 { 
 job 
 . 
 title 
 } 
 " 
 ) 
 return 
 results

Custom Ranking Stay organized with collections Save and categorize content based on your preferences.

Benefits

Example use case

How to use

Code Sample

Go

Java

Node.js

Python

Custom Ranking