Debian Codegraph @

kgsearch/v1/kgsearch-gen.go

raw
1 // Copyright 2026 Google LLC.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4
5 // Code generated file. DO NOT EDIT.
6
7 // Package kgsearch provides access to the Knowledge Graph Search API.
8 //
9 // For product documentation, see: https://developers.google.com/knowledge-graph/
10 //
11 // # Library status
12 //
13 // These client libraries are officially supported by Google. However, this
14 // library is considered complete and is in maintenance mode. This means
15 // that we will address critical bugs and security issues but will not add
16 // any new features.
17 //
18 // When possible, we recommend using our newer
19 // [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go)
20 // that are still actively being worked and iterated on.
21 //
22 // # Creating a client
23 //
24 // Usage example:
25 //
26 // import "google.golang.org/api/kgsearch/v1"
27 // ...
28 // ctx := context.Background()
29 // kgsearchService, err := kgsearch.NewService(ctx)
30 //
31 // In this example, Google Application Default Credentials are used for
32 // authentication. For information on how to create and obtain Application
33 // Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials.
34 //
35 // # Other authentication options
36 //
37 // To use an API key for authentication (note: some APIs do not support API
38 // keys), use [google.golang.org/api/option.WithAPIKey]:
39 //
40 // kgsearchService, err := kgsearch.NewService(ctx, option.WithAPIKey("AIza..."))
41 //
42 // To use an OAuth token (e.g., a user token obtained via a three-legged OAuth
43 // flow, use [google.golang.org/api/option.WithTokenSource]:
44 //
45 // config := &oauth2.Config{...}
46 // // ...
47 // token, err := config.Exchange(ctx, ...)
48 // kgsearchService, err := kgsearch.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token)))
49 //
50 // See [google.golang.org/api/option.ClientOption] for details on options.
51 package kgsearch // import "google.golang.org/api/kgsearch/v1"
52
53 import (
54 "bytes"
55 "context"
56 "encoding/json"
57 "errors"
58 "fmt"
59 "io"
60 "log/slog"
61 "net/http"
62 "net/url"
63 "strconv"
64 "strings"
65
66 "github.com/googleapis/gax-go/v2/internallog"
67 googleapi "google.golang.org/api/googleapi"
68 internal "google.golang.org/api/internal"
69 gensupport "google.golang.org/api/internal/gensupport"
70 option "google.golang.org/api/option"
71 internaloption "google.golang.org/api/option/internaloption"
72 htransport "google.golang.org/api/transport/http"
73 )
74
75 // Always reference these packages, just in case the auto-generated code
76 // below doesn't.
77 var _ = bytes.NewBuffer
78 var _ = strconv.Itoa
79 var _ = fmt.Sprintf
80 var _ = json.NewDecoder
81 var _ = io.Copy
82 var _ = url.Parse
83 var _ = gensupport.MarshalJSON
84 var _ = googleapi.Version
85 var _ = errors.New
86 var _ = strings.Replace
87 var _ = context.Canceled
88 var _ = internaloption.WithDefaultEndpoint
89 var _ = internal.Version
90 var _ = internallog.New
91
92 const apiId = "kgsearch:v1"
93 const apiName = "kgsearch"
94 const apiVersion = "v1"
95 const basePath = "https://kgsearch.googleapis.com/"
96 const basePathTemplate = "https://kgsearch.UNIVERSE_DOMAIN/"
97 const mtlsBasePath = "https://kgsearch.mtls.googleapis.com/"
98
99 // NewService creates a new Service.
100 func NewService(ctx context.Context, opts ...option.ClientOption) (*Service, error) {
101 opts = append(opts, internaloption.WithDefaultEndpoint(basePath))
102 opts = append(opts, internaloption.WithDefaultEndpointTemplate(basePathTemplate))
103 opts = append(opts, internaloption.WithDefaultMTLSEndpoint(mtlsBasePath))
104 opts = append(opts, internaloption.EnableNewAuthLibrary())
105 client, endpoint, err := htransport.NewClient(ctx, opts...)
106 if err != nil {
107 return nil, err
108 }
109 s := &Service{client: client, BasePath: basePath, logger: internaloption.GetLogger(opts)}
110 s.Entities = NewEntitiesService(s)
111 if endpoint != "" {
112 s.BasePath = endpoint
113 }
114 return s, nil
115 }
116
117 // New creates a new Service. It uses the provided http.Client for requests.
118 //
119 // Deprecated: please use NewService instead.
120 // To provide a custom HTTP client, use option.WithHTTPClient.
121 // If you are using google.golang.org/api/googleapis/transport.APIKey, use option.WithAPIKey with NewService instead.
122 func New(client *http.Client) (*Service, error) {
123 if client == nil {
124 return nil, errors.New("client is nil")
125 }
126 return NewService(context.TODO(), option.WithHTTPClient(client))
127 }
128
129 type Service struct {
130 client *http.Client
131 logger *slog.Logger
132 BasePath string // API endpoint base URL
133 UserAgent string // optional additional User-Agent fragment
134
135 Entities *EntitiesService
136 }
137
138 func (s *Service) userAgent() string {
139 if s.UserAgent == "" {
140 return googleapi.UserAgent
141 }
142 return googleapi.UserAgent + " " + s.UserAgent
143 }
144
145 func NewEntitiesService(s *Service) *EntitiesService {
146 rs := &EntitiesService{s: s}
147 return rs
148 }
149
150 type EntitiesService struct {
151 s *Service
152 }
153
154 // SearchResponse: Response message includes the context and a list of matching
155 // results which contain the detail of associated entities.
156 type SearchResponse struct {
157 // ItemListElement: The item list of search results.
158 ItemListElement []interface{} `json:"itemListElement,omitempty"`
159
160 // ServerResponse contains the HTTP response code and headers from the server.
161 googleapi.ServerResponse `json:"-"`
162 // ForceSendFields is a list of field names (e.g. "ItemListElement") to
163 // unconditionally include in API requests. By default, fields with empty or
164 // default values are omitted from API requests. See
165 // https://pkg.go.dev/google.golang.org/api#hdr-ForceSendFields for more
166 // details.
167 ForceSendFields []string `json:"-"`
168 // NullFields is a list of field names (e.g. "ItemListElement") to include in
169 // API requests with the JSON null value. By default, fields with empty values
170 // are omitted from API requests. See
171 // https://pkg.go.dev/google.golang.org/api#hdr-NullFields for more details.
172 NullFields []string `json:"-"`
173 }
174
175 func (s SearchResponse) MarshalJSON() ([]byte, error) {
176 type NoMethod SearchResponse
177 return gensupport.MarshalJSON(NoMethod(s), s.ForceSendFields, s.NullFields)
178 }
179
180 type EntitiesSearchCall struct {
181 s *Service
182 urlParams_ gensupport.URLParams
183 ifNoneMatch_ string
184 ctx_ context.Context
185 header_ http.Header
186 }
187
188 // Search: Searches Knowledge Graph for entities that match the constraints. A
189 // list of matched entities will be returned in response, which will be in
190 // JSON-LD format and compatible with http://schema.org
191 func (r *EntitiesService) Search() *EntitiesSearchCall {
192 c := &EntitiesSearchCall{s: r.s, urlParams_: make(gensupport.URLParams)}
193 return c
194 }
195
196 // Ids sets the optional parameter "ids": The list of entity id to be used for
197 // search instead of query string. To specify multiple ids in the HTTP request,
198 // repeat the parameter in the URL as in ...?ids=A&ids=B
199 func (c *EntitiesSearchCall) Ids(ids ...string) *EntitiesSearchCall {
200 c.urlParams_.SetMulti("ids", append([]string{}, ids...))
201 return c
202 }
203
204 // Indent sets the optional parameter "indent": Enables indenting of json
205 // results.
206 func (c *EntitiesSearchCall) Indent(indent bool) *EntitiesSearchCall {
207 c.urlParams_.Set("indent", fmt.Sprint(indent))
208 return c
209 }
210
211 // Languages sets the optional parameter "languages": The list of language
212 // codes (defined in ISO 693) to run the query with, e.g. 'en'.
213 func (c *EntitiesSearchCall) Languages(languages ...string) *EntitiesSearchCall {
214 c.urlParams_.SetMulti("languages", append([]string{}, languages...))
215 return c
216 }
217
218 // Limit sets the optional parameter "limit": Limits the number of entities to
219 // be returned.
220 func (c *EntitiesSearchCall) Limit(limit int64) *EntitiesSearchCall {
221 c.urlParams_.Set("limit", fmt.Sprint(limit))
222 return c
223 }
224
225 // Prefix sets the optional parameter "prefix": Enables prefix match against
226 // names and aliases of entities
227 func (c *EntitiesSearchCall) Prefix(prefix bool) *EntitiesSearchCall {
228 c.urlParams_.Set("prefix", fmt.Sprint(prefix))
229 return c
230 }
231
232 // Query sets the optional parameter "query": The literal query string for
233 // search.
234 func (c *EntitiesSearchCall) Query(query string) *EntitiesSearchCall {
235 c.urlParams_.Set("query", query)
236 return c
237 }
238
239 // Types sets the optional parameter "types": Restricts returned entities with
240 // these types, e.g. Person (as defined in http://schema.org/Person). If
241 // multiple types are specified, returned entities will contain one or more of
242 // these types.
243 func (c *EntitiesSearchCall) Types(types ...string) *EntitiesSearchCall {
244 c.urlParams_.SetMulti("types", append([]string{}, types...))
245 return c
246 }
247
248 // Fields allows partial responses to be retrieved. See
249 // https://developers.google.com/gdata/docs/2.0/basics#PartialResponse for more
250 // details.
251 func (c *EntitiesSearchCall) Fields(s ...googleapi.Field) *EntitiesSearchCall {
252 c.urlParams_.Set("fields", googleapi.CombineFields(s))
253 return c
254 }
255
256 // IfNoneMatch sets an optional parameter which makes the operation fail if the
257 // object's ETag matches the given value. This is useful for getting updates
258 // only after the object has changed since the last request.
259 func (c *EntitiesSearchCall) IfNoneMatch(entityTag string) *EntitiesSearchCall {
260 c.ifNoneMatch_ = entityTag
261 return c
262 }
263
264 // Context sets the context to be used in this call's Do method.
265 func (c *EntitiesSearchCall) Context(ctx context.Context) *EntitiesSearchCall {
266 c.ctx_ = ctx
267 return c
268 }
269
270 // Header returns a http.Header that can be modified by the caller to add
271 // headers to the request.
272 func (c *EntitiesSearchCall) Header() http.Header {
273 if c.header_ == nil {
274 c.header_ = make(http.Header)
275 }
276 return c.header_
277 }
278
279 func (c *EntitiesSearchCall) doRequest(alt string) (*http.Response, error) {
280 reqHeaders := gensupport.SetHeaders(c.s.userAgent(), "", c.header_)
281 if c.ifNoneMatch_ != "" {
282 reqHeaders.Set("If-None-Match", c.ifNoneMatch_)
283 }
284 c.urlParams_.Set("alt", alt)
285 c.urlParams_.Set("prettyPrint", "false")
286 urls := googleapi.ResolveRelative(c.s.BasePath, "v1/entities:search")
287 urls += "?" + c.urlParams_.Encode()
288 req, err := http.NewRequest("GET", urls, nil)
289 if err != nil {
290 return nil, err
291 }
292 req.Header = reqHeaders
293 c.s.logger.DebugContext(c.ctx_, "api request", "serviceName", apiName, "rpcName", "kgsearch.entities.search", "request", internallog.HTTPRequest(req, nil))
294 return gensupport.SendRequest(c.ctx_, c.s.client, req)
295 }
296
297 // Do executes the "kgsearch.entities.search" call.
298 // Any non-2xx status code is an error. Response headers are in either
299 // *SearchResponse.ServerResponse.Header or (if a response was returned at all)
300 // in error.(*googleapi.Error).Header. Use googleapi.IsNotModified to check
301 // whether the returned error was because http.StatusNotModified was returned.
302 func (c *EntitiesSearchCall) Do(opts ...googleapi.CallOption) (*SearchResponse, error) {
303 gensupport.SetOptions(c.urlParams_, opts...)
304 res, err := c.doRequest("json")
305 if res != nil && res.StatusCode == http.StatusNotModified {
306 if res.Body != nil {
307 res.Body.Close()
308 }
309 return nil, gensupport.WrapError(&googleapi.Error{
310 Code: res.StatusCode,
311 Header: res.Header,
312 })
313 }
314 if err != nil {
315 return nil, err
316 }
317 defer googleapi.CloseBody(res)
318 if err := googleapi.CheckResponse(res); err != nil {
319 return nil, gensupport.WrapError(err)
320 }
321 ret := &SearchResponse{
322 ServerResponse: googleapi.ServerResponse{
323 Header: res.Header,
324 HTTPStatusCode: res.StatusCode,
325 },
326 }
327 target := &ret
328 b, err := gensupport.DecodeResponseBytes(target, res)
329 if err != nil {
330 return nil, err
331 }
332 c.s.logger.DebugContext(c.ctx_, "api response", "serviceName", apiName, "rpcName", "kgsearch.entities.search", "response", internallog.HTTPResponse(res, b))
333 return ret, nil
334 }