0
# Google Cloud Talent API
1

2
A comprehensive Python client library for Google Cloud Talent Solution API, enabling developers to create, read, update, and delete job postings, as well as search jobs based on keywords and filters. It offers both synchronous and asynchronous clients for various services including CompanyService, JobService, EventService, TenantService, and Completion service, with support for advanced job matching, filtering, and analytics capabilities.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-talent
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-talent`
9

10
## Core Imports
11

12
```python
13
from google.cloud import talent
14
```
15

16
For specific API versions:
17

18
```python
19
from google.cloud import talent_v4
20
from google.cloud import talent_v4beta1
21
```
22

23
Common service client imports:
24

25
```python
26
from google.cloud.talent import (
27
    JobServiceClient,
28
    CompanyServiceClient,
29
    TenantServiceClient,
30
    EventServiceClient,
31
    CompletionClient
32
)
33
```
34

35
For async clients:
36

37
```python
38
from google.cloud.talent import (
39
    JobServiceAsyncClient,
40
    CompanyServiceAsyncClient,
41
    TenantServiceAsyncClient,
42
    EventServiceAsyncClient,
43
    CompletionAsyncClient
44
)
45
```
46

47
For request/response types:
48

49
```python
50
from google.cloud.talent import (
51
    # Job service types
52
    SearchJobsRequest, SearchJobsResponse, ListJobsResponse,
53
    CreateJobRequest, UpdateJobRequest, DeleteJobRequest, GetJobRequest,
54
    BatchCreateJobsRequest, BatchUpdateJobsRequest, BatchDeleteJobsRequest,
55
    # Company service types  
56
    ListCompaniesResponse, CreateCompanyRequest, UpdateCompanyRequest,
57
    # Tenant service types
58
    ListTenantsResponse, CreateTenantRequest, UpdateTenantRequest,
59
    # Event service types
60
    CreateClientEventRequest,
61
    # Completion service types
62
    CompleteQueryRequest, CompleteQueryResponse
63
)
64
```
65

66
For working with field masks and protobuf types:
67

68
```python
69
from google.protobuf import field_mask_pb2
70
from google.protobuf import duration_pb2
71
from google.protobuf.timestamp_pb2 import Timestamp
72
from google.type import money_pb2, latlng_pb2
73
```
74

75
## Basic Usage
76

77
```python
78
from google.cloud.talent import JobServiceClient, Job, Company
79

80
# Initialize the client
81
client = JobServiceClient()
82

83
# Create a tenant (required for multi-tenancy)
84
from google.cloud.talent import TenantServiceClient, Tenant
85

86
tenant_client = TenantServiceClient()
87
tenant = Tenant(external_id="my-tenant-123")
88
tenant_response = tenant_client.create_tenant(
89
    parent="projects/my-project-id",
90
    tenant=tenant
91
)
92

93
# Create a company
94
from google.cloud.talent import CompanyServiceClient
95

96
company_client = CompanyServiceClient()
97
company = Company(
98
    display_name="Example Corp",
99
    external_id="example-corp-123"
100
)
101
company_response = company_client.create_company(
102
    parent=tenant_response.name,
103
    company=company
104
)
105

106
# Create a job posting
107
job = Job(
108
    company=company_response.name,
109
    requisition_id="req-001",
110
    title="Software Engineer",
111
    description="Join our engineering team to build innovative solutions.",
112
    addresses=["1600 Amphitheatre Parkway, Mountain View, CA"]
113
)
114

115
job_response = client.create_job(
116
    parent=tenant_response.name,
117
    job=job
118
)
119

120
# Search for jobs
121
from google.cloud.talent import SearchJobsRequest, JobQuery
122

123
search_request = SearchJobsRequest(
124
    parent=tenant_response.name,
125
    job_query=JobQuery(
126
        query="software engineer",
127
        location_filters=[{"address": "San Francisco, CA"}]
128
    )
129
)
130

131
search_response = client.search_jobs(search_request)
132
for matching_job in search_response.matching_jobs:
133
    print(f"Job: {matching_job.job.title}")
