@googlemaps/places 1.0.1 → 1.2.0

package/build/src/index.js

@@ -1,5 +1,5 @@
 "use strict";
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

package/build/src/v1/index.js

@@ -1,5 +1,5 @@
 "use strict";
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

package/build/src/v1/places_client.d.ts

@@ -3,6 +3,11 @@ import type { Callback, CallOptions, Descriptors, ClientOptions } from 'google-g
 import * as protos from '../../protos/protos';
 /**
  *  Service definition for the Places API.
+ *  Note: every request actually requires a field mask set outside of
+ *  the request proto (all/'*', is not assumed).  That can be set via either a
+ *  side channel (SystemParameterContext) over RPC, or a header
+ *  (X-Goog-FieldMask) over HTTP. See:
+ *  https://cloud.google.com/apis/docs/system-parameters
  * @class
  * @memberof v1
  */
@@ -14,12 +19,17 @@ export declare class PlacesClient {
     private _gaxGrpc;
     private _protos;
     private _defaults;
+    private _universeDomain;
+    private _servicePath;
     auth: gax.GoogleAuth;
     descriptors: Descriptors;
     warn: (code: string, message: string, warnType?: string) => void;
     innerApiCalls: {
         [name: string]: Function;
     };
+    pathTemplates: {
+        [name: string]: gax.PathTemplate;
+    };
     placesStub?: Promise<{
         [name: string]: Function;
     }>;
@@ -79,15 +89,22 @@ export declare class PlacesClient {
     }>;
     /**
      * The DNS address for this API service.
+     * @deprecated Use the apiEndpoint method of the client instance.
      * @returns {string} The DNS address for this service.
      */
     static get servicePath(): string;
     /**
-     * The DNS address for this API service - same as servicePath(),
-     * exists for compatibility reasons.
+     * The DNS address for this API service - same as servicePath.
+     * @deprecated Use the apiEndpoint method of the client instance.
      * @returns {string} The DNS address for this service.
      */
     static get apiEndpoint(): string;
+    /**
+     * The DNS address for this API service.
+     * @returns {string} The DNS address for this service.
+     */
+    get apiEndpoint(): string;
+    get universeDomain(): string;
     /**
      * The port for this API service.
      * @returns {number} The default port for this service.
@@ -101,6 +118,129 @@ export declare class PlacesClient {
     static get scopes(): never[];
     getProjectId(): Promise<string>;
     getProjectId(callback: Callback<string, undefined, undefined>): void;
+    /**
+     * Search for places near locations.
+     *
+     * @param {Object} request
+     *   The request object that will be sent.
+     * @param {string} request.languageCode
+     *   Place details will be displayed with the preferred language if available.
+     *   If the language code is unspecified or unrecognized, place details of any
+     *   language may be returned, with a preference for English if such details
+     *   exist.
+     *
+     *   Current list of supported languages:
+     *   https://developers.google.com/maps/faq#languagesupport.
+     * @param {string} request.regionCode
+     *   The Unicode country/region code (CLDR) of the location where the
+     *   request is coming from. This parameter is used to display the place
+     *   details, like region-specific place name, if available. The parameter can
+     *   affect results based on applicable law.
+     *
+     *   For more information, see
+     *   https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.
+     *
+     *
+     *   Note that 3-digit region codes are not currently supported.
+     * @param {string[]} request.includedTypes
+     *   Included Place type (eg, "restaurant" or "gas_station") from
+     *   https://developers.google.com/maps/documentation/places/web-service/place-types.
+     *
+     *   Up to 50 types from [Table
+     *   A](https://developers.google.com/maps/documentation/places/web-service/place-types#table-a)
+     *   may be specified.
+     *
+     *   If there are any conflicting types, i.e. a type appears in both
+     *   included_types and excluded_types, an INVALID_ARGUMENT error is
+     *   returned.
+     *
+     *   If a Place type is specified with multiple type restrictions, only places
+     *   that satisfy all of the restrictions are returned. For example, if we
+     *   have {included_types = ["restaurant"], excluded_primary_types =
+     *   ["restaurant"]}, the returned places provide "restaurant"
+     *   related services but do not operate primarily as "restaurants".
+     * @param {string[]} request.excludedTypes
+     *   Excluded Place type (eg, "restaurant" or "gas_station") from
+     *   https://developers.google.com/maps/documentation/places/web-service/place-types.
+     *
+     *   Up to 50 types from [Table
+     *   A](https://developers.google.com/maps/documentation/places/web-service/place-types#table-a)
+     *   may be specified.
+     *
+     *   If the client provides both included_types (e.g. restaurant) and
+     *   excluded_types (e.g. cafe), then the response should include places that
+     *   are restaurant but not cafe. The response includes places that match at
+     *   least one of the included_types and none of the excluded_types.
+     *
+     *   If there are any conflicting types, i.e. a type appears in both
+     *   included_types and excluded_types, an INVALID_ARGUMENT error is returned.
+     *
+     *   If a Place type is specified with multiple type restrictions, only places
+     *   that satisfy all of the restrictions are returned. For example, if we
+     *   have {included_types = ["restaurant"], excluded_primary_types =
+     *   ["restaurant"]}, the returned places provide "restaurant"
+     *   related services but do not operate primarily as "restaurants".
+     * @param {string[]} request.includedPrimaryTypes
+     *   Included primary Place type (e.g. "restaurant" or "gas_station") from
+     *   https://developers.google.com/maps/documentation/places/web-service/place-types.
+     *   A place can only have a single primary type from the supported types table
+     *   associated with it.
+     *
+     *   Up to 50 types from [Table
+     *   A](https://developers.google.com/maps/documentation/places/web-service/place-types#table-a)
+     *   may be specified.
+     *
+     *   If there are any conflicting primary types, i.e. a type appears in both
+     *   included_primary_types and excluded_primary_types, an INVALID_ARGUMENT
+     *   error is returned.
+     *
+     *   If a Place type is specified with multiple type restrictions, only places
+     *   that satisfy all of the restrictions are returned. For example, if we
+     *   have {included_types = ["restaurant"], excluded_primary_types =
+     *   ["restaurant"]}, the returned places provide "restaurant"
+     *   related services but do not operate primarily as "restaurants".
+     * @param {string[]} request.excludedPrimaryTypes
+     *   Excluded primary Place type (e.g. "restaurant" or "gas_station") from
+     *   https://developers.google.com/maps/documentation/places/web-service/place-types.
+     *
+     *   Up to 50 types from [Table
+     *   A](https://developers.google.com/maps/documentation/places/web-service/place-types#table-a)
+     *   may be specified.
+     *
+     *   If there are any conflicting primary types, i.e. a type appears in both
+     *   included_primary_types and excluded_primary_types, an INVALID_ARGUMENT
+     *   error is returned.
+     *
+     *   If a Place type is specified with multiple type restrictions, only places
+     *   that satisfy all of the restrictions are returned. For example, if we
+     *   have {included_types = ["restaurant"], excluded_primary_types =
+     *   ["restaurant"]}, the returned places provide "restaurant"
+     *   related services but do not operate primarily as "restaurants".
+     * @param {number} request.maxResultCount
+     *   Maximum number of results to return. It must be between 1 and 20 (default),
+     *   inclusively. If the number is unset, it falls back to the upper limit. If
+     *   the number is set to negative or exceeds the upper limit, an
+     *   INVALID_ARGUMENT error is returned.
+     * @param {google.maps.places.v1.SearchNearbyRequest.LocationRestriction} request.locationRestriction
+     *   Required. The region to search.
+     * @param {google.maps.places.v1.SearchNearbyRequest.RankPreference} request.rankPreference
+     *   How results will be ranked in the response.
+     * @param {object} [options]
+     *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+     * @returns {Promise} - The promise which resolves to an array.
+     *   The first element of the array is an object representing {@link protos.google.maps.places.v1.SearchNearbyResponse|SearchNearbyResponse}.
+     *   Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation }
+     *   for more details and examples.
+     * @example <caption>include:samples/generated/v1/places.search_nearby.js</caption>
+     * region_tag:places_v1_generated_Places_SearchNearby_async
+     */
+    searchNearby(request?: protos.google.maps.places.v1.ISearchNearbyRequest, options?: CallOptions): Promise<[
+        protos.google.maps.places.v1.ISearchNearbyResponse,
+        protos.google.maps.places.v1.ISearchNearbyRequest | undefined,
+        {} | undefined
+    ]>;
+    searchNearby(request: protos.google.maps.places.v1.ISearchNearbyRequest, options: CallOptions, callback: Callback<protos.google.maps.places.v1.ISearchNearbyResponse, protos.google.maps.places.v1.ISearchNearbyRequest | null | undefined, {} | null | undefined>): void;
+    searchNearby(request: protos.google.maps.places.v1.ISearchNearbyRequest, callback: Callback<protos.google.maps.places.v1.ISearchNearbyResponse, protos.google.maps.places.v1.ISearchNearbyRequest | null | undefined, {} | null | undefined>): void;
     /**
      * Text query based place search.
      *
@@ -118,48 +258,35 @@ export declare class PlacesClient {
      *   https://developers.google.com/maps/faq#languagesupport.
      * @param {string} request.regionCode
      *   The Unicode country/region code (CLDR) of the location where the
-     *   request is coming from. It is used to display the place details, like
-     *   region-specific place name, if available.
+     *   request is coming from. This parameter is used to display the place
+     *   details, like region-specific place name, if available. The parameter can
+     *   affect results based on applicable law.
      *
      *   For more information, see
-     *   http://www.unicode.org/reports/tr35/#unicode_region_subtag.
+     *   https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.
      *
      *
      *   Note that 3-digit region codes are not currently supported.
      * @param {google.maps.places.v1.SearchTextRequest.RankPreference} request.rankPreference
      *   How results will be ranked in the response.
-     * @param {google.maps.places.v1.SearchTextRequest.Location} request.location
-     *   The region to search. Setting location would usually yields
-     *   better results. Recommended to set. This location serves as a bias unless
-     *   strict_restriction is set to true, which turns the location to a strict
-     *   restriction.
-     *
-     *   Deprecated.  Use LocationRestriction or LocationBias instead.
      * @param {string} request.includedType
      *   The requested place type. Full list of types supported:
-     *   https://developers.google.com/places/supported_types. Only support one
-     *   included type.
+     *   https://developers.google.com/maps/documentation/places/web-service/place-types.
+     *   Only support one included type.
      * @param {boolean} request.openNow
-     *   Used to restrict the search to places that are open at a specific time.
-     *   open_now marks if a business is currently open.
-     * @param {google.maps.places.v1.Int32Range} request.priceRange
-     *   [Deprecated!]Used to restrict the search to places that are within a
-     *   certain price range. This is on a scale of 0 to 4. Set a minimum of 0 or
-     *   set a maximum of 4 has no effect on the search results. Min price is
-     *   default to 0 and max price is default to 4. Default value will be used if
-     *   either min or max is unset.
+     *   Used to restrict the search to places that are currently open.  The default
+     *   is false.
      * @param {number} request.minRating
      *   Filter out results whose average user rating is strictly less than this
-     *   limit. A valid value must be an float between 0 and 5 (inclusively) at a
-     *   0.5 cadence i.e. `[0, 0.5, 1.0, ... , 5.0]` inclusively. This is to keep
-     *   parity with LocalRefinement_UserRating. The input rating will round up to
-     *   the nearest 0.5(ceiling). For instance, a rating of 0.6 will eliminate all
-     *   results with a less than 1.0 rating.
+     *   limit. A valid value must be a float between 0 and 5 (inclusively) at a
+     *   0.5 cadence i.e. [0, 0.5, 1.0, ... , 5.0] inclusively. The input rating
+     *   will round up to the nearest 0.5(ceiling). For instance, a rating of 0.6
+     *   will eliminate all results with a less than 1.0 rating.
      * @param {number} request.maxResultCount
      *   Maximum number of results to return. It must be between 1 and 20,
-     *   inclusively. If the number is unset, it falls back to the upper limit. If
-     *   the number is set to negative or exceeds the upper limit, an
-     *   INVALID_ARGUMENT error is returned.
+     *   inclusively. The default is 20.  If the number is unset, it falls back to
+     *   the upper limit. If the number is set to negative or exceeds the upper
+     *   limit, an INVALID_ARGUMENT error is returned.
      * @param {number[]} request.priceLevels
      *   Used to restrict the search to places that are marked as certain price
      *   levels. Users can choose any combinations of price levels. Default to
@@ -191,6 +318,192 @@ export declare class PlacesClient {
     ]>;
     searchText(request: protos.google.maps.places.v1.ISearchTextRequest, options: CallOptions, callback: Callback<protos.google.maps.places.v1.ISearchTextResponse, protos.google.maps.places.v1.ISearchTextRequest | null | undefined, {} | null | undefined>): void;
     searchText(request: protos.google.maps.places.v1.ISearchTextRequest, callback: Callback<protos.google.maps.places.v1.ISearchTextResponse, protos.google.maps.places.v1.ISearchTextRequest | null | undefined, {} | null | undefined>): void;
+    /**
+     * Get a photo media with a photo reference string.
+     *
+     * @param {Object} request
+     *   The request object that will be sent.
+     * @param {string} request.name
+     *   Required. The resource name of a photo media in the format:
+     *   `places/{place_id}/photos/{photo_reference}/media`.
+     *
+     *   The resource name of a photo as returned in a Place object's `photos.name`
+     *   field comes with the format
+     *   `places/{place_id}/photos/{photo_reference}`. You need to append `/media`
+     *   at the end of the photo resource to get the photo media resource name.
+     * @param {number} [request.maxWidthPx]
+     *   Optional. Specifies the maximum desired width, in pixels, of the image. If
+     *   the image is smaller than the values specified, the original image will be
+     *   returned. If the image is larger in either dimension, it will be scaled to
+     *   match the smaller of the two dimensions, restricted to its original aspect
+     *   ratio. Both the max_height_px and max_width_px properties accept an integer
+     *   between 1 and 4800, inclusively. If the value is not within the allowed
+     *   range, an INVALID_ARGUMENT error will be returned.
+     *
+     *   At least one of max_height_px or max_width_px needs to be specified. If
+     *   neither max_height_px nor max_width_px is specified, an INVALID_ARGUMENT
+     *   error will be returned.
+     * @param {number} [request.maxHeightPx]
+     *   Optional. Specifies the maximum desired height, in pixels, of the image. If
+     *   the image is smaller than the values specified, the original image will be
+     *   returned. If the image is larger in either dimension, it will be scaled to
+     *   match the smaller of the two dimensions, restricted to its original aspect
+     *   ratio. Both the max_height_px and max_width_px properties accept an integer
+     *   between 1 and 4800, inclusively. If the value is not within the allowed
+     *   range, an INVALID_ARGUMENT error will be returned.
+     *
+     *   At least one of max_height_px or max_width_px needs to be specified. If
+     *   neither max_height_px nor max_width_px is specified, an INVALID_ARGUMENT
+     *   error will be returned.
+     * @param {boolean} [request.skipHttpRedirect]
+     *   Optional. If set, skip the default HTTP redirect behavior and render a text
+     *   format (for example, in JSON format for HTTP use case) response. If not
+     *   set, an HTTP redirect will be issued to redirect the call to the image
+     *   media. This option is ignored for non-HTTP requests.
+     * @param {object} [options]
+     *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+     * @returns {Promise} - The promise which resolves to an array.
+     *   The first element of the array is an object representing {@link protos.google.maps.places.v1.PhotoMedia|PhotoMedia}.
+     *   Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation }
+     *   for more details and examples.
+     * @example <caption>include:samples/generated/v1/places.get_photo_media.js</caption>
+     * region_tag:places_v1_generated_Places_GetPhotoMedia_async
+     */
+    getPhotoMedia(request?: protos.google.maps.places.v1.IGetPhotoMediaRequest, options?: CallOptions): Promise<[
+        protos.google.maps.places.v1.IPhotoMedia,
+        protos.google.maps.places.v1.IGetPhotoMediaRequest | undefined,
+        {} | undefined
+    ]>;
+    getPhotoMedia(request: protos.google.maps.places.v1.IGetPhotoMediaRequest, options: CallOptions, callback: Callback<protos.google.maps.places.v1.IPhotoMedia, protos.google.maps.places.v1.IGetPhotoMediaRequest | null | undefined, {} | null | undefined>): void;
+    getPhotoMedia(request: protos.google.maps.places.v1.IGetPhotoMediaRequest, callback: Callback<protos.google.maps.places.v1.IPhotoMedia, protos.google.maps.places.v1.IGetPhotoMediaRequest | null | undefined, {} | null | undefined>): void;
+    /**
+     * Get place details with a place id (in a name) string.
+     *
+     * @param {Object} request
+     *   The request object that will be sent.
+     * @param {string} request.name
+     *   Required. A place ID returned in a Place (with "places/" prefix), or
+     *   equivalently the name in the same Place. Format:
+     *   `places/{place_id}`.
+     * @param {string} [request.languageCode]
+     *   Optional. Place details will be displayed with the preferred language if
+     *   available.
+     *
+     *   Current list of supported languages:
+     *   https://developers.google.com/maps/faq#languagesupport.
+     * @param {string} [request.regionCode]
+     *   Optional. The Unicode country/region code (CLDR) of the location where the
+     *   request is coming from. This parameter is used to display the place
+     *   details, like region-specific place name, if available. The parameter can
+     *   affect results based on applicable law.
+     *   For more information, see
+     *   https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.
+     *
+     *
+     *   Note that 3-digit region codes are not currently supported.
+     * @param {object} [options]
+     *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+     * @returns {Promise} - The promise which resolves to an array.
+     *   The first element of the array is an object representing {@link protos.google.maps.places.v1.Place|Place}.
+     *   Please see the {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#regular-methods | documentation }
+     *   for more details and examples.
+     * @example <caption>include:samples/generated/v1/places.get_place.js</caption>
+     * region_tag:places_v1_generated_Places_GetPlace_async
+     */
+    getPlace(request?: protos.google.maps.places.v1.IGetPlaceRequest, options?: CallOptions): Promise<[
+        protos.google.maps.places.v1.IPlace,
+        protos.google.maps.places.v1.IGetPlaceRequest | undefined,
+        {} | undefined
+    ]>;
+    getPlace(request: protos.google.maps.places.v1.IGetPlaceRequest, options: CallOptions, callback: Callback<protos.google.maps.places.v1.IPlace, protos.google.maps.places.v1.IGetPlaceRequest | null | undefined, {} | null | undefined>): void;
+    getPlace(request: protos.google.maps.places.v1.IGetPlaceRequest, callback: Callback<protos.google.maps.places.v1.IPlace, protos.google.maps.places.v1.IGetPlaceRequest | null | undefined, {} | null | undefined>): void;
+    /**
+     * Return a fully-qualified photo resource name string.
+     *
+     * @param {string} place
+     * @param {string} photo
+     * @returns {string} Resource name string.
+     */
+    photoPath(place: string, photo: string): string;
+    /**
+     * Parse the place from Photo resource.
+     *
+     * @param {string} photoName
+     *   A fully-qualified path representing Photo resource.
+     * @returns {string} A string representing the place.
+     */
+    matchPlaceFromPhotoName(photoName: string): string | number;
+    /**
+     * Parse the photo from Photo resource.
+     *
+     * @param {string} photoName
+     *   A fully-qualified path representing Photo resource.
+     * @returns {string} A string representing the photo.
+     */
+    matchPhotoFromPhotoName(photoName: string): string | number;
+    /**
+     * Return a fully-qualified photoMedia resource name string.
+     *
+     * @param {string} place_id
+     * @param {string} photo_reference
+     * @returns {string} Resource name string.
+     */
+    photoMediaPath(placeId: string, photoReference: string): string;
+    /**
+     * Parse the place_id from PhotoMedia resource.
+     *
+     * @param {string} photoMediaName
+     *   A fully-qualified path representing PhotoMedia resource.
+     * @returns {string} A string representing the place_id.
+     */
+    matchPlaceIdFromPhotoMediaName(photoMediaName: string): string | number;
+    /**
+     * Parse the photo_reference from PhotoMedia resource.
+     *
+     * @param {string} photoMediaName
+     *   A fully-qualified path representing PhotoMedia resource.
+     * @returns {string} A string representing the photo_reference.
+     */
+    matchPhotoReferenceFromPhotoMediaName(photoMediaName: string): string | number;
+    /**
+     * Return a fully-qualified place resource name string.
+     *
+     * @param {string} place_id
+     * @returns {string} Resource name string.
+     */
+    placePath(placeId: string): string;
+    /**
+     * Parse the place_id from Place resource.
+     *
+     * @param {string} placeName
+     *   A fully-qualified path representing Place resource.
+     * @returns {string} A string representing the place_id.
+     */
+    matchPlaceIdFromPlaceName(placeName: string): string | number;
+    /**
+     * Return a fully-qualified review resource name string.
+     *
+     * @param {string} place
+     * @param {string} review
+     * @returns {string} Resource name string.
+     */
+    reviewPath(place: string, review: string): string;
+    /**
+     * Parse the place from Review resource.
+     *
+     * @param {string} reviewName
+     *   A fully-qualified path representing Review resource.
+     * @returns {string} A string representing the place.
+     */
+    matchPlaceFromReviewName(reviewName: string): string | number;
+    /**
+     * Parse the review from Review resource.
+     *
+     * @param {string} reviewName
+     *   A fully-qualified path representing Review resource.
+     * @returns {string} A string representing the review.
+     */
+    matchReviewFromReviewName(reviewName: string): string | number;
     /**
      * Terminate the gRPC channel and close the client.
      *