Nearby Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

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

Una solicitud de Nearby Search (nuevo) toma como entrada la región de búsqueda especificada como un círculo, definida 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 todos los tipos dentro del área de búsqueda. De manera opcional, puedes filtrar la respuesta especificando una lista de tipos de lugares para incluir o excluir explícitamente de la respuesta. Por ejemplo, puedes especificar que, en la respuesta, se incluyan solo los lugares del tipo "restaurante", "panadería" y "cafetería", o bien que se excluyan todos los lugares del tipo "escuela".

Solicitudes de Nearby Search (nuevo)

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

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

• La lista de campos que se mostrarán en el objeto GMSPlace, también llamada máscara de campo, según se define en GMSPlaceProperty. Si no especificas al menos un campo de la lista 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 esta solicitud de búsqueda cercana de ejemplo, se especifica que los objetos GMSPlace de respuesta contienen el nombre del lugar (GMSPlacePropertyName) y las coordenadas de lugar (GMSPlacePropertyCoordinate) de 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;
    }
  }
];

GooglePlacesSwift

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.

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

Junto con los campos de datos, el objeto GMSPlace en la respuesta contiene las siguientes funciones de miembro:

• isOpen calcula si un lugar está abierto en un momento determinado.
• isOpenAtDate calcula si un lugar está abierto en una fecha determinada.

Nota: Estas funciones solo están disponibles cuando habilitas el SDK de Places para iOS. No están disponibles cuando habilitas el SDK de Places para iOS (nuevo). Para obtener más información, consulta Elige tu versión del SDK.

Parámetros obligatorios

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

• Lista de campos

  Cuando solicitas Place Details, 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 campo 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 innecesarios.

  Especifica uno o más de los siguientes campos:

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

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

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

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

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

    GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine y 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];
          

  GooglePlacesSwift

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

• locationRestriction

  Es un objeto GMSPlaceLocationRestriction que define la región en la que se buscará especificada como un círculo, que se define por el punto central y el radio en metros. El radio debe ser de entre 0.0 y 50,000.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 para la búsqueda.

• includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

  Te permite especificar una lista de tipos de los 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.

  Nota: Los valores de la Tabla B solo se muestran en la respuesta. No puedes usar los valores de la Tabla B como filtro.

  Un lugar solo puede tener un tipo principal asociado a los tipos de la Tabla A. Por ejemplo, el tipo principal podría ser "mexican_restaurant" o "steak_house". Utiliza 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 tipos de la Tabla A asociados. Por ejemplo, un restaurante podría tener los siguientes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest" y "establishment". Utiliza includedTypes y excludedTypes para filtrar los resultados en la lista de tipos asociados con un lugar.

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

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

  includedTypes

  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

  Lista de tipos de lugares de la Tabla A que se deben excluir de una búsqueda.

  Si especificas el includedTypes (como "school") y el 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 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

  Lista de tipos de lugares principales de la Tabla A que se deben incluir en una búsqueda.

  excludedPrimaryTypes

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

  Si hay tipos principales 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 ser un valor entre 1 y 20 (predeterminado) inclusive.

• rankPreference

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

  • .popularity (predeterminado): Ordena los resultados según su popularidad.
  • .distance: Ordena los resultados en orden ascendente según su distancia desde la ubicación especificada.

• regionCode

  El código regional 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 regionCode, el código de país se omite 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 de "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 del 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.