134
```
135

136
## Architecture
137

138
The Google Cloud Talent API is structured around five core service clients, each managing specific aspects of talent management:
139

140
- **TenantService**: Multi-tenant data isolation and management
141
- **CompanyService**: Company entity management and profiles
142
- **JobService**: Job posting lifecycle, search, and batch operations
143
- **EventService**: User interaction tracking and analytics
144
- **CompletionService**: Query autocompletion and suggestions
145

146
The API supports both stable (v4) and beta (v4beta1) versions, with comprehensive type definitions for request/response objects, enums for standardized values, and advanced filtering capabilities including geographic search, compensation ranges, and commute time calculations.
147

148
## Capabilities
149

150
### Job Management
151

152
Complete job posting lifecycle management including creation, updates, deletion, listing, and advanced search with filtering, ranking, and analytics. Supports both individual operations and batch processing for efficient bulk operations.
153

154
```python { .api }
155
class JobServiceClient:
156
    def create_job(self, parent: str, job: Job) -> Job: ...
157
    def get_job(self, name: str) -> Job: ...
158
    def update_job(self, job: Job, update_mask: FieldMask = None) -> Job: ...
159
    def delete_job(self, name: str) -> None: ...
160
    def list_jobs(self, parent: str, filter: str = None, page_size: int = None, 
161
                  page_token: str = None, job_view: JobView = None) -> ListJobsResponse: ...
162
    def search_jobs(self, request: SearchJobsRequest) -> SearchJobsResponse: ...
163
    def search_jobs_for_alert(self, request: SearchJobsRequest) -> SearchJobsResponse: ...
164
    def batch_create_jobs(self, parent: str, jobs: List[Job]) -> Operation: ...
165
    def batch_update_jobs(self, parent: str, jobs: List[Job]) -> Operation: ...
166
    def batch_delete_jobs(self, parent: str, names: List[str]) -> Operation: ...
167
```
168

169
[Job Management](./job-management.md)
170

171
### Company Management
172

173
Company entity management for organizations that post jobs, including company profiles, metadata, and hierarchical organization management with support for multi-company scenarios.
174

175
```python { .api }
176
class CompanyServiceClient:
177
    def create_company(self, parent: str, company: Company) -> Company: ...
178
    def get_company(self, name: str) -> Company: ...
179
    def update_company(self, company: Company, update_mask: FieldMask = None) -> Company: ...
180
    def delete_company(self, name: str) -> None: ...
181
    def list_companies(self, parent: str, page_size: int = None, 
182
                      page_token: str = None) -> ListCompaniesResponse: ...
183
```
184

185
[Company Management](./company-management.md)
186

187
### Tenant Management
188

189
Multi-tenant data isolation and management for organizations requiring separate data namespaces, enabling secure multi-customer deployments and data segregation.
190

191
```python { .api }
192
class TenantServiceClient:
193
    def create_tenant(self, parent: str, tenant: Tenant) -> Tenant: ...
194
    def get_tenant(self, name: str) -> Tenant: ...
195
    def update_tenant(self, tenant: Tenant, update_mask: FieldMask = None) -> Tenant: ...
196
    def delete_tenant(self, name: str) -> None: ...
197
    def list_tenants(self, parent: str, page_size: int = None, 
198
                    page_token: str = None) -> ListTenantsResponse: ...
199
```
200

201
[Tenant Management](./tenant-management.md)
202

203
### Search and Filtering
204

205
Advanced job search capabilities with text queries, geographic filtering, compensation ranges, commute time calculations, and faceted search with histogram analytics for building sophisticated job search experiences.
206

207
```python { .api }
208
class JobQuery:
209
    query: str = None
210
    companies: List[str] = None
211
    location_filters: List[LocationFilter] = None
212
    job_categories: List[JobCategory] = None
213
    employment_types: List[EmploymentType] = None
214
    compensation_filter: CompensationFilter = None
215
    commute_filter: CommuteFilter = None
216
    custom_attribute_filter: str = None
217
    publish_time_range: TimestampRange = None
218

219
class LocationFilter:
220
    address: str = None
221
    region_code: str = None
222
    lat_lng: LatLng = None
223
    distance_in_miles: float = None
224
    telecommute_preference: TelecommutePreference = None
225

226
class CompensationFilter:
227
    type_: FilterType = None
228
    units: List[CompensationUnit] = None
229
    range_: CompensationRange = None
