Method: projects.tenants.search

Searches for profiles within a tenant.

For example, search by raw queries "software engineer in Mountain View" or search by structured filters (location filter, education filter, etc.).

See SearchProfilesRequest for more information.

HTTP request

POST https://jobs.googleapis.com/v4beta1/{parent=projects/*/tenants/*}:search

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The resource name of the tenant to search within.

The format is "projects/{project_id}/tenants/{tenantId}", for example, "projects/api-test-project/tenants/foo".

Request body

The request body contains data with the following structure:

JSON representation
{
  "requestMetadata": {
    object (RequestMetadata)
  },
  "profileQuery": {
    object (ProfileQuery)
  },
  "pageSize": number,
  "pageToken": string,
  "offset": number,
  "disableSpellCheck": boolean,
  "orderBy": string,
  "caseSensitiveSort": boolean,
  "histogramQueries": [
    {
      object (HistogramQuery)
    }
  ],
  "resultSetId": string,
  "strictKeywordsSearch": boolean
}
Fields
requestMetadata

object (RequestMetadata)

Required. The meta information collected about the profile search user. This is used to improve the search quality of the service. These values are provided by users, and must be precise and consistent.

profileQuery

object (ProfileQuery)

Optional. Search query to execute. See ProfileQuery for more details.

pageSize

number

Optional. A limit on the number of profiles returned in the search results. A value above the default value 10 can increase search response time.

The maximum value allowed is 100. Otherwise an error is thrown.

pageToken

string

Optional. The pageToken, similar to offset enables users of the API to paginate through the search results. To retrieve the first page of results, set the pageToken to empty. The search response includes a nextPageToken field that can be used to populate the pageToken field for the next page of results. Using pageToken instead of offset increases the performance of the API, especially compared to larger offset values.

offset

number

Optional. An integer that specifies the current offset (that is, starting result) in search results. This field is only considered if pageToken is unset.

The maximum allowed value is 5000. Otherwise an error is thrown.

For example, 0 means to search from the first profile, and 10 means to search from the 11th profile. This can be used for pagination, for example pageSize = 10 and offset = 10 means to search from the second page.

disableSpellCheck

boolean

Optional. This flag controls the spell-check feature. If false, the service attempts to correct a misspelled query.

For example, "enginee" is corrected to "engineer".

orderBy

string

Optional. The criteria that determines how search results are sorted. Defaults is "relevance desc" if no value is specified.

Supported options are:

caseSensitiveSort

boolean

Optional. When sort by field is based on alphabetical order, sort values case sensitively (based on ASCII) when the value is set to true. Default value is case in-sensitive sort (false).

histogramQueries[]

object (HistogramQuery)

Optional. A list of expressions specifies histogram requests against matching profiles for SearchProfilesRequest.

The expression syntax looks like a function definition with optional parameters.

Function syntax: function_name(histogram_facet[, list of buckets])

Data types:

  • Histogram facet: facet names with format [a-zA-Z][a-zA-Z0-9_]+.
  • String: string like "any string with backslash escape for quote(")."
  • Number: whole number and floating point number like 10, -1 and -0.01.
  • List: list of elements with comma(,) separator surrounded by square brackets. For example, [1, 2, 3] and ["one", "two", "three"].

Built-in constants:

  • MIN (minimum number similar to java Double.MIN_VALUE)
  • MAX (maximum number similar to java Double.MAX_VALUE)

Built-in functions:

  • bucket(start, end[, label]) Bucket build-in function creates a bucket with range of [start, end). Note that the end is exclusive. For example, bucket(1, MAX, "positive number") or bucket(1, 10).

