Nearby Search (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Desarrolladores del Espacio Económico Europeo (EEE)

Si tu dirección de facturación se encuentra en el Espacio Económico Europeo, a partir del 8 de julio de 2025, se aplicarán las Condiciones del Servicio del EEE de Google Maps Platform al uso que hagas de los Servicios. La funcionalidad varía según la región. Obtén más información.

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 devuelve 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 lugar para incluir o excluir explícitamente de la respuesta. Por ejemplo, puedes especificar que solo se incluyan en la respuesta los lugares de tipo "restaurante", "panadería" y "cafetería", o bien excluir todos los lugares de tipo "escuela".

Nota: La función Nearby Search (nuevo) está disponible en la versión 3.5.0 y posteriores del SDK de Places para Android. Para obtener más información, consulta Elige tu versión del SDK. Para obtener más información sobre el uso de las APIs de Kotlin agregadas en la versión 4.0.0, consulta la Descripción general de referencia.

Solicitudes de Nearby Search (nuevo)

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

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

• Es la lista de campos que se devolverán en el objeto Place, también conocida 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 devolverá un error.
• Es 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 búsqueda cercana, se especifica que los objetos Place de la respuesta deben contener 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 mostrar solo 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();
    });

Nota: Para obtener más información sobre cómo inicializar PlacesClient, consulta Inicializa el cliente de la API de Places.

Puedes usar un CancellationToken para intentar cancelar una solicitud a cualquiera de las clases de solicitud (por ejemplo, FetchPlaceRequest). La cancelación se realiza según el criterio del mejor esfuerzo. Una vez que se emite una solicitud de cancelación, no se devolverá 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 devuelve ninguna 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 cada 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 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 significa que cada objeto Place de la respuesta contiene solo el ID 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 cómo acceder a los datos en un objeto Place, consulta Cómo acceder a los campos de datos del objeto Place.

Parámetros obligatorios

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

• Lista de campos

  Cuando solicitas detalles de un lugar, debes especificar los datos que se devolverá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 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 el SKU de Nearby Search Pro:

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * Úsalo en lugar de Place.Field.NAME, que dejó de estar disponible.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * Úsalo en lugar de Place.Field.ICON_URL, que está obsoleto.
    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

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

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * Úsalo en lugar de Place.Field.PHONE_NUMBER, que está obsoleto.
    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*
        * Úsalo en lugar de Place.Field.USER_RATINGS_TOTAL, que está obsoleto.
    Place.Field.WEBSITE_URI

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

    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
  Nota: En la versión 4.0 del SDK de Places para Android, se introdujo la baja de varios campos de datos de Place y la adición de campos nuevos. Para obtener más información, consulta Migra a los nuevos campos de datos de Place en el SDK de Places para Android 4.0 .

  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 devuelve 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

  Objeto LocationRestriction 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 ser mayor que 0.0 y menor o igual que 50000.0. Ten en cuenta que, si especificas un radio demasiado pequeño, se devolverá 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 de la búsqueda.

• Tipos y tipos principales

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

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

  Un lugar solo puede tener un solo tipo principal de los tipos de la Tabla A asociados a é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 a él. 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 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 que se especificó. 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 devuelven los lugares que satisfacen todas las restricciones. Por ejemplo, si especificas includedTypes = Arrays.asList("restaurant") y excludedPrimaryTypes = Arrays.asList("steak_house"), los lugares devueltos 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 devolverá lugares de 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 las solicitudes de Nearby Search (nuevo).

  Tipos incluidos

  Es una lista de los tipos de lugar de la Tabla A que se deben buscar. Si se omite este parámetro, se devuelven 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

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

  Si especificas tanto includedTypes (como "school") como 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 tipos en conflicto, como un tipo que aparece en includedTypes y excludedTypes, se devuelve 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

  Es una lista de los tipos de lugar principales de la Tabla A que se incluirán 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

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

  Si hay tipos principales en conflicto, como un tipo que aparece en includedPrimaryTypes y excludedPrimaryTypes, se devuelve un error de 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 devolverán. Debe estar entre 1 y 20 (valor predeterminado), ambos incluidos.

  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

  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 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

  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 de 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 legislación aplicable.

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

Mostrar atribuciones en tu aplicación

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

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