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.


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.


import (

	talent ""
	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: %v", err)

	// 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: "",
		JobQuery: &talentpb.JobQuery{
			Companies: []string{fmt.Sprintf("projects/%s/companies/%s", projectID, companyID)},
		// More info on 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: %v", err)

	for _, job := range resp.GetMatchingJobs() {
		fmt.Fprintf(w, "Job: %q\n", job.GetJob().GetName())

	return nil


For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.


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 {
    try (JobServiceClient jobServiceClient = JobServiceClient.create()) {
      TenantName parent = TenantName.of(projectId, tenantId);
      String domain = "";
      String sessionId = "Hashed session identifier";
      String userId = "Hashed user identifier";
      RequestMetadata requestMetadata =
      SearchJobsRequest.CustomRankingInfo.ImportanceLevel importanceLevel =
      String rankingExpression = "(someFieldLong + 25) * 0.25";
      SearchJobsRequest.CustomRankingInfo customRankingInfo =
      String orderBy = "custom_ranking desc";
      SearchJobsRequest request =
      for (SearchJobsResponse.MatchingJob responseItem :
          jobServiceClient.searchJobs(request).iterateAll()) {
        System.out.printf("Job summary: %s\n", responseItem.getJobSummary());
        System.out.printf("Job title snippet: %s\n", responseItem.getJobTitleSnippet());
        Job job = responseItem.getJob();
        System.out.printf("Job name: %s\n", job.getName());
        System.out.printf("Job title: %s\n", job.getTitle());


For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.

require __DIR__ . '/vendor/autoload.php';

use Google\Cloud\Talent\V4beta1\JobServiceClient;
use Google\Cloud\Talent\V4beta1\RequestMetadata;
use Google\Cloud\Talent\V4beta1\SearchJobsRequest_CustomRankingInfo;
use Google\Cloud\Talent\V4beta1\SearchJobsRequest_CustomRankingInfo_ImportanceLevel;

 * Search Jobs using custom rankings.
 * @param string $projectId Your Google Cloud Project ID
 * @param string $tenantId  Identifier of the Tenantd
function sampleSearchJobs($projectId, $tenantId)

    $jobServiceClient = new JobServiceClient();

    // $projectId = 'Your Google Cloud Project ID';
    // $tenantId = 'Your Tenant ID (using tenancy is optional)';
    $formattedParent = $jobServiceClient->tenantName($projectId, $tenantId);
    $domain = '';
    $sessionId = 'Hashed session identifier';
    $userId = 'Hashed user identifier';
    $requestMetadata = new RequestMetadata();
    $importanceLevel = SearchJobsRequest_CustomRankingInfo_ImportanceLevel::EXTREME;
    $rankingExpression = '(someFieldLong + 25) * 0.25';
    $customRankingInfo = new SearchJobsRequest_CustomRankingInfo();
    $orderBy = 'custom_ranking desc';

    try {
        // Iterate through all elements
        $pagedResponse = $jobServiceClient->searchJobs($formattedParent, $requestMetadata, ['customRankingInfo' => $customRankingInfo, 'orderBy' => $orderBy]);
        foreach ($pagedResponse->iterateAllElements() as $responseItem) {
            printf('Job summary: %s'.PHP_EOL, $responseItem->getJobSummary());
            printf('Job title snippet: %s'.PHP_EOL, $responseItem->getJobTitleSnippet());
            $job = $responseItem->getJob();
            printf('Job name: %s'.PHP_EOL, $job->getName());
            printf('Job title: %s'.PHP_EOL, $job->getTitle());
    } finally {



For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.

# Search Jobs using custom rankings
# @param project_id {String} Your Google Cloud Project ID
# @param tenant_id {String} Identifier of the Tenantd
def sample_search_jobs project_id, tenant_id
  # Instantiate a client
  job_client = version: :v4beta1

  # project_id = "Your Google Cloud Project ID"
  # tenant_id = "Your Tenant ID (using tenancy is optional)"
  formatted_parent = job_client.class.tenant_path(project_id, tenant_id)
  domain = ""
  session_id = "Hashed session identifier"
  user_id = "Hashed user identifier"
  request_metadata = {
    domain: domain,
    session_id: session_id,
    user_id: user_id
  importance_level = :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.
  job_client.search_jobs(formatted_parent, request_metadata, custom_ranking_info: custom_ranking_info, order_by: order_by).each do |element|
    puts "Job summary: #{element.job_summary}"
    puts "Job title snippet: #{element.job_title_snippet}"
    job = element.job
    puts "Job name: #{}"
    puts "Job title: #{job.title}"


For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.

public static object CustomRankingSearch(string projectId, string tenantId)
    JobServiceClient jobServiceClient = JobServiceClient.Create();
    TenantName name = TenantName.FromProjectTenant(projectId, tenantId);

    string domain = "";
    string sessionId = "Hashed session identifier";
    string userId = "Hashed user identifier";
    RequestMetadata requestMetadata = new RequestMetadata
        Domain = domain,
        SessionId = sessionId,
        UserId = userId

    CustomRankingInfo customRankingInfo = new CustomRankingInfo
        ImportanceLevel = ImportanceLevel.Extreme,
        // Custom ranking supports math operators, and Field name can be CPC or Freshness
        RankingExpression = "(someFieldLong + 25) * 0.25"
    string orderBy = "custom_ranking desc";

    SearchJobsRequest request = new SearchJobsRequest
        ParentAsTenantName = name,
        CustomRankingInfo = customRankingInfo,
        RequestMetadata = requestMetadata,
        OrderBy = orderBy

    var response = jobServiceClient.SearchJobs(request);
    foreach (var result in response)
        Console.WriteLine($"Job summary: {result.JobSummary}");
        Console.WriteLine($"Job title snippet: {result.JobTitleSnippet}");
        Job job = result.Job;
        Console.WriteLine($"Job name: {job.Name}");
        Console.WriteLine($"Job title: {job.Title}");

    return 0;