Histogram Facets:

  • admin1: Admin1 is a global placeholder for referring to state, province, or the particular term a country uses to define the geographic structure below the country level. Examples include states codes such as "CA", "IL", "NY", and provinces, such as "BC".
  • locality: Locality is a global placeholder for referring to city, town, or the particular term a country uses to define the geographic structure below the admin1 level. Examples include city names such as "Mountain View" and "New York".
  • extended_locality: Extended locality is concatenated version of admin1 and locality with comma separator. For example, "Mountain View, CA" and "New York, NY".
  • postalCode: Postal code of profile which follows locale code.
  • country: Country code (ISO-3166-1 alpha-2 code) of profile, such as US, JP, GB.
  • jobTitle: Normalized job titles specified in EmploymentHistory.
  • companyName: Normalized company name of profiles to match on.
  • institution: The school name. For example, "MIT", "University of California, Berkeley"
  • degree: Highest education degree in ISCED code. Each value in degree covers a specific level of education, without any expansion to upper nor lower levels of education degree.
  • experience_in_months: experience in months. 0 means 0 month to 1 month (exclusive).
  • applicationDate: The application date specifies application start dates. See ApplicationDateFilter for more details.
  • application_outcome_notes: The application outcome reason specifies the reasons behind the outcome of the job application. See ApplicationOutcomeNotesFilter for more details.
  • application_job_title: The application job title specifies the job applied for in the application. See ApplicationJobFilter for more details.
  • hirable_status: Hirable status specifies the profile's hirable status.
  • string_custom_attribute: String custom attributes. Values can be accessed via square bracket notation like string_custom_attribute["key1"].
  • numeric_custom_attribute: Numeric custom attributes. Values can be accessed via square bracket notation like numeric_custom_attribute["key1"].

Example expressions:

  • count(admin1)
  • count(experience_in_months, [bucket(0, 12, "1 year"), bucket(12, 36, "1-3 years"), bucket(36, MAX, "3+ years")])
  • count(string_custom_attribute["assigned_recruiter"])
  • count(numeric_custom_attribute["favorite_number"], [bucket(MIN, 0, "negative"), bucket(0, MAX, "non-negative")])

resultSetId

string

Optional. An id that uniquely identifies the result set of a tenants.search call. The id should be retrieved from the SearchProfilesResponse message returned from a previous invocation of tenants.search.

A result set is an ordered list of search results.

If this field is not set, a new result set is computed based on the profileQuery. A new resultSetId is returned as a handle to access this result set.

If this field is set, the service will ignore the resource and profileQuery values, and simply retrieve a page of results from the corresponding result set. In this case, one and only one of pageToken or offset must be set.

A typical use case is to invoke SearchProfilesRequest without this field, then use the resulting resultSetId in SearchProfilesResponse to page through the results.

Response body

If successful, the response body contains data with the following structure:

Response of tenants.search method.

JSON representation
{
  "estimatedTotalSize": string,
  "spellCorrection": {
    object (SpellingCorrection)
  },
  "metadata": {
    object (ResponseMetadata)
  },
  "nextPageToken": string,
  "histogramQueryResults": [
    {
      object (HistogramQueryResult)
    }
  ],
  "summarizedProfiles": [
    {
      object (SummarizedProfile)
    }
  ],
  "resultSetId": string
}
Fields
estimatedTotalSize

string (int64 format)

An estimation of the number of profiles that match the specified query.

This number isn't guaranteed to be accurate.

spellCorrection

object (SpellingCorrection)

The spell checking result, and correction.

metadata

object (ResponseMetadata)

Additional information for the API invocation, such as the request tracking id.

nextPageToken

string

A token to retrieve the next page of results. This is empty if there are no more results.

histogramQueryResults[]

object (HistogramQueryResult)

The histogram results that match with specified SearchProfilesRequest.histogram_queries.

summarizedProfiles[]

object (SummarizedProfile)

The profile entities that match the specified SearchProfilesRequest.

resultSetId

string

An id that uniquely identifies the result set of a tenants.search call for consistent results.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/jobs
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

ProfileQuery

Filters to apply when performing the search query.

