Custom Ranking (v3)

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.


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 job search service. It leverages the values provided in any customer defined combination of the custom attributes.

Use Case

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

A company has two nearly identical job listings with job-A having a higher cost per click (CPC) than job-B. Custom ranking can be used to increase the visibility of job-A by setting the ranking of the CPC custom attribute adjusted 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. Now 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 that uses two custom attributes, cpc_value and freshness_value, and sets the custom ranking expression to (cpc_value / 2) - freshness_value.


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

public static SearchJobsResponse customRanking(String companyName) throws IOException {
  // Make sure to set the requestMetadata the same as the associated search request
  RequestMetadata requestMetadata =
      new RequestMetadata()
          // Make sure to hash your userID
          // Make sure to hash the sessionID
          // Domain of the website where the search is conducted

  CustomRankingInfo customRankingInfo = new CustomRankingInfo()
      // Both cpc_value and freshness_value are customAttributes for job.
      .setRankingExpression("cpc_value / 2 - freshness_value")

  SearchJobsRequest request =
      new SearchJobsRequest()
          .setOrderBy("custom_ranking desc")
  if (companyName != null) {
    request.setJobQuery(new JobQuery().setCompanyNames(Arrays.asList(companyName)));

  SearchJobsResponse response =
          .searchForAlert(DEFAULT_PROJECT_ID, request)
  return response;


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

def custom_ranking(client_service, company_name):
    request_metadata = {
        'user_id': 'HashedUserId',
        'session_id': 'HashedSessionId',
        'domain': ''
    custom_ranking_info = {
        'ranking_expression': 'cpc_value / 2 - freshness_value',
        'importance_level': 'EXTREME'
    request = {
        'search_mode': 'JOB_SEARCH',
        'request_metadata': request_metadata,
        'order_by': 'custom_ranking desc',
        'custom_ranking_info': custom_ranking_info
    if company_name is not None:
        request.update({'job_query': {'company_names': [company_name]}})

    response = client_service.projects().jobs().search(
        parent=parent, body=request).execute()
    return response