or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

company-management.mdevent-tracking.mdindex.mdjob-management.mdquery-autocompletion.mdsearch-filtering.mdtenant-management.md
tile.json

tessl/pypi-google-cloud-talent

Google Cloud Talent API client library for job search and talent management

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/google-cloud-talent@2.17.x

To install, run

npx @tessl/cli install tessl/pypi-google-cloud-talent@2.17.0

index.mddocs/

Google Cloud Talent API

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.

Package Information

  • Package Name: google-cloud-talent
  • Language: Python
  • Installation: pip install google-cloud-talent

Core Imports

from google.cloud import talent

For specific API versions:

from google.cloud import talent_v4
from google.cloud import talent_v4beta1

Common service client imports:

from google.cloud.talent import (
    JobServiceClient,
    CompanyServiceClient,
    TenantServiceClient,
    EventServiceClient,
    CompletionClient
)

For async clients:

from google.cloud.talent import (
    JobServiceAsyncClient,
    CompanyServiceAsyncClient,
    TenantServiceAsyncClient,
    EventServiceAsyncClient,
    CompletionAsyncClient
)

For request/response types:

from google.cloud.talent import (
    # Job service types
    SearchJobsRequest, SearchJobsResponse, ListJobsResponse,
    CreateJobRequest, UpdateJobRequest, DeleteJobRequest, GetJobRequest,
    BatchCreateJobsRequest, BatchUpdateJobsRequest, BatchDeleteJobsRequest,
    # Company service types  
    ListCompaniesResponse, CreateCompanyRequest, UpdateCompanyRequest,
    # Tenant service types
    ListTenantsResponse, CreateTenantRequest, UpdateTenantRequest,
    # Event service types
    CreateClientEventRequest,
    # Completion service types
    CompleteQueryRequest, CompleteQueryResponse
)

For working with field masks and protobuf types:

from google.protobuf import field_mask_pb2
from google.protobuf import duration_pb2
from google.protobuf.timestamp_pb2 import Timestamp
from google.type import money_pb2, latlng_pb2

Basic Usage

from google.cloud.talent import JobServiceClient, Job, Company

# Initialize the client
client = JobServiceClient()

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

tenant_client = TenantServiceClient()
tenant = Tenant(external_id="my-tenant-123")
tenant_response = tenant_client.create_tenant(
    parent="projects/my-project-id",
    tenant=tenant
)

# Create a company
from google.cloud.talent import CompanyServiceClient

company_client = CompanyServiceClient()
company = Company(
    display_name="Example Corp",
    external_id="example-corp-123"
)
company_response = company_client.create_company(
    parent=tenant_response.name,
    company=company
)

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

job_response = client.create_job(
    parent=tenant_response.name,
    job=job
)

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

search_request = SearchJobsRequest(
    parent=tenant_response.name,
    job_query=JobQuery(
        query="software engineer",
        location_filters=[{"address": "San Francisco, CA"}]
    )
)

search_response = client.search_jobs(search_request)
for matching_job in search_response.matching_jobs:
    print(f"Job: {matching_job.job.title}")

Architecture

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

  • TenantService: Multi-tenant data isolation and management
  • CompanyService: Company entity management and profiles
  • JobService: Job posting lifecycle, search, and batch operations
  • EventService: User interaction tracking and analytics
  • CompletionService: Query autocompletion and suggestions

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.

Capabilities

Job Management

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.

class JobServiceClient:
    def create_job(self, parent: str, job: Job) -> Job: ...
    def get_job(self, name: str) -> Job: ...
    def update_job(self, job: Job, update_mask: FieldMask = None) -> Job: ...
    def delete_job(self, name: str) -> None: ...
    def list_jobs(self, parent: str, filter: str = None, page_size: int = None, 
                  page_token: str = None, job_view: JobView = None) -> ListJobsResponse: ...
    def search_jobs(self, request: SearchJobsRequest) -> SearchJobsResponse: ...
    def search_jobs_for_alert(self, request: SearchJobsRequest) -> SearchJobsResponse: ...
    def batch_create_jobs(self, parent: str, jobs: List[Job]) -> Operation: ...
    def batch_update_jobs(self, parent: str, jobs: List[Job]) -> Operation: ...
    def batch_delete_jobs(self, parent: str, names: List[str]) -> Operation: ...

