Nearby Search (nueva)

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 Place, 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 incluirla de forma explícita o excluir de ella. 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".

Nota: Nearby Search (nuevo) está disponible en el SDK de Places para Android 3.5.0 y versiones posteriores. Para obtener más información, consulta Cómo elegir tu versión del SDK.

Solicitudes de Nearby Search (nuevo)

Para realizar una solicitud de Nearby Search (nuevo), llama a PlacesClient.searchNearby y pasa un objeto SearchNearbyRequest que defina los parámetros de la solicitud.

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

• La lista de campos que se mostrarán en el objeto Place, que también se conoce como máscara de campo. Si no especificas al menos un campo de la lista o si omites la lista de campos, la llamada mostrará un error.
• Es la restricción de ubicación para el área de búsqueda, que se define como un par de latitud y longitud, y un valor de radio en metros.

Esta solicitud de búsqueda cercana de ejemplo especifica que los objetos Place de respuesta contienen los campos de lugar Place.Field.ID y Place.Field.NAME para cada objeto Place en los resultados de la búsqueda. También filtra la respuesta para mostrar solo lugares de tipo “restaurante” y “cafetería”, pero excluir lugares de tipo “pizza_restaurant” y “american_restaurant”.

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Puedes usar un CancellationToken para intentar cancelar una solicitud a cualquiera de las clases de solicitud (por ejemplo, FetchPlaceRequest). La cancelación se realiza sobre la base del mejor esfuerzo. Una vez que se envía una solicitud de cancelación, no se mostrará ninguna respuesta. Emitir un token de cancelación NO garantiza que se cancelará una solicitud en particular, y es posible que se te cobre por la solicitud incluso si no se muestra una respuesta.

Respuestas de Nearby Search (nuevo)

La clase SearchNearbyResponse representa la respuesta de una solicitud de búsqueda. Un objeto SearchNearbyResponse contiene lo siguiente:

• Es una lista de objetos Place que representan todos los lugares coincidentes, con un objeto Place por lugar coincidente.
• Cada objeto Place solo contiene los campos definidos por la lista de campos que se pasa en la solicitud.

Por ejemplo, en la solicitud definiste una lista de campos de la siguiente manera:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

Esta lista de campos indica que cada objeto Place de la respuesta contiene solo el ID de lugar y el nombre de cada lugar coincidente. Luego, puedes usar los métodos Place.getId() y Place.getName() para acceder a estos campos en cada objeto Place.

Para obtener más ejemplos sobre cómo acceder a los datos de un objeto Place, consulta Cómo acceder a los campos de datos de objetos de Place.

Parámetros obligatorios

Usa el objeto SearchNearbyRequest para especificar los parámetros que se requieren para la búsqueda.

• Lista de campos

  Cuando solicitas Place Details, debes especificar los datos que se mostrarán en el objeto Place del lugar como una máscara de campo. Para definir la máscara de campo, pasa un array de valores de Place.Field al objeto SearchNearbyRequest. 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):

    Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT y Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL y Place.Field.WEBSITE_URI

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

    Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE y Place.Field.TAKEOUT

  Para establecer el parámetro de lista de campos, llama al método setPlaceFields() cuando compiles el objeto SearchNearbyRequest.

  En el siguiente ejemplo, se define una lista de dos valores de campo para especificar que el objeto Place que muestra una solicitud contenga los campos Place.Field.ID y Place.Field.NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

• Restricción de ubicación

  Es un objeto LocationRestriction 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 mayor que 0.0 y menor o igual que 50,000.0. Ten en cuenta que, si especificas un radio demasiado pequeño, se mostrará ZERO_RESULTS como respuesta.

  Para establecer el parámetro de restricción de ubicación, llama al método setLocationRestriction() cuando compiles el objeto SearchNearbyRequest.

Parámetros opcionales

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

• Tipos y tipos principales

  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 = Arrays.asList("restaurant") y excludedPrimaryTypes = Arrays.asList("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.

  Para ver un ejemplo de cómo usar includedTypes y excludedTypes, consulta Solicitudes de Nearby Search (nuevas).

  Tipos incluidos

  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.

  Para establecer el parámetro de tipos incluidos, llama al método setIncludedTypes() cuando compiles el objeto SearchNearbyRequest.

  Tipos excluidos

  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.

  Para establecer el parámetro de tipos excluidos, llama al método setExcludedTypes() cuando compiles el objeto SearchNearbyRequest.

  Tipos principales incluidos

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

  Para establecer el parámetro de tipos principales incluidos, llama al método setIncludedPrimaryTypes() cuando compiles el objeto SearchNearbyRequest.

  Tipos principales excluidos

  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.

  Para establecer el parámetro de tipos principales excluidos, llama al método setExcludedPrimaryTypes() cuando compiles el objeto SearchNearbyRequest.

• Recuento máximo de resultados

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

  Para establecer el parámetro de recuento máximo de resultados, llama al método setMaxResultCount() cuando compiles el objeto SearchNearbyRequest.

• Preferencia de clasificación

  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.

  Para establecer el parámetro de preferencia de clasificación, llama al método setRankPreference() cuando compiles el objeto SearchNearbyRequest.

• Código de la región

  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.

  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.

  Para establecer el parámetro del código regional, llama al método setRegionCode() cuando compiles el objeto SearchNearbyRequest.

Mostrar atribuciones en tu aplicación

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

Para obtener más información, consulta Políticas del SDK de Places para Android.