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`](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/reference/rest/v3/SearchType.md.txt).
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`](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/reference/rest/v3/JobQuery.md.txt) and the same [`requestMetadata`](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/reference/rest/v3/RequestMetadata.md.txt).

## 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`](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/reference/rest/v3/SearchType.md.txt) for a detailed list of enums.

## Optional fields

- `jobQuery` is the job query to perform in this search. See
  [Search Filters](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/search-filters.md.txt) for more details. In this example, no query is applied.

- `requestMetadata` contains information about the user initiating the search.
  See the
  [`RequestMetadata`](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/search.md.txt#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`:

### Java


For more on installing and creating a Cloud Talent Solution client, see
[Cloud Talent Solution Client Libraries](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/libraries.md.txt).

```java

/** Histogram search */
public static void histogramSearch(String companyName) throws IOException, InterruptedException {
  // Make sure to set the requestMetadata the same as the associated search request
  RequestMetadata requestMetadata =
      new RequestMetadata()
          // 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");

  HistogramFacets histogramFacets =
      new HistogramFacets()
          .setSimpleHistogramFacets(Arrays.asList("COMPANY_ID"))
          .setCustomAttributeHistogramFacets(
              Arrays.asList(
                  new CustomAttributeHistogramRequest()
                      .setKey("someFieldName1")
                      .setStringValueHistogram(true)));

  // conducted.
  SearchJobsRequest searchJobsRequest =
      new SearchJobsRequest()
          .setRequestMetadata(requestMetadata)
          .setSearchMode("JOB_SEARCH")
          .setHistogramFacets(histogramFacets);
  if (companyName != null) {
    searchJobsRequest.setJobQuery(new JobQuery().setCompanyNames(Arrays.asList(companyName)));
  }

  SearchJobsResponse searchJobsResponse =
      talentSolutionClient
          .projects()
          .jobs()
          .search(DEFAULT_PROJECT_ID, searchJobsRequest)
          .execute();
  Thread.sleep(1000);

  System.out.printf("Histogram search results: %s\n", searchJobsResponse);
}
```

### Python


For more on installing and creating a Cloud Talent Solution client, see
[Cloud Talent Solution Client Libraries](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/libraries.md.txt).

```python
def histogram_search(client_service, company_name):
    request_metadata = {
        "user_id": "HashedUserId",
        "session_id": "HashedSessionId",
        "domain": "www.google.com",
    }
    custom_attribute_histogram_facet = {
        "key": "someFieldName1",
        "string_value_histogram": True,
    }
    histogram_facets = {
        "simple_histogram_facets": ["COMPANY_ID"],
        "custom_attribute_histogram_facets": [custom_attribute_histogram_facet],
    }
    request = {
        "search_mode": "JOB_SEARCH",
        "request_metadata": request_metadata,
        "histogram_facets": histogram_facets,
    }
    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()
    )
    print(response)
```

### Go


For more on installing and creating a Cloud Talent Solution client, see
[Cloud Talent Solution Client Libraries](https://docs.cloud.google.com/talent-solution/job-search/v3/docs/libraries.md.txt).

```go

// histogramSearch searches for jobs with histogram facets.
func histogramSearch(w io.Writer, projectID, companyName string) (*talent.SearchJobsResponse, error) {
	ctx := context.Background()

	client, err := google.DefaultClient(ctx, talent.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %w", err)
	}
	// Create the jobs service client.
	service, err := talent.New(client)
	if err != nil {
		return nil, fmt.Errorf("talent.New: %w", err)
	}

	parent := "projects/" + projectID
	req := &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,
	}
	if companyName != "" {
		req.JobQuery = &talent.JobQuery{
			CompanyNames: []string{companyName},
		}
	}

	resp, err := service.Projects.Jobs.Search(parent, req).Do()
	if err != nil {
		return nil, fmt.Errorf("failed to search for jobs with Historgram Facets: %w", err)
	}

	fmt.Fprintln(w, "Jobs:")
	for _, j := range resp.MatchingJobs {
		fmt.Fprintf(w, "\t%q\n", j.Job.Name)
	}

	return resp, nil
}
```

<br />

## 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`.