Job Management

Company Management

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

class CompanyServiceClient:
    def create_company(self, parent: str, company: Company) -> Company: ...
    def get_company(self, name: str) -> Company: ...
    def update_company(self, company: Company, update_mask: FieldMask = None) -> Company: ...
    def delete_company(self, name: str) -> None: ...
    def list_companies(self, parent: str, page_size: int = None, 
                      page_token: str = None) -> ListCompaniesResponse: ...

Company Management

Tenant Management

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

class TenantServiceClient:
    def create_tenant(self, parent: str, tenant: Tenant) -> Tenant: ...
    def get_tenant(self, name: str) -> Tenant: ...
    def update_tenant(self, tenant: Tenant, update_mask: FieldMask = None) -> Tenant: ...
    def delete_tenant(self, name: str) -> None: ...
    def list_tenants(self, parent: str, page_size: int = None, 
                    page_token: str = None) -> ListTenantsResponse: ...

Tenant Management

Search and Filtering

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.

class JobQuery:
    query: str = None
    companies: List[str] = None
    location_filters: List[LocationFilter] = None
    job_categories: List[JobCategory] = None
    employment_types: List[EmploymentType] = None
    compensation_filter: CompensationFilter = None
    commute_filter: CommuteFilter = None
    custom_attribute_filter: str = None
    publish_time_range: TimestampRange = None

class LocationFilter:
    address: str = None
    region_code: str = None
    lat_lng: LatLng = None
    distance_in_miles: float = None
    telecommute_preference: TelecommutePreference = None

class CompensationFilter:
    type_: FilterType = None
    units: List[CompensationUnit] = None
    range_: CompensationRange = None

Search and Filtering

Event Tracking and Analytics

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.

class EventServiceClient:
    def create_client_event(self, parent: str, client_event: ClientEvent) -> ClientEvent: ...

class ClientEvent:
    request_id: str = None
    event_id: str = None
    create_time: Timestamp = None
    job_event: JobEvent = None
    event_notes: str = None

Event Tracking

Query Autocompletion

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

class CompletionClient:
    def complete_query(self, tenant: str, query: str, page_size: int = None,
                      language_codes: List[str] = None, company: str = None,
                      scope: CompletionScope = None, type_: CompletionType = None) -> CompleteQueryResponse: ...

Query Autocompletion

Core Data Types

Job Entity

class Job:
    name: str = None  # Resource name (auto-generated)
    company: str = None  # Company resource name (required)
    requisition_id: str = None  # Client-defined job identifier (required)
    title: str = None  # Job title (required, max 500 chars)
    description: str = None  # Job description (required, max 100k chars, HTML supported)
    addresses: List[str] = None  # Job location addresses (max 50)
    employment_types: List[EmploymentType] = None  # Employment types
    job_level: JobLevel = None  # Experience level required
    job_categories: List[JobCategory] = None  # Derived job categories
    compensation_info: CompensationInfo = None  # Salary/compensation details
    job_benefits: List[JobBenefit] = None  # Benefits offered
    qualifications: str = None  # Required qualifications (max 10k chars, HTML)
    responsibilities: str = None  # Job responsibilities (max 10k chars, HTML)
    custom_attributes: Dict[str, CustomAttribute] = None  # Custom job attributes
    posting_expire_time: Timestamp = None  # Job expiration date
    visibility: Visibility = None  # Job visibility settings

Company Entity

