A Job resource represents a single job posting (also referred to as a "job listing" or "job requisition"). A job belongs to a Company resource that represents the hiring entity responsible for the job.
You can access a job using the LIST and GET methods and manipulate it using CREATE, UPDATE, and DELETE methods. It can take several minutes for the Cloud Talent Solution index to reflect changes.
Jobs are contained within the scope of a service account. Only search requests authenticated using the credentials of a particular service account can be used to access the content of these jobs.
For easy troubleshooting and triaging, synchronize the Cloud Talent Solution job index
with your own job index, and maintain a relationship between the name
generated by Cloud Talent Solution and the unique job identifier in your system. As
jobs change or are introduced into your system, the appropriate CRUD call should
be sent to CTS in real time to ensure that these changes are
reflected immediately. The CTS index must be added to the
existing job ingestion pipeline.
Create a job
You can create a Job using the code sample below. See Quickstart: Create companies and jobs for more details. Video tutorials and interactive codelabs are also available.
Go
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Required fields
The following fields are required during Job creation and update:
companyName
: The resource name of the company that owns the job, such ascompanyName=\"projects/{ProjectId}/companies/{CompanyId}\"
.requisitionId
: The requisition ID, also referred to as the posting ID, is a value that you assign to identify a job. You can use this field for client identification and requisition tracking. The maximum number of allowed characters is 225.The uniqueness of a job posting is determined using a combination of the
requisitionID
, thecompanyName
, and location. If a job is created with a specific key of these attributes, this key is stored in the Cloud Talent Solution index and no other jobs with these same fields can be created until the job is deleted.title
: The job title, for example "Software Engineer." The maximum number of allowed characters is 500.To fix the problem of missed search results due to non-standard job titles, Cloud Talent Solution leverages all job fields to understand the context of the job and internally store a "clean" job title. When a search request is sent to the service, the query of the search is also cleaned, and the ontologies are used to map the cleaned query to relevant clean jobs.
description
: The description of the job, which typically includes a multi-paragraph description of the company and related information. Separate fields are provided on the Job object for responsibilities, qualifications, and other job characteristics. Use of these separate fields is recommended.This field accepts and sanitizes HTML input, and accepts bold, italic, ordered list, and unordered list markup tags. The maximum number of allowed characters is 100,000.
One of the following:
applicationInfo.uris
: The URL(s) of the application page(s).applicationInfo.emails
: Email address(es) to which resumes or applications should be sent.applicationInfo.instruction
: Application instructions, such as "Mail your application to ...". This field accepts and sanitizes HTML input, and accepts bold, italic, ordered list, and unordered list markup tags. The maximum number of allowed characters is 3,000.
Commonly used fields
postingExpireTime
: The time, based on the timestamp, when the job posting expires. After this time occurs, the job is marked as expired and won't appear in search results. This date should be before 2100/12/31 in UTC timezone. Invalid dates (such as past dates) are ignored. The default date when the job expires is 30 days after the job creation time in UTC time zone.The content of expired jobs can still be retrieved up to 90 days after the job has expired by using the GET operator. After this 90 day deadline, the job won't be returned through a GET operation.
addresses
: Job location(s). Providing the full street address(es) of the hiring location is recommended to enable better Job Search results, including searches by commute time. The maximum number of allowed characters is 500. More information aboutaddresses
is available in the Best practices section below.promotionValue
: A value greater than 0 defines this job as a "featured job", which is returned only in searches of typeFEATURED_JOBS
. Higher values are returned higher in the featured search results. See Featured Jobs for more information.
Using custom job fields
Cloud Talent Solution includes several job fields that are built in to its
API schemas. However, you may need additional fields that aren't present in the
out-of-the-box options. While we recommended that you use the out-of-the box
fields wherever possible, Cloud Talent Solution also provides some customAttributes
fields for a job. These can be filterable or non-filterable. Refer to
the customAttributes
documentation for more information.
customAttributes
: This field stores up to 100 custom attributes used to store custom data about the job. These fields can be filtered against using a search request specifying thejobQuery
field. Additionally, any of these fields can be set in thekeywordSearchableJobCustomAttributes
attribute of thecompany
, so a search term that has an exact match in any of the fields inkeywordSearchableJobCustomAttributes
returns any Job that includes the match.
The following code example shows how to create a job with a customAttribute
:
Go
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Retrieve a job
Go
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
List jobs
Go
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Delete a job
Go
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Go API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Java API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Node.js API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for CTS, see CTS client libraries. For more information, see the CTS Python API reference documentation.
To authenticate to CTS, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Best practices
Location fields
Whenever possible, we recommend providing the street address of a job in the
addresses
field. This helps with location detection and relevance. When a
street-level address isn't available, enter as much information as possible.
Addresses are supported up to the country level. Region designations (such as
"Pacific Northwest") are not supported.
Cloud Talent Solution uses the data in the addresses
field to populate
the (output only) derivedInfo.locations
field. When a full address isn't provided,
the service uses other signals, such as the company name, to determine if a
more complete address can be inferred for the job posting.
For example, if the location of a software position is specified as Mountain View
,
and the company to which the job is associated is Google
, the service
looks up the company
object to see if a better street address is
provided in the headquartersAddress
field and whether that street address is in the same city
as the job posting. If so, the service understands that the job is "likely"
located at that street address and fills in the derivedInfo.locations
field appropriately.
If company address data isn't available, the service uses a combination of
proprietary knowledge and job/company information to inform the derivedInfo.locations
field.
Because the derivedInfo.locations
value is a best-guess effort, you may wish to use
the derivedInfo.locations
data, or the addresses
field,
when displaying the job address.
A job posting may have no more than 50 locations associated with it. If a job
has more locations you can split the job into multiple jobs, each with a unique
requisitionId (for example, 'ReqA' , 'ReqA-1', 'ReqA-2', and so on). Having multiple
jobs with the same requisitionId
, , companyName
and languageCode
is not
allowed. If the original requisitionId
must be preserved, a CustomAttribute
should be used for storage. It's recommended you group the locations closest to
each other in the same job for a better search experience.
Supported addresses
Any address that is recognized by the Google Maps Geocoding API (in the
formattedAddress
field) is accepted by Cloud Talent Solution. The service
returns a 400 error if you attempt to create a Job or execute a search
using an unrecognized address.
If a business address is listed incorrectly in the Google Maps Geocoding API, file a bug to have it corrected. Corrections may take up to 5 days to take effect.
Address autocompletion
Cloud Talent Solution does not provide autocomplete suggestions for locations. Use the Google Maps Places API, or other similar location services, to populate autocomplete suggestions.
Statewide, nationwide, and telecommute jobs
Jobs can be specified as statewide, nationwide, or telecommute by using the
postingRegion
field.
ADMINISTRATIVE_AREA
andNATION
Jobs are returned for any search with a specified location inside the state/country of the job posting. For example, if anADMINISTRATIVE_AREA
job has a location of "WA, USA" it is returned for searches withLocationFilter
specifing "Seattle".TELECOMMUTE
Jobs are returned in any location-related search, but are treated as less relevant. They can be targeted in a search by setting thetelecommutePreference
flag toTELECOMMUTE_ALLOWED
in the search'sLocationFilter
.