Nearby Search (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web

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

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

Solicitudes de Nearby Search (nuevo)

Para realizar una solicitud de Búsqueda cercana, llama a GMSPlacesClient searchNearbyWithRequest: y pasa un objeto GMSPlaceSearchNearbyRequest que defina los parámetros de solicitud y un método de devolución de llamada, de tipo GMSPlaceSearchNearbyResultCallback, para controlar la respuesta.

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

  • Es la lista de campos que se mostrarán en el objeto GMSPlace, también llamada máscara de campo, como lo define GMSPlaceProperty. Si no especificas al menos un campo en la lista de campos o si omites la lista de campos, la llamada mostrará un error.
  • La restricción de ubicación, es decir, 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 la respuesta deben contener el nombre del lugar (GMSPlacePropertyName) y las coordenadas del lugar (GMSPlacePropertyCoordinate) para cada objeto GMSPlace en los resultados de la búsqueda. También filtra la respuesta para que solo muestre lugares de tipo "restaurante" y "cafetería".

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 forma de objetos GMSPlace, con un objeto GMSPlace por lugar coincidente.

Cómo obtener el estado de abierto

El objeto GMSPlacesClient contiene una función miembro llamada isOpenWithRequest (isOpenRequest en Swift y isPlaceOpenRequest en GooglePlacesSwift) que muestra una respuesta que indica si el lugar está abierto en el momento en que se realiza la llamada.

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

  • Un objeto GMSPlace o una cadena que especifique un ID de lugar Para obtener más información sobre cómo crear el objeto Place con los campos necesarios, consulta Detalles de Place.
  • Es un objeto NSDate (Obj-C) o Date (Swift) opcional que especifica la hora que deseas verificar. Si no se especifica una hora, la configuración predeterminada es la actual.
  • Un método GMSPlaceOpenStatusResponseCallback para controlar la respuesta.
    • >

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Si no se proporcionan estos campos 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 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 de isOpenWithRequest

  • Los campos GMSPlacePropertyUTCOffsetMinutes y GMSPlacePropertyBusinessStatus se cobran en el SKU de Basic Data. El resto de los horarios de apertura se cobra con el SKU de Place Details Enterprise.
  • Si tu objeto GMSPlace ya tiene estos campos de una solicitud anterior, no se te volverá a cobrar.

Ejemplo: Realiza una solicitud GMSPlaceIsOpenWithRequest

En el siguiente ejemplo, se muestra cómo inicializar un 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 de un lugar, debes especificar los datos que se mostrarán en el objeto GMSPlace del lugar como una máscara de campo. Para definir la máscara de campo, pasa un array de valores de GMSPlaceProperty al objeto GMSPlaceSearchNearbyRequest. El enmascaramiento de campos es una práctica de diseño recomendada para garantizar que no solicites datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos de facturación adicionales.

    Especifica uno o más de los siguientes campos:

    • Los siguientes campos activan el SKU de Nearby Search Pro:

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

    • Los siguientes campos activan el SKU de Nearby Search Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Los siguientes campos activan el SKU de Enterprise Plus de Nearby Search:

      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 los 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 de búsqueda especificada como un círculo, definido por el punto central y el radio en metros. El radio debe estar entre 0.0 y 50000.0, inclusive. El radio predeterminado es 0.0. Debes establecerlo en tu solicitud en un valor superior a 0.0.

Parámetros opcionales

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

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

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

    Un lugar también puede tener varios valores de tipo de los tipos de la Tabla A asociados con él. Por ejemplo, un restaurante podría tener los siguientes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest" y "establishment". Usa includedTypes y excludedTypes para filtrar los resultados de 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, especificas que se incluya un tipo principal de "restaurant". Luego, la respuesta puede contener lugares con un tipo principal de "restaurant", pero también puede contener lugares con un tipo principal más específico, como "chinese_restaurant" o "seafood_restaurant".

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

    includedTypes

    Es una lista de los tipos de lugares de la Tabla A que se deben buscar. Si se omite este parámetro, se muestran lugares de todos los tipos.

    excludedTypes

    Es una lista de los tipos de lugares de la Tabla A que se excluirán de una búsqueda.

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

    Si hay algún tipo en conflicto, como un tipo que aparece en includedTypes y excludedTypes, se muestra un error INVALID_REQUEST.

    includedPrimaryTypes

    Es una lista de los tipos de lugares principales de la Tabla A que se incluyen en una búsqueda.

    excludedPrimaryTypes

    Es una lista de los tipos de lugares principales de la Tabla A que se deben excluir de una búsqueda.

    Si hay algún tipo principal en conflicto, como un tipo que aparece en includedPrimaryTypes y excludedPrimaryTypes, se muestra un error INVALID_ARGUMENT.

  • maxResultCount

    Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe estar comprendido entre 1 y 20 (valor predeterminado) inclusive.

  • rankPreference

    Es 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 (predeterminada): Ordena los resultados según su popularidad.
    • .distance Ordena los resultados en orden ascendente según su distancia desde la ubicación especificada.

  • regionCode

    Es el código de región que se usa para dar formato a la respuesta, especificado como un 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, se omite el código de país de formattedAddress. Este parámetro no tiene efecto en adrFormatAddress, que siempre incluye el nombre del país, ni en shortFormattedAddress, que nunca lo incluye.

    La mayoría de los códigos CLDR son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es "uk" (.co.uk), mientras que su código ISO 3166-1 es "gb" (técnicamente, para la entidad "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

Cuando tu app muestra información obtenida de GMSPlacesClient, como fotos y opiniones, también debe mostrar las atribuciones requeridas.

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

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