Nearby Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Esta función requiere que habilites API de Places (nueva), la nueva generación de la API de Places. Para obtener más información, consulta Habilita las APIs.

Una solicitud de Nearby Search (nueva) toma como entrada la región que se buscará especificado como círculo, definido por las coordenadas de latitud y longitud del punto central de la y el radio en metros. La solicitud devuelve una lista de los lugares coincidentes, cada uno de ellos representado por un GMSPlace dentro del área de búsqueda especificada.

De forma predeterminada, la respuesta contiene lugares de todo tipo dentro del área de búsqueda. Opcionalmente, puedes filtrar la respuesta especificando una lista de tipos de lugares que se incluirán o excluirán de forma explícita respuesta. Por ejemplo, puedes especificar que se incluyan solo los lugares de la respuesta que son de tipo. "restaurante", "panadería" y "cafetería", o bien excluir todos los lugares del tipo "escuela".

Solicitudes de Nearby Search (nuevo)

Llamada para hacer una solicitud de Nearby Search GMSPlacesClient searchNearbyWithRequest:: pasar un GMSPlaceSearchNearbyRequest que define los parámetros de la solicitud y un método de devolución de llamada, del tipo GMSPlaceSearchNearbyResultCallback para manejar la respuesta.

El objeto GMSPlaceSearchNearbyRequest especifica todos los obligatorio y opcional parámetros para la solicitud. Entre los parámetros obligatorios, se incluyen los siguientes:

• La lista de campos que se debe mostrar en el objeto GMSPlace, también llamado máscara de campo, como lo define GMSPlaceProperty Si no especificas al menos un campo en la lista de campos la lista de campos, entonces la llamada devuelve un error.
• La restricción de ubicación, que significa el círculo que define el área de búsqueda.

En este ejemplo de solicitud de búsqueda cercana, se especifica que los objetos GMSPlace de respuesta contienen el nombre del lugar (GMSPlacePropertyName) y las coordenadas del lugar (GMSPlacePropertyCoordinate) para cada objeto GMSPlace en la búsqueda resultados. También filtra la respuesta para que solo se muestren lugares del tipo “restaurante”. y "cafe".

Swift

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

Objective-C

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

SDK de Places Swift para iOS (versión preliminar)

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Respuestas de Nearby Search

La API de Nearby Search muestra un array de coincidencias en la forma de GMSPlace objetos, con un objeto GMSPlace por cada lugar coincidente.

Nota: Campos del objeto GMSPlace de respuesta no puede estar vacío. Por ejemplo, si la lista de campos incluye GMSPlacePropertyPhotos para solicita el campo photos en la respuesta y el campo photos en la respuesta está vacío, se omite del objeto GMSPlace de respuesta.

Obtener estado de apertura

El objeto GMSPlacesClient contiene una función de miembro llamada isOpenWithRequest (isOpenRequest en Swift y isPlaceOpenRequest en GooglePlacesSwift) que muestra una respuesta que indica si el lugar está abierto en ese momento, según el horario especificado en la llamada.

Nota: Es posible que las funciones GMSPlace isOpen: y GMSPlace isOpenAtDate: obsoletas no sean precisas y no estén diseñadas para usarse con la API de Places (versión nueva).

Este método toma un solo argumento de tipo GMSPlaceIsOpenWithRequest que contiene lo siguiente:

• Un objeto GMSPlace o una cadena que especifica un ID de lugar Para obtener más información sobre cómo crear el objeto Place con los campos necesarios, consulta Detalles del lugar.
  
  Nota: El objeto Place debe contener un ID de lugar válido.
• Un objeto NSDate (Obj-C) o Date (Swift) opcional que especifique la hora que deseas verificar. Si no se especifica la hora, el valor predeterminado será ahora.
• Un método GMSPlaceOpenStatusResponseCallback para controlar la respuesta
>

El método GMSPlaceIsOpenWithRequest requiere que se configuren los siguientes campos en el objeto GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

Si estos campos no se proporcionan en el objeto Place o si pasas un ID de lugar, el método usa GMSPlacesClient GMSFetchPlaceRequest: para recuperarlos.

