Stay organized with collections
Save and categorize content based on your preferences.
Cloud Talent Solution allows you to get a histogram representation of the number of
jobs associated to a given search. A histogram search returns a count of all jobs
that match a particular query, broken down by the requested searchType.
For example, a histogram search could return the number of jobs per employment
type (full-time, part-time, etc) that exist in Mountain View, CA. To define the
dimensions and parameters of the histogram, follow this guide.
Histograms are generally run in parallel with a search call, using the same
JobQuery and the same requestMetadata.
Request
The histogram can be obtained from the underlying search API. This is achieved by setting the histogramFacets on the search API and defining the filters of the request. Note that the histogram observes all the filters as defined in the search query. The following example illustrates the mechanism of retrieving a histogram,
Required fields
searchTypes is a list of categories for which to return counts. For example,
specify EMPLOYMENT_TYPE to return a count of employment types, such as
full-time or part-time. See
SearchType
for a detailed list of enums.
Optional fields
jobQuery is the job query to perform in this search. See
Search Filters for more details. In this example, no query is applied.
requestMetadata contains information about the user initiating the search.
See the
RequestMetadata
section of the job search page for more information.
enableBroadening loosens the restrictions on location and job category of
the search request, in order to return more results. For example, if a
request specified jobs within a 20 mile radius of a location, setting this
flag to true may return jobs from outside of that radius. The following
example does not include broadened results.
Examples
The following example returns the list of job counts across the COMPANY_ID
and the customAttribute someFieldName1:
/** Histogram search */publicstaticvoidhistogramSearch(StringcompanyName)throwsIOException,InterruptedException{// Make sure to set the requestMetadata the same as the associated search requestRequestMetadatarequestMetadata=newRequestMetadata()// Make sure to hash your userID.setUserId("HashedUserId")// Make sure to hash the sessionID.setSessionId("HashedSessionID")// Domain of the website where the search is conducted.setDomain("www.google.com");HistogramFacetshistogramFacets=newHistogramFacets().setSimpleHistogramFacets(Arrays.asList("COMPANY_ID")).setCustomAttributeHistogramFacets(Arrays.asList(newCustomAttributeHistogramRequest().setKey("someFieldName1").setStringValueHistogram(true)));// conducted.SearchJobsRequestsearchJobsRequest=newSearchJobsRequest().setRequestMetadata(requestMetadata).setSearchMode("JOB_SEARCH").setHistogramFacets(histogramFacets);if(companyName!=null){searchJobsRequest.setJobQuery(newJobQuery().setCompanyNames(Arrays.asList(companyName)));}SearchJobsResponsesearchJobsResponse=talentSolutionClient.projects().jobs().search(DEFAULT_PROJECT_ID,searchJobsRequest).execute();Thread.sleep(1000);System.out.printf("Histogram search results: %s\n",searchJobsResponse);}
// histogramSearch searches for jobs with histogram facets.funchistogramSearch(wio.Writer,projectID,companyNamestring)(*talent.SearchJobsResponse,error){ctx:=context.Background()client,err:=google.DefaultClient(ctx,talent.CloudPlatformScope)iferr!=nil{returnnil,fmt.Errorf("google.DefaultClient: %w",err)}// Create the jobs service client.service,err:=talent.New(client)iferr!=nil{returnnil,fmt.Errorf("talent.New: %w",err)}parent:="projects/"+projectIDreq:=&talent.SearchJobsRequest{// Make sure to set the RequestMetadata the same as the associated// search request.RequestMetadata:&talent.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",},HistogramFacets:&talent.HistogramFacets{SimpleHistogramFacets:[]string{"COMPANY_ID"},CustomAttributeHistogramFacets:[]*talent.CustomAttributeHistogramRequest{{Key:"someFieldString",StringValueHistogram:true,},},},// Set the search mode to a regular search.SearchMode:"JOB_SEARCH",RequirePreciseResultSize:true,}ifcompanyName!=""{req.JobQuery=&talent.JobQuery{CompanyNames:[]string{companyName},}}resp,err:=service.Projects.Jobs.Search(parent,req).Do()iferr!=nil{returnnil,fmt.Errorf("failed to search for jobs with Historgram Facets: %w",err)}fmt.Fprintln(w,"Jobs:")for_,j:=rangeresp.MatchingJobs{fmt.Fprintf(w,"\t%q\n",j.Job.Name)}returnresp,nil}
Relevance thresholding
Histogram requests do not use relevance thresholding. To ensure that the counts
are consistent between a histogram search and an identical job search,
disableKeywordMatch in the job search must be false.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Histogram (v3)\n\nCloud Talent Solution allows you to get a histogram representation of the number of\njobs associated to a given search. A histogram search returns a count of all jobs\nthat match a particular query, broken down by the requested [`searchType`](/talent-solution/job-search/v3/docs/reference/rest/v3/SearchType).\nFor example, a histogram search could return the number of jobs per employment\ntype (full-time, part-time, etc) that exist in Mountain View, CA. To define the\ndimensions and parameters of the histogram, follow this guide.\n\nHistograms are generally run in parallel with a search call, using the same\n[`JobQuery`](/talent-solution/job-search/v3/docs/reference/rest/v3/JobQuery) and the same [`requestMetadata`](/talent-solution/job-search/v3/docs/reference/rest/v3/RequestMetadata).\n\nRequest\n-------\n\nThe histogram can be obtained from the underlying `search` API. This is achieved by setting the `histogramFacets` on the `search` API and defining the filters of the request. **Note that the histogram observes all the filters as defined in the search query**. The following example illustrates the mechanism of retrieving a histogram,\n\nRequired fields\n---------------\n\n- `searchTypes` is a list of categories for which to return counts. For example, specify `EMPLOYMENT_TYPE` to return a count of employment types, such as full-time or part-time. See [`SearchType`](/talent-solution/job-search/v3/docs/reference/rest/v3/SearchType) for a detailed list of enums.\n\nOptional fields\n---------------\n\n- `jobQuery` is the job query to perform in this search. See\n [Search Filters](/talent-solution/job-search/v3/docs/search-filters) for more details. In this example, no query is applied.\n\n- `requestMetadata` contains information about the user initiating the search.\n See the\n [`RequestMetadata`](/talent-solution/job-search/v3/docs/search#requestmetadata)\n section of the job search page for more information.\n\n- `enableBroadening` loosens the restrictions on location and job category of\n the search request, in order to return more results. For example, if a\n request specified jobs within a 20 mile radius of a location, setting this\n flag to `true` may return jobs from outside of that radius. The following\n example does not include broadened results.\n\nExamples\n--------\n\nThe following example returns the list of job counts across the `COMPANY_ID`\nand the customAttribute `someFieldName1`: \n\n### Java\n\n\nFor more on installing and creating a Cloud Talent Solution client, see\n[Cloud Talent Solution Client Libraries](/talent-solution/job-search/v3/docs/libraries). \n\n\n /** Histogram search */\n public static void histogramSearch(String companyName) throws IOException, InterruptedException {\n // Make sure to set the requestMetadata the same as the associated search request\n RequestMetadata requestMetadata =\n new RequestMetadata()\n // Make sure to hash your userID\n .setUserId(\"HashedUserId\")\n // Make sure to hash the sessionID\n .setSessionId(\"HashedSessionID\")\n // Domain of the website where the search is conducted\n .setDomain(\"www.google.com\");\n\n HistogramFacets histogramFacets =\n new HistogramFacets()\n .setSimpleHistogramFacets(Arrays.asList(\"COMPANY_ID\"))\n .setCustomAttributeHistogramFacets(\n Arrays.asList(\n new CustomAttributeHistogramRequest()\n .setKey(\"someFieldName1\")\n .setStringValueHistogram(true)));\n\n // conducted.\n SearchJobsRequest searchJobsRequest =\n new SearchJobsRequest()\n .setRequestMetadata(requestMetadata)\n .setSearchMode(\"JOB_SEARCH\")\n .setHistogramFacets(histogramFacets);\n if (companyName != null) {\n searchJobsRequest.setJobQuery(new JobQuery().setCompanyNames(Arrays.asList(companyName)));\n }\n\n SearchJobsResponse searchJobsResponse =\n talentSolutionClient\n .projects()\n .jobs()\n .search(DEFAULT_PROJECT_ID, searchJobsRequest)\n .execute();\n Thread.sleep(1000);\n\n System.out.printf(\"Histogram search results: %s\\n\", searchJobsResponse);\n }\n\n### Python\n\n\nFor more on installing and creating a Cloud Talent Solution client, see\n[Cloud Talent Solution Client Libraries](/talent-solution/job-search/v3/docs/libraries). \n\n def histogram_search(client_service, company_name):\n request_metadata = {\n \"user_id\": \"HashedUserId\",\n \"session_id\": \"HashedSessionId\",\n \"domain\": \"www.google.com\",\n }\n custom_attribute_histogram_facet = {\n \"key\": \"someFieldName1\",\n \"string_value_histogram\": True,\n }\n histogram_facets = {\n \"simple_histogram_facets\": [\"COMPANY_ID\"],\n \"custom_attribute_histogram_facets\": [custom_attribute_histogram_facet],\n }\n request = {\n \"search_mode\": \"JOB_SEARCH\",\n \"request_metadata\": request_metadata,\n \"histogram_facets\": histogram_facets,\n }\n if company_name is not None:\n request.update({\"job_query\": {\"company_names\": [company_name]}})\n response = (\n client_service.projects().jobs().search(parent=parent, body=request).execute()\n )\n print(response)\n\n### Go\n\n\nFor more on installing and creating a Cloud Talent Solution client, see\n[Cloud Talent Solution Client Libraries](/talent-solution/job-search/v3/docs/libraries). \n\n\n // histogramSearch searches for jobs with histogram facets.\n func histogramSearch(w io.Writer, projectID, companyName string) (*talent.SearchJobsResponse, error) {\n \tctx := context.Background()\n\n \tclient, err := google.DefaultClient(ctx, talent.CloudPlatformScope)\n \tif err != nil {\n \t\treturn nil, fmt.Errorf(\"google.DefaultClient: %w\", err)\n \t}\n \t// Create the jobs service client.\n \tservice, err := talent.New(client)\n \tif err != nil {\n \t\treturn nil, fmt.Errorf(\"talent.New: %w\", err)\n \t}\n\n \tparent := \"projects/\" + projectID\n \treq := &talent.SearchJobsRequest{\n \t\t// Make sure to set the RequestMetadata the same as the associated\n \t\t// search request.\n \t\tRequestMetadata: &talent.RequestMetadata{\n \t\t\t// Make sure to hash your userID.\n \t\t\tUserId: \"HashedUsrId\",\n \t\t\t// Make sure to hash the sessionID.\n \t\t\tSessionId: \"HashedSessionId\",\n \t\t\t// Domain of the website where the search is conducted.\n \t\t\tDomain: \"www.googlesample.com\",\n \t\t},\n \t\tHistogramFacets: &talent.HistogramFacets{\n \t\t\tSimpleHistogramFacets: []string{\"COMPANY_ID\"},\n \t\t\tCustomAttributeHistogramFacets: []*talent.CustomAttributeHistogramRequest{\n \t\t\t\t{\n \t\t\t\t\tKey: \"someFieldString\",\n \t\t\t\t\tStringValueHistogram: true,\n \t\t\t\t},\n \t\t\t},\n \t\t},\n \t\t// Set the search mode to a regular search.\n \t\tSearchMode: \"JOB_SEARCH\",\n \t\tRequirePreciseResultSize: true,\n \t}\n \tif companyName != \"\" {\n \t\treq.JobQuery = &talent.JobQuery{\n \t\t\tCompanyNames: []string{companyName},\n \t\t}\n \t}\n\n \tresp, err := service.Projects.Jobs.Search(parent, req).Do()\n \tif err != nil {\n \t\treturn nil, fmt.Errorf(\"failed to search for jobs with Historgram Facets: %w\", err)\n \t}\n\n \tfmt.Fprintln(w, \"Jobs:\")\n \tfor _, j := range resp.MatchingJobs {\n \t\tfmt.Fprintf(w, \"\\t%q\\n\", j.Job.Name)\n \t}\n\n \treturn resp, nil\n }\n\n\u003cbr /\u003e\n\nRelevance thresholding\n----------------------\n\nHistogram requests do not use relevance thresholding. To ensure that the counts\nare consistent between a histogram search and an identical job search,\n`disableKeywordMatch` in the job search must be `false`."]]