JSON representation
{
  "query": string,
  "locationFilters": [
    {
      object (LocationFilter)
    }
  ],
  "jobTitleFilters": [
    {
      object (JobTitleFilter)
    }
  ],
  "employerFilters": [
    {
      object (EmployerFilter)
    }
  ],
  "educationFilters": [
    {
      object (EducationFilter)
    }
  ],
  "skillFilters": [
    {
      object (SkillFilter)
    }
  ],
  "workExperienceFilter": [
    {
      object (WorkExperienceFilter)
    }
  ],
  "timeFilters": [
    {
      object (TimeFilter)
    }
  ],
  "hirableFilter": boolean,
  "applicationDateFilters": [
    {
      object (ApplicationDateFilter)
    }
  ],
  "applicationOutcomeNotesFilters": [
    {
      object (ApplicationOutcomeNotesFilter)
    }
  ],
  "applicationJobFilters": [
    {
      object (ApplicationJobFilter)
    }
  ],
  "customAttributeFilter": string,
  "candidateAvailabilityFilter": {
    object (CandidateAvailabilityFilter)
  },
  "personNameFilters": [
    {
      object (PersonNameFilter)
    }
  ]
}
Fields
query

string

Optional. Keywords to match any text fields of profiles.

For example, "software engineer in Palo Alto".

locationFilters[]

object (LocationFilter)

Optional. The location filter specifies geo-regions containing the profiles to search against.

If a location filter isn't specified, profiles fitting the other search criteria are retrieved regardless of where they're located.

If LocationFilter.negated is specified, the result doesn't contain profiles from that location.

For example, search for profiles with addresses in "New York City".

jobTitleFilters[]

object (JobTitleFilter)

Optional. Job title filter specifies job titles of profiles to match on.

If a job title isn't specified, profiles with any titles are retrieved.

If multiple values are specified, profiles are retrieved with any of the specified job titles.

If JobTitleFilter.negated is specified, the result won't contain profiles with the job titles.

For example, search for profiles with a job title "Product Manager".

employerFilters[]

object (EmployerFilter)

Optional. Employer filter specifies employers of profiles to match on.

If an employer filter isn't specified, profiles with any employers are retrieved.

If multiple employer filters are specified, profiles with any matching employers are retrieved.

If EmployerFilter.negated is specified, the result won't contain profiles that match the employers.

For example, search for profiles that have working experience at "Google LLC".

educationFilters[]

object (EducationFilter)

Optional. Education filter specifies education of profiles to match on.

If an education filter isn't specified, profiles with any education are retrieved.

If multiple education filters are specified, profiles that match any education filters are retrieved.

If EducationFilter.negated is specified, the result won't contain profiles that match the educations.

For example, search for profiles with a master degree.

skillFilters[]

object (SkillFilter)

Optional. Skill filter specifies skill of profiles to match on.

If a skill filter isn't specified, profiles with any skills are retrieved.

If multiple skill filters are specified, profiles that match any skill filters are retrieved.

If SkillFilter.negated is specified, the result won't contain profiles that match the skills.

For example, search for profiles that have "Java" and "Python" in skill list.

workExperienceFilter[]

object (WorkExperienceFilter)

Optional. Work experience filter specifies the total working experience of profiles to match on.

If a work experience filter isn't specified, profiles with any professional experience are retrieved.

If multiple work experience filters are specified, profiles that match any work experience filters are retrieved.

For example, search for profiles with 10 years of work experience.

timeFilters[]

object (TimeFilter)

Optional. Time filter specifies the create/update timestamp of the profiles to match on.

For example, search for profiles created since "2018-1-1".

hirableFilter

boolean

Optional. The hirable filter specifies the profile's hirable status to match on.

applicationDateFilters[]

object (ApplicationDateFilter)

Optional. The application date filters specify application date ranges to match on.

applicationOutcomeNotesFilters[]

object (ApplicationOutcomeNotesFilter)

Optional. The application outcome notes filters specify the notes for the outcome of the job application.

applicationJobFilters[]

object (ApplicationJobFilter)

Optional. The application job filters specify the job applied for in the application.

customAttributeFilter

string

Optional. This filter specifies a structured syntax to match against the Profile.custom_attributes that are marked as filterable.

The syntax for this expression is a subset of Google SQL syntax.

String custom attributes: supported operators are =, != where the left of the operator is a custom field key and the right of the operator is a string (surrounded by quotes) value.

