Nearby Search (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Desarrolladores del Espacio Económico Europeo (EEE)

Una solicitud de Nearby Search (nuevo) toma como entrada la región en la que se realizará la 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 Place objeto, 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 se incluyan solo aquellos lugares en la respuesta que sean de tipo "restaurante", "panadería" y "cafetería", o excluir todos los lugares de tipo "escuela".

Solicitudes de Nearby Search (nuevo)

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

El objeto SearchNearbyRequest 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 Place, que también se conoce como máscara de campo. Si no especificas al menos un campo en la lista de campos o si omites la lista de campos, la llamada muestra un error.
  • La restricción de ubicación para el área de búsqueda, definida como un par de latitud y longitud, y un valor de radio, en metros.

En este ejemplo de solicitud de Nearby Search, se especifica que los objetos Place de la respuesta contengan los campos de lugar Place.Field.ID y Place.Field.DISPLAY_NAME para cada objeto Place en los resultados de la búsqueda. También filtra la respuesta para que solo muestre lugares de tipo "restaurante" y "cafetería", pero excluye los lugares de tipo "pizzería" y "restaurante estadounidense".

// 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.DISPLAY_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();
    });

Respuestas de Nearby Search (nuevo)

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

  • 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 pasó en la solicitud.

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

// 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 significa 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 de acceso a datos en un objeto Place, consulta Accede a los campos de datos del objeto Place.

Parámetros obligatorios

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

  • Lista de campos

    Cuando solicitas detalles de lugares, debes especificar los datos que se mostrarán en el objeto Place para el 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 uso de campos enmascarados 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 la SKU de Nearby Search Pro:

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
          * Usa en lugar de Place.Field.NAME, que dejó de estar disponible.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * Usa en lugar de Place.Field.ICON_URL, que dejó de estar disponible.
      Place.Field.ID
      Place.Field.LAT_LNG
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.RESOURCE_NAME
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT
      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

      Para obtener una lista completa de los campos y sus SKUs asociadas, consulta Campos de datos de lugares (nuevo).

    • Los siguientes campos activan la Nearby Search Enterprise SKU:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Usa en lugar de Place.Field.PHONE_NUMBER, que dejó de estar disponible.
      Place.Field.NATIONAL_PHONE_NUMBER
      Place.Field.OPENING_HOURS
      Place.Field.PRICE_LEVEL
      Place.Field.RATING
      Place.Field.SECONDARY_OPENING_HOURS
      Place.Field.USER_RATING_COUNT*
          * Usa en lugar de Place.Field.USER_RATINGS_TOTAL, que dejó de estar disponible.
      Place.Field.WEBSITE_URI

      Para obtener una lista completa de los campos y sus SKUs asociadas, consulta Campos de datos de lugares (nuevo).

    • Los siguientes campos activan la Nearby Search Enterprise Plus SKU:

      Place.Field.ALLOWS_DOGS
      Place.Field.CURBSIDE_PICKUP
      Place.Field.DELIVERY
      Place.Field.DINE_IN
      Place.Field.EDITORIAL_SUMMARY
      Place.Field.EV_CHARGE_OPTIONS
      Place.Field.FUEL_OPTIONS
      Place.Field.GOOD_FOR_CHILDREN
      Place.Field.GOOD_FOR_GROUPS
      Place.Field.GOOD_FOR_WATCHING_SPORTS
      Place.Field.LIVE_MUSIC
      Place.Field.MENU_FOR_CHILDREN
      Place.Field.OUTDOOR_SEATING
      Place.Field.PARKING_OPTIONS
      Place.Field.PAYMENT_OPTIONS
      Place.Field.RESERVABLE
      Place.Field.RESTROOM
      Place.Field.REVIEWS
      Place.Field.SERVES_BEER
      Place.Field.SERVES_BREAKFAST
      Place.Field.SERVES_BRUNCH
      Place.Field.SERVES_COCKTAILS
      Place.Field.SERVES_COFFEE
      Place.Field.SERVES_DESSERT
      Place.Field.SERVES_DINNER
      Place.Field.SERVES_LUNCH
      Place.Field.SERVES_VEGETARIAN_FOOD
      Place.Field.SERVES_WINE
      Place.Field.TAKEOUT

      Para obtener una lista completa de los campos y sus SKUs asociadas, consulta Campos de datos de lugares (nuevo).

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

    En el siguiente ejemplo, se define una lista de dos valores de campo para especificar que el Place objeto que muestra una solicitud contiene los campos Place.Field.ID y Place.Field.DISPLAY_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.DISPLAY_NAME);

  • Restricción de ubicación

    Un LocationRestriction objeto que define la región en la que se realizará la búsqueda, especificada como un círculo, definido por el punto central y el radio en metros. El radio debe ser mayor que 0.0 y menor o igual que 50000.0. Ten en cuenta que, si especificas un radio demasiado pequeño, se mostrará ZERO_RESULTS como respuesta.

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

Parámetros opcionales

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

  • Tipos y tipos principales

    Te permite especificar una lista de tipos de tipos Tabla A que se usa 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 único tipo principal de tipos Tabla A asociado 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 tipos Tabla A asociados. Por ejemplo, un restaurante podría tener los siguientes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Usa includedTypes y excludedTypes para filtrar los resultados según la lista de tipos asociados a 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". La respuesta puede contener lugares con un tipo principal de "restaurant", pero la respuesta 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 = Arrays.asList("restaurant") y excludedPrimaryTypes = Arrays.asList("steak_house"), los lugares que se muestran proporcionan servicios relacionados con "restaurant" pero no operan principalmente como un "steak_house".

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

    Tipos incluidos

    Es una lista de los tipos de lugares de la Tabla A en los que se realizará la búsqueda. Si se omite este parámetro, se muestran lugares de todos los tipos.

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

    Tipos excluidos

    Es una lista de 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 incluye lugares que se clasifican 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.

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

    Tipos principales incluidos

    Es una lista de tipos de lugares principales de la Tabla A que se incluirán en una búsqueda.

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

    Tipos principales excluidos

    Es una lista de tipos de lugares principales de la Tabla A que se excluirán 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.

    Para configurar 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 estar entre 1 y 20 (predeterminado) inclusive.

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

  • Preferencia de clasificación

    Es 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 configurar el parámetro de preferencia de clasificación, llama al método setRankPreference() cuando compiles el objeto SearchNearbyRequest.

  • Código de la región

    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 FORMATTED_ADDRESS en la respuesta coincide con regionCode, se omite el código de país de FORMATTED_ADDRESS.

    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 "El Reino Unido de Gran Bretaña e Irlanda del Norte"). El parámetro puede afectar los resultados según la ley aplicable.

    Para configurar el parámetro de código de región, llama al setRegionCode() método cuando compiles el SearchNearbyRequest objeto.

Mostrar atribuciones en tu aplicación

Cuando tu aplicación 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.