1// Copyright 2023 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.talent.v4;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/resource.proto";
23import "google/cloud/talent/v4/common.proto";
24
25option go_package = "cloud.google.com/go/talent/apiv4/talentpb;talentpb";
26option java_multiple_files = true;
27option java_outer_classname = "CompletionServiceProto";
28option java_package = "com.google.cloud.talent.v4";
29option objc_class_prefix = "CTS";
30
31// A service handles auto completion.
32service Completion {
33  option (google.api.default_host) = "jobs.googleapis.com";
34  option (google.api.oauth_scopes) =
35      "https://www.googleapis.com/auth/cloud-platform,"
36      "https://www.googleapis.com/auth/jobs";
37
38  // Completes the specified prefix with keyword suggestions.
39  // Intended for use by a job search auto-complete search box.
40  rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) {
41    option (google.api.http) = {
42      get: "/v4/{tenant=projects/*/tenants/*}:completeQuery"
43    };
44  }
45}
46
47// Auto-complete parameters.
48message CompleteQueryRequest {
49  // Enum to specify the scope of completion.
50  enum CompletionScope {
51    // Default value.
52    COMPLETION_SCOPE_UNSPECIFIED = 0;
53
54    // Suggestions are based only on the data provided by the client.
55    TENANT = 1;
56
57    // Suggestions are based on all jobs data in the system that's visible to
58    // the client
59    PUBLIC = 2;
60  }
61
62  // Enum to specify auto-completion topics.
63  enum CompletionType {
64    // Default value.
65    COMPLETION_TYPE_UNSPECIFIED = 0;
66
67    // Suggest job titles for jobs autocomplete.
68    //
69    // For
70    // [CompletionType.JOB_TITLE][google.cloud.talent.v4.CompleteQueryRequest.CompletionType.JOB_TITLE]
71    // type, only open jobs with the same
72    // [language_codes][google.cloud.talent.v4.CompleteQueryRequest.language_codes]
73    // are returned.
74    JOB_TITLE = 1;
75
76    // Suggest company names for jobs autocomplete.
77    //
78    // For
79    // [CompletionType.COMPANY_NAME][google.cloud.talent.v4.CompleteQueryRequest.CompletionType.COMPANY_NAME]
80    // type, only companies having open jobs with the same
81    // [language_codes][google.cloud.talent.v4.CompleteQueryRequest.language_codes]
82    // are returned.
83    COMPANY_NAME = 2;
84
85    // Suggest both job titles and company names for jobs autocomplete.
86    //
87    // For
88    // [CompletionType.COMBINED][google.cloud.talent.v4.CompleteQueryRequest.CompletionType.COMBINED]
89    // type, only open jobs with the same
90    // [language_codes][google.cloud.talent.v4.CompleteQueryRequest.language_codes]
91    // or companies having open jobs with the same
92    // [language_codes][google.cloud.talent.v4.CompleteQueryRequest.language_codes]
93    // are returned.
94    COMBINED = 3;
95  }
96
97  // Required. Resource name of tenant the completion is performed within.
98  //
99  // The format is "projects/{project_id}/tenants/{tenant_id}", for example,
100  // "projects/foo/tenants/bar".
101  string tenant = 1 [
102    (google.api.field_behavior) = REQUIRED,
103    (google.api.resource_reference) = { type: "jobs.googleapis.com/Tenant" }
104  ];
105
106  // Required. The query used to generate suggestions.
107  //
108  // The maximum number of allowed characters is 255.
109  string query = 2 [(google.api.field_behavior) = REQUIRED];
110
111  // The list of languages of the query. This is
112  // the BCP-47 language code, such as "en-US" or "sr-Latn".
113  // For more information, see
114  // [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47).
115  //
116  // The maximum number of allowed characters is 255.
117  repeated string language_codes = 3;
118
119  // Required. Completion result count.
120  //
121  // The maximum allowed page size is 10.
122  int32 page_size = 4 [(google.api.field_behavior) = REQUIRED];
123
124  // If provided, restricts completion to specified company.
125  //
126  // The format is
127  // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for
128  // example, "projects/foo/tenants/bar/companies/baz".
129  string company = 5 [
130    (google.api.resource_reference) = { type: "jobs.googleapis.com/Company" }
131  ];
132
133  // The scope of the completion. The defaults is
134  // [CompletionScope.PUBLIC][google.cloud.talent.v4.CompleteQueryRequest.CompletionScope.PUBLIC].
135  CompletionScope scope = 6;
136
137  // The completion topic. The default is
138  // [CompletionType.COMBINED][google.cloud.talent.v4.CompleteQueryRequest.CompletionType.COMBINED].
139  CompletionType type = 7;
140}
141
142// Response of auto-complete query.
143message CompleteQueryResponse {
144  // Resource that represents completion results.
145  message CompletionResult {
146    // The suggestion for the query.
147    string suggestion = 1;
148
149    // The completion topic.
150    CompleteQueryRequest.CompletionType type = 2;
151
152    // The URI of the company image for
153    // [COMPANY_NAME][google.cloud.talent.v4.CompleteQueryRequest.CompletionType.COMPANY_NAME].
154    string image_uri = 3;
155  }
156
157  // Results of the matching job/company candidates.
158  repeated CompletionResult completion_results = 1;
159
160  // Additional information for the API invocation, such as the request
161  // tracking id.
162  ResponseMetadata metadata = 2;
163}
164