class Company:
    name: str = None  # Resource name (auto-generated)
    display_name: str = None  # Company name (required)
    external_id: str = None  # Client-defined company identifier (required)
    size: CompanySize = None  # Company size category
    headquarters_address: str = None  # Main office address
    website_uri: str = None  # Company website URL
    career_site_uri: str = None  # Careers page URL
    image_uri: str = None  # Company logo URL
    eeo_text: str = None  # Equal employment opportunity statement

Tenant Entity

class Tenant:
    name: str = None  # Resource name (auto-generated)
    external_id: str = None  # Client-defined tenant identifier (required)

Compensation Types

class CompensationInfo:
    entries: List[CompensationEntry] = None  # Individual compensation components
    annualized_base_compensation_range: CompensationRange = None  # Base salary range
    annualized_total_compensation_range: CompensationRange = None  # Total compensation range

class CompensationRange:
    max_compensation: Money = None  # Maximum compensation
    min_compensation: Money = None  # Minimum compensation

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

class CompensationUnit(Enum):
    HOURLY = 1
    DAILY = 2
    WEEKLY = 3
    MONTHLY = 4
    YEARLY = 5
    ONE_TIME = 6

Location and Geographic Types

class Location:
    location_type: LocationType = None  # COUNTRY, ADMINISTRATIVE_AREA, LOCALITY, etc.
    postal_address: PostalAddress = None  # Structured postal address
    lat_lng: LatLng = None  # Latitude/longitude coordinates
    radius_miles: float = None  # Location radius

class LatLng:
    latitude: float = None  # Latitude in degrees
    longitude: float = None  # Longitude in degrees

class Duration:
    seconds: int = None  # Duration in seconds
    nanos: int = None  # Fractional seconds in nanoseconds

Utility Types

class CustomAttribute:
    string_values: List[str] = None  # String attribute values
    long_values: List[int] = None  # Integer attribute values
    filterable: bool = None  # Whether attribute can be used in filters

class TimestampRange:
    start_time: Timestamp = None  # Range start time
    end_time: Timestamp = None  # Range end time

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

Key Enums and Constants

Employment and Job Classification

class EmploymentType(Enum):
    FULL_TIME = 1
    PART_TIME = 2
    CONTRACTOR = 3
    CONTRACT_TO_HIRE = 4
    TEMPORARY = 5
    INTERN = 6
    VOLUNTEER = 7
    PER_DIEM = 8
    FLY_IN_FLY_OUT = 9

class JobLevel(Enum):
    ENTRY_LEVEL = 1
    EXPERIENCED = 2
    MANAGER = 3
    DIRECTOR = 4
    EXECUTIVE = 5

class JobCategory(Enum):
    COMPUTER_AND_IT = 1
    HEALTHCARE = 2
    FINANCE = 3
    EDUCATION = 4
    # ... 30+ additional categories

class CompanySize(Enum):
    MINI = 1  # <50 employees
    SMALL = 2  # 50-99 employees
    SMEDIUM = 3  # 100-499 employees
    MEDIUM = 4  # 500-999 employees
    BIG = 5  # 1k-5k employees
    BIGGER = 6  # 5k-10k employees
    GIANT = 7  # 10k+ employees

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

Resource Naming Patterns

  • Projects: projects/{project_id}
  • Tenants: projects/{project_id}/tenants/{tenant_id}
  • Companies: projects/{project_id}/tenants/{tenant_id}/companies/{company_id}
  • Jobs: projects/{project_id}/tenants/{tenant_id}/jobs/{job_id}

Method Calling Patterns

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

Individual Parameters (Recommended for simple cases):

job = client.create_job(parent=tenant_name, job=job_object)

Request Objects (Recommended for complex cases):

from google.cloud.talent import CreateJobRequest

request = CreateJobRequest(parent=tenant_name, job=job_object)
job = client.create_job(request=request)

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

Error Handling

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

from google.api_core import exceptions

try:
    job = client.get_job(name="invalid-job-name")
except exceptions.NotFound:
    print("Job not found")
except exceptions.PermissionDenied:
    print("Access denied")
except exceptions.InvalidArgument as e:
    print(f"Invalid request: {e}")

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