Numeric custom attributes: Supported operators are '>', '<' or '=' operators where the left of the operator is a custom field key and the right of the operator is a numeric value.

Supported functions are LOWER() to perform case insensitive match and EMPTY() to filter on the existence of a key.

Boolean expressions (AND/OR/NOT) are supported up to 3 levels of nesting (for example "((A AND B AND C) OR NOT D) AND E"), and there can be a maximum of 50 comparisons/functions in the expression. The expression must be < 2000 characters in length.

Sample Query: (key1 = "TEST" OR LOWER(key1)="test" OR NOT EMPTY(key1))

candidateAvailabilityFilter

object (CandidateAvailabilityFilter)

Optional. The candidate availability filter which filters based on availability signals.

Signal 1: Number of days since most recent job application. See Availability.JobApplicationAvailabilitySignal for the details of this signal.

Signal 2: Number of days since last profile update. See Availability.ProfileUpdateAvailabilitySignal for the details of this signal.

The candidate availability filter helps a recruiter understand if a specific candidate is likely to be actively seeking new job opportunities based on an aggregated set of signals. Specifically, the intent is NOT to indicate the candidate's potential qualification / interest / close ability for a specific job.

personNameFilters[]

object (PersonNameFilter)

Optional. Person name filter specifies person name of profiles to match on.

If multiple person name filters are specified, profiles that match any person name filters are retrieved.

For example, search for profiles of candidates with name "John Smith".

JobTitleFilter

Input only.

Job title of the search.

JSON representation
{
  "jobTitle": string,
  "negated": boolean
}
Fields
jobTitle

string

Required. The job title, for example, "Software engineer", or "Product manager".

negated

boolean

Optional. Whether to apply negation to the filter so profiles matching the filter are excluded.

EmployerFilter

Input only.

Employer filter of the search.

JSON representation
{
  "employer": string,
  "mode": enum (EmployerFilterMode),
  "negated": boolean
}
Fields
employer

string

Required. The name of the employer, for example "Google", "Alphabet".

mode

enum (EmployerFilterMode)

Optional. Define set of EmploymentRecords to search against.

Defaults to EmployerFilterMode.ALL_EMPLOYMENT_RECORDS.

negated

boolean

Optional. Whether to apply negation to the filter so profiles matching the filter is excluded.

EmployerFilterMode

Enum indicating which set of Profile.employment_records to search against.

Enums
EMPLOYER_FILTER_MODE_UNSPECIFIED Default value.
ALL_EMPLOYMENT_RECORDS Apply to all employers in Profile.employment_records.
CURRENT_EMPLOYMENT_RECORDS_ONLY Apply only to current employer in Profile.employment_records.
PAST_EMPLOYMENT_RECORDS_ONLY Apply only to past (not current) employers in Profile.employment_records.

EducationFilter

Input only.

Education filter of the search.

JSON representation
{
  "school": string,
  "fieldOfStudy": string,
  "degreeType": enum (DegreeType),
  "negated": boolean
}
Fields
school

string

Optional. The school name. For example "MIT", "University of California, Berkeley".

fieldOfStudy

string

Optional. The field of study. This is to search against value provided in Degree.fields_of_study. For example "Computer Science", "Mathematics".

degreeType

enum (DegreeType)

Optional. Education degree in ISCED code. Each value in degree covers a specific level of education, without any expansion to upper nor lower levels of education degree.

negated

boolean

Optional. Whether to apply negation to the filter so profiles matching the filter is excluded.

SkillFilter

Input only.

Skill filter of the search.

JSON representation
{
  "skill": string,
  "negated": boolean
}
Fields
skill

string

Required. The skill name. For example, "java", "j2ee", and so on.

negated

boolean

Optional. Whether to apply negation to the filter so profiles matching the filter are excluded.

WorkExperienceFilter

Input only.

Work experience filter.

This filter is used to search for profiles with working experience length between minExperience and maxExperience.

JSON representation
{
  "minExperience": string,
  "maxExperience": string
}
Fields
minExperience