isOpenWithRequest respuesta

isOpenWithRequest muestra un objeto GMSPlaceIsOpenResponse que contiene un valor booleano llamado status que indica si la empresa está abierta, cerrada o si el estado es desconocido.

Idioma	Valor si está abierto	Valor si el sitio está cerrado	Valor si el estado es desconocido
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown
GooglePlacesSwift (versión preliminar)	true	false	nil

Facturación para isOpenWithRequest

• Los campos GMSPlacePropertyUTCOffsetMinutes y GMSPlacePropertyBusinessStatus se cobran según el SKU de Basic Data. El resto del horario de atención se cobra en el SKU de Place Details (Advanced).
• Si tu objeto GMSPlace ya tiene estos campos de una solicitud anterior, no se te volverá a cobrar.
• Advertencia Si tu objeto GMSPlace no contiene estos campos, se te cobrará nuevamente por el SKU de Basic Data. El resto del horario de atención se cobra en el SKU de Place Details (Advanced). Si tu proyecto usará isOpenWithRequest, te recomendamos que te asegures de recuperar los detalles necesarios del lugar.

Ejemplo: Realiza una solicitud GMSPlaceIsOpenWithRequest

En el siguiente ejemplo, se muestra cómo inicializar un elemento GMSPlaceIsOpenWithRequest dentro de un objeto GMSPlace existente.

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

GooglePlacesSwift

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

Parámetros obligatorios

Usa el objeto GMSPlaceSearchNearbyRequest para especificar los parámetros obligatorios para la búsqueda.

• Lista de campos

  Cuando solicitas detalles del lugar, debes especificar los datos para Se devuelve en el objeto GMSPlace del lugar como una máscara de campo. Para definir pasa un array de valores desde GMSPlaceProperty al objeto GMSPlaceSearchNearbyRequest. El enmascaramiento de campo es una buena práctica de diseño para garantizar que no solicites datos innecesarios lo que ayuda a evitar tiempos de procesamiento y cargos de facturación innecesarios.

  Especifica uno o más de los siguientes campos:

  • Los siguientes campos activan la SKU de Nearby Search (Basic):

    GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyCoordinate, GMSPlacePropertyFormattedAddress, GMSPlacePropertyName, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyPhotos, GMSPlacePropertyPlaceID, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, GMSPlacePropertyWheelchairAccessibleEntrance

  • Los siguientes campos activan la SKU de Nearby Search (Advanced):

    GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

  • Los siguientes campos activan la SKU de Nearby Search (Preferred):

    GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

  En el siguiente ejemplo, se pasa una lista de dos valores de campo para especificar que el objeto GMSPlace que muestra una solicitud contiene el Campos name y placeID:

  Swift

  // Specify the place data types to return.
  let fields: [GMSPlaceProperty] = [.placeID, .name]
          

  Objective-C

  // Specify the place data types to return.
  NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
          

  SDK de Places Swift para iOS (versión preliminar)

  // Specify the place data types to return.
  let fields: [PlaceProperty] = [.placeID, .displayName]
          

• locationRestriction

  Un objeto GMSPlaceLocationRestriction que define la región a buscar especificada como un círculo, definida por el punto central y radio en metros. El radio debe ser de entre 0.0 y 50,000.0, inclusive. El radio predeterminado es 0.0 Debes configurarlo en un valor superior a 0.0 en la solicitud.

Parámetros opcionales

Usa el objeto GMSPlaceSearchNearbyRequest para especificar los parámetros opcionales de la búsqueda.

• includeTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

  Te permite especificar una lista de tipos de tipos Se usa la Tabla A para filtrar los resultados de la búsqueda. Se pueden especificar hasta 50 tipos en cada categoría de restricción de tipos.

  Nota: Los valores en Tabla B solo se devuelven en la respuesta. No puedes usar valores en Tabla B como un filtro.

  Un lugar solo puede tener un único tipo principal de los tipos Tabla A asociada con que la modifica. Por ejemplo, el tipo principal podría ser "mexican_restaurant" o "steak_house". Usa includedPrimaryTypes y excludedPrimaryTypes para filtrar los resultados el tipo principal de un lugar.

  Un lugar también puede tener varios valores de tipo de tipos Tabla A asociados con ella. Por ejemplo, un restaurante puede tener los siguientes tipos: "seafood_restaurant", "restaurant" y "food" "point_of_interest", "establishment". Usar includedTypes y excludedTypes para filtrar los resultados en la lista de tipos asociados con un lugar.

  Cuando especificas un tipo principal general, como "restaurant" o "hotel", la respuesta puede contener lugares con un tipo principal más específico que el especificado. Por ejemplo, puedes especificar que se incluya un tipo principal de "restaurant" La respuesta puede contener sitios con un tipo principal de "restaurant", pero la respuesta también puede contener lugares con un tipo principal, como "chinese_restaurant" o "seafood_restaurant".

  Si se especifica una búsqueda con varias restricciones de tipo, solo los lugares que satisfagan todas las restricciones. Por ejemplo, si especificas {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, el Los lugares que se muestran proporcionan servicios relacionados con "restaurant", pero no operan principalmente como "steak_house".

  Si omites includedTypes, excludedTypes, includedPrimaryTypes y excludedPrimaryTypes de la solicitud, la búsqueda devuelve lugares para todos los tipos dentro de los límites de la restricción de ubicación.

  includedTypes

  Una lista de los tipos de lugares de Tabla A para buscar. Si se omite este parámetro, se devuelven lugares de todos los tipos.

  excludedTypes

  Una lista de los tipos de lugares de Tabla A para excluir de un búsqueda.

  Si especificas tanto includedTypes (como "school") como excludedTypes (como "primary_school") en la solicitud y, luego, el incluye lugares categorizados como "school", pero no como "primary_school" La respuesta incluye lugares que coinciden con al menos uno de el includedTypes y ninguno de los excludedTypes.

  Si hay tipos en conflicto, como uno que aparezca en includedTypes y excludedTypes, se muestra un error INVALID_REQUEST.

  includedPrimaryTypes

  Una lista de los tipos de lugares principales de Tabla A que se debe incluir en una búsqueda.

  excludedPrimaryTypes

  Una lista de los tipos de lugares principales de Tabla A para excluir de una búsqueda.

  Si hay tipos principales en conflicto, como uno que aparezca en ambos includedPrimaryTypes y excludedPrimaryTypes, un Se muestra el error INVALID_ARGUMENT.

• maxResultCount

  Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe ser un valor entre 1 y 20 (predeterminado), ambos incluidos.

• rankPreference

  El tipo de clasificación que se usará. Si se omite este parámetro, los resultados se clasifican por popularidad. Puede ser una de las siguientes opciones:

  • .popularity (predeterminado) ordena los resultados según su popularidad.
  • .distance ordena los resultados en forma ascendente por su distancia desde la ubicación especificada.

• regionCode

  El código de región que se usa para dar formato a la respuesta, especificado como una valor de código CLDR de dos caracteres. No hay un valor predeterminado.

  Si el nombre del país del campo formattedAddress en la respuesta coincide con el regionCode, el código de país se omite de formattedAddress. Este parámetro no tiene efecto en adrFormatAddress, que siempre incluye el país. nombre o en shortFormattedAddress, que nunca lo incluye.

  La mayoría de los códigos CLDR son idénticos a códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es “uk” (.co.uk), mientras que el código ISO 3166-1 es "gb" (técnicamente para el del "Reino Unido de Gran Bretaña e Irlanda del Norte"). El parámetro puede afectar los resultados según la ley aplicable.

Mostrar atribuciones en tu aplicación

Cuándo muestra la app información obtenida de GMSPlacesClient: como fotos y opiniones, la app también debe mostrar las atribuciones requeridas.

Por ejemplo, la propiedad reviews del objeto GMSPlacesClient contiene un array de hasta cinco GMSPlaceReview objetos. Cada objeto GMSPlaceReview puede contener atribuciones y atribuciones de autor. Si muestra la opinión en su aplicación, también debe mostrar cualquier atribución o autor atribución.

Para obtener más información, consulta la documentación sobre atribuciones.