230
```
231

232
[Search and Filtering](./search-filtering.md)
233

234
### Event Tracking and Analytics
235

236
User interaction event tracking for improving search quality and providing analytics insights, including job views, applications, and other user behaviors with support for custom event metadata.
237

238
```python { .api }
239
class EventServiceClient:
240
    def create_client_event(self, parent: str, client_event: ClientEvent) -> ClientEvent: ...
241

242
class ClientEvent:
243
    request_id: str = None
244
    event_id: str = None
245
    create_time: Timestamp = None
246
    job_event: JobEvent = None
247
    event_notes: str = None
248
```
249

250
[Event Tracking](./event-tracking.md)
251

252
### Query Autocompletion
253

254
Query autocompletion and suggestion functionality for building intelligent search interfaces with support for job titles, companies, and location-based suggestions.
255

256
```python { .api }
257
class CompletionClient:
258
    def complete_query(self, tenant: str, query: str, page_size: int = None,
259
                      language_codes: List[str] = None, company: str = None,
260
                      scope: CompletionScope = None, type_: CompletionType = None) -> CompleteQueryResponse: ...
261
```
262

263
[Query Autocompletion](./query-autocompletion.md)
264

265
## Core Data Types
266

267
### Job Entity
268

269
```python { .api }
270
class Job:
271
    name: str = None  # Resource name (auto-generated)
272
    company: str = None  # Company resource name (required)
273
    requisition_id: str = None  # Client-defined job identifier (required)
274
    title: str = None  # Job title (required, max 500 chars)
275
    description: str = None  # Job description (required, max 100k chars, HTML supported)
276
    addresses: List[str] = None  # Job location addresses (max 50)
277
    employment_types: List[EmploymentType] = None  # Employment types
278
    job_level: JobLevel = None  # Experience level required
279
    job_categories: List[JobCategory] = None  # Derived job categories
280
    compensation_info: CompensationInfo = None  # Salary/compensation details
281
    job_benefits: List[JobBenefit] = None  # Benefits offered
282
    qualifications: str = None  # Required qualifications (max 10k chars, HTML)
283
    responsibilities: str = None  # Job responsibilities (max 10k chars, HTML)
284
    custom_attributes: Dict[str, CustomAttribute] = None  # Custom job attributes
285
    posting_expire_time: Timestamp = None  # Job expiration date
286
    visibility: Visibility = None  # Job visibility settings
287
```
288

289
### Company Entity
290

291
```python { .api }
292
class Company:
293
    name: str = None  # Resource name (auto-generated)
294
    display_name: str = None  # Company name (required)
295
    external_id: str = None  # Client-defined company identifier (required)
296
    size: CompanySize = None  # Company size category
297
    headquarters_address: str = None  # Main office address
298
    website_uri: str = None  # Company website URL
299
    career_site_uri: str = None  # Careers page URL
300
    image_uri: str = None  # Company logo URL
301
    eeo_text: str = None  # Equal employment opportunity statement
302
```
303

304
### Tenant Entity
305

306
```python { .api }
307
class Tenant:
308
    name: str = None  # Resource name (auto-generated)
309
    external_id: str = None  # Client-defined tenant identifier (required)
310
```
311

312
### Compensation Types
313

314
```python { .api }
315
class CompensationInfo:
316
    entries: List[CompensationEntry] = None  # Individual compensation components
317
    annualized_base_compensation_range: CompensationRange = None  # Base salary range
318
    annualized_total_compensation_range: CompensationRange = None  # Total compensation range
319

320
class CompensationRange:
321
    max_compensation: Money = None  # Maximum compensation
322
    min_compensation: Money = None  # Minimum compensation
323

324
class Money:
325
    currency_code: str = None  # ISO 4217 currency code (e.g., "USD")
326
    units: int = None  # Integer amount
327
    nanos: int = None  # Fractional amount (nano units)
328

329
class CompensationUnit(Enum):
330
    HOURLY = 1
331
    DAILY = 2
332
    WEEKLY = 3
333
    MONTHLY = 4
334
    YEARLY = 5
335
    ONE_TIME = 6
336
```
337

338
### Location and Geographic Types
339

340
```python { .api }
341
class Location:
342
    location_type: LocationType = None  # COUNTRY, ADMINISTRATIVE_AREA, LOCALITY, etc.
343
    postal_address: PostalAddress = None  # Structured postal address
344
    lat_lng: LatLng = None  # Latitude/longitude coordinates
345
    radius_miles: float = None  # Location radius
346

347
class LatLng:
348
    latitude: float = None  # Latitude in degrees
349
    longitude: float = None  # Longitude in degrees
350

351
class Duration:
352
    seconds: int = None  # Duration in seconds
353
    nanos: int = None  # Fractional seconds in nanoseconds
354
```
355

356
### Utility Types
357

358
```python { .api }
359
class CustomAttribute:
360
    string_values: List[str] = None  # String attribute values
361
    long_values: List[int] = None  # Integer attribute values
362
    filterable: bool = None  # Whether attribute can be used in filters
363

364
class TimestampRange:
365
    start_time: Timestamp = None  # Range start time
366
    end_time: Timestamp = None  # Range end time
367

368
class FieldMask:
369
    paths: List[str] = None  # Field paths to update (e.g., ["title", "description"])
370
```
371

372
## Key Enums and Constants
373

374
### Employment and Job Classification
375

376
```python { .api }
377
class EmploymentType(Enum):
378
    FULL_TIME = 1
379
    PART_TIME = 2
380
    CONTRACTOR = 3
381
    CONTRACT_TO_HIRE = 4
382
    TEMPORARY = 5
383
    INTERN = 6
384
    VOLUNTEER = 7
385
    PER_DIEM = 8
386
    FLY_IN_FLY_OUT = 9
387

388
class JobLevel(Enum):
389
    ENTRY_LEVEL = 1
390
    EXPERIENCED = 2
391
    MANAGER = 3
392
    DIRECTOR = 4
393
    EXECUTIVE = 5
394

395
class JobCategory(Enum):
396
    COMPUTER_AND_IT = 1
397
    HEALTHCARE = 2
398
    FINANCE = 3
399
    EDUCATION = 4
400
    # ... 30+ additional categories
401

402
class CompanySize(Enum):
403
    MINI = 1  # <50 employees
404
    SMALL = 2  # 50-99 employees
405
    SMEDIUM = 3  # 100-499 employees
406
    MEDIUM = 4  # 500-999 employees
407
    BIG = 5  # 1k-5k employees
408
    BIGGER = 6  # 5k-10k employees
409
    GIANT = 7  # 10k+ employees
410

411
class JobView(Enum):
412
    JOB_VIEW_UNSPECIFIED = 0  # Default value
413
    JOB_VIEW_ID_ONLY = 1  # ID, requisition_id, language_code only
414
    JOB_VIEW_MINIMAL = 2  # Basic fields: name, title, company, locations
415
    JOB_VIEW_SMALL = 3  # Small view with description and visibility
416
    JOB_VIEW_FULL = 4  # All available attributes
417
```
418

419
## Resource Naming Patterns
420

421
- **Projects**: `projects/{project_id}`
422
- **Tenants**: `projects/{project_id}/tenants/{tenant_id}`
423
- **Companies**: `projects/{project_id}/tenants/{tenant_id}/companies/{company_id}`
424
- **Jobs**: `projects/{project_id}/tenants/{tenant_id}/jobs/{job_id}`
425

426
## Method Calling Patterns
427

428
The Google Cloud Talent API client supports two calling patterns for most methods:
429

430
**Individual Parameters (Recommended for simple cases):**
431
```python
432
job = client.create_job(parent=tenant_name, job=job_object)
433
```
434

435
**Request Objects (Recommended for complex cases):**
436
```python
437
from google.cloud.talent import CreateJobRequest
438

439
request = CreateJobRequest(parent=tenant_name, job=job_object)
440
job = client.create_job(request=request)
441
```
442

443
Both patterns support additional parameters like `retry`, `timeout`, and `metadata`. The documentation shows simplified signatures focusing on the primary parameters for clarity.
444

445
## Error Handling
446

447
The client library uses Google Cloud standard error handling with `google.api_core.exceptions`:
448

449
```python
450
from google.api_core import exceptions
451

452
try:
453
    job = client.get_job(name="invalid-job-name")
454
except exceptions.NotFound:
455
    print("Job not found")
456
except exceptions.PermissionDenied:
457
    print("Access denied")
458
except exceptions.InvalidArgument as e:
459
    print(f"Invalid request: {e}")
460
```
461

462
Common exceptions include `NotFound`, `PermissionDenied`, `InvalidArgument`, `AlreadyExists`, and `ResourceExhausted` for quota limits.