string (Duration format)

Optional. The minimum duration of the work experience (inclusive).

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

maxExperience

string (Duration format)

Optional. The maximum duration of the work experience (exclusive).

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

TimeFilter

Input only.

Filter on create timestamp or update timestamp of profiles.

JSON representation
{
  "startTime": string,
  "endTime": string,
  "timeField": enum (TimeField)
}
Fields
startTime

string (Timestamp format)

Optional. Start timestamp, matching profiles with the start time. If this field missing, The API matches profiles with create / update timestamp before the end timestamp.

endTime

string (Timestamp format)

Optional. End timestamp, matching profiles with the end time. If this field missing, The API matches profiles with create / update timestamp after the start timestamp.

timeField

enum (TimeField)

Optional. Specifies which time field to filter profiles.

Defaults to TimeField.CREATE_TIME.

TimeField

Time fields can be used in TimeFilter.

Enums
TIME_FIELD_UNSPECIFIED Default value.
CREATE_TIME Earliest profile create time.
UPDATE_TIME Latest profile update time.

ApplicationDateFilter

Input only.

Application Date Range Filter.

The API matches profiles with Application.application_date between start date and end date (both boundaries are inclusive). The filter is ignored if both startDate and endDate are missing.

JSON representation
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Fields
startDate

object (Date)

Optional. Start date. If it's missing, The API matches profiles with application date not after the end date.

endDate

object (Date)

Optional. End date. If it's missing, The API matches profiles with application date not before the start date.

ApplicationOutcomeNotesFilter

Input only.

Outcome Notes Filter.

JSON representation
{
  "outcomeNotes": string,
  "negated": boolean
}
Fields
outcomeNotes

string

Required. User entered or selected outcome reason. The API does an exact match on the Application.outcome_notes in profiles.

negated

boolean

Optional. If true, The API excludes all candidates with any Application.outcome_notes matching the outcome reason specified in the filter.

ApplicationJobFilter

Input only.

Filter on the job information of Application.

JSON representation
{
  "jobRequisitionId": string,
  "jobTitle": string,
  "negated": boolean
}
Fields
jobRequisitionId

string

Optional. The job requisition id in the application. The API does an exact match on the Job.requisition_id of Application.job in profiles.

jobTitle

string

Optional. The job title in the application. The API does an exact match on the Job.title of Application.job in profiles.

negated

boolean

Optional. If true, the API excludes all profiles with any Application.job matching the filters.

CandidateAvailabilityFilter

Input only

Filter on availability signals.

JSON representation
{
  "negated": boolean
}
Fields
negated

boolean

Optional. It is false by default. If true, API excludes all the potential available profiles.

PersonNameFilter

Input only.

Filter on person name.

JSON representation
{
  "personName": string
}
Fields
personName

string

Required. The person name. For example, "John Smith".

Can be any combination of [PersonName.structured_name.given_name][], [PersonName.structured_name.middle_initial][], [PersonName.structured_name.family_name][], and PersonName.formatted_name.

SummarizedProfile

Output only.

Profile entry with metadata inside SearchProfilesResponse.

JSON representation
{
  "profiles": [
    {
      object (Profile)
    }
  ],
  "summary": {
    object (Profile)
  }
}
Fields
profiles[]

object (Profile)

A list of profiles that are linked by Profile.group_id.

summary

object (Profile)

A profile summary shows the profile summary and how the profile matches the search query.

In profile summary, the profiles with the same Profile.group_id are merged together. Among profiles, same education/employment records may be slightly different but they are merged into one with best efforts.

For example, in one profile the school name is "UC Berkeley" and the field study is "Computer Science" and in another one the school name is "University of California at Berkeley" and the field study is "CS". The API merges these two inputs into one and selects one value for each field. For example, the school name in summary is set to "University of California at Berkeley" and the field of study is set to "Computer Science".

Try it!

Var denne siden nyttig? Si fra hva du synes:

Send tilbakemelding om ...

Job search documentation
Trenger du hjelp? Gå til brukerstøttesiden vår.