Text Search (nueva)

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 de Google Maps Platform para el EEE al uso que hagas de los Servicios. La funcionalidad varía según la región. Obtén más información.

Text Search (nueva) muestra información sobre un conjunto de lugares en función de una cadena; por ejemplo, "pizza en Buenos Aires", "tiendas de zapatos cerca de Santiago" o "Calle principal 123". El servicio responde con una lista de lugares que coinciden con la cadena de texto y con cualquier personalización de ubicación que se haya establecido.

Además de los parámetros obligatorios, Text Search (nueva) admite el refinamiento de las consultas con parámetros opcionales para obtener mejores resultados.

Text Search (nueva) es similar a Nearby Search (nueva). La principal diferencia entre ambas es que Text Search (nueva) te permite especificar una cadena de búsqueda arbitraria, mientras que Nearby Search (nueva) requiere un área específica en la que se realizará la búsqueda.

Nota: Text Search (nueva) está disponible en el SDK de Places para Android versión 3.3.0 y posteriores. 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 la referencia.

Solicitudes de Text Search

Nota: Text Search forma parte del SDK de Places para Android (nuevo) y no está disponible en el SDK de Places para Android.

Una solicitud de Text Search tiene el siguiente formato:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

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

En este ejemplo, haces lo siguiente:

• Configuras la lista de campos para incluir solo Place.Field.ID y Place.Field.DISPLAY_NAME. Eso significa que los objetos Place de la respuesta que representan cada lugar coincidente solo contienen esos dos campos.

• Usa SearchByTextRequest.Builder para crear un SearchByTextRequest objeto que define la búsqueda.

  • Configuras la cadena de consulta de texto en "Spicy Vegetarian Food".

  • Estableces la cantidad máxima de lugares de resultados en 10. El valor predeterminado y el máximo es 20.

  • Restringes el área de búsqueda al rectángulo definido por las coordenadas de latitud y longitud. No se muestran coincidencias fuera de esta área.

• Agregas un OnSuccessListener y obtienes los lugares coincidentes del SearchByTextResponse objeto.

Nota: Para obtener más información sobre la inicialización de 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 de la mejor manera posible. Una vez que se emite 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 ninguna respuesta.

Respuestas de Text Search

La SearchByTextResponse clase representa la respuesta de una solicitud de búsqueda. Un objeto SearchByTextResponse 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:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

Esta lista de campos significa que cada objeto Place de la respuesta contiene solo el ID del 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

Paginación

La clase SearchByTextResponse de Text Search proporciona acceso a la paginación de los resultados de la búsqueda de texto a través de su método getPagination(), que muestra un objeto Pagination.

Usa el método hasNextPage() del objeto Pagination para determinar si hay páginas de resultados adicionales disponibles. Este método devuelve un valor booleano (verdadero o falso).

Mientras hasNextPage() muestre verdadero, llama al método fetchNextPage() para recuperar la siguiente página de resultados.

En el siguiente ejemplo, se muestra cómo verificar si hay una página siguiente disponible y, luego, cargarla.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

Parámetros obligatorios

Los parámetros obligatorios para SearchByTextRequest son los siguientes:

• Lista de campos

  Especifica qué campos de datos de lugar deseas que se completen. Pasa una lista de Place.Field valores que especifiquen los campos de datos que se devolverán. No hay una lista predeterminada de campos devueltos en la respuesta.

  Las listas de campos son una buena práctica de diseño 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 Text Search Essentials (solo ID):

    Place.Field.DISPLAY_NAME*
        * Usa en lugar de Place.Field.NAME (obsoleto en la versión 4.0).
    Place.Field.ID
Place.Field.RESOURCE_NAME*
        * Contiene el nombre de recurso del lugar expresado de la siguiente forma: places/PLACE_ID.
    Utiliza DISPLAY_NAME para acceder al nombre del lugar en forma de texto.

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

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

    Place.Field.ACCESSIBILITY_OPTIONS*
        Usa en lugar de Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (obsoleto).
    Place.Field.ADDRESS_COMPONENTS
Place.Field.ADR_FORMAT_ADDRESS
Place.Field.BUSINESS_STATUS
Place.Field.FORMATTED_ADDRESS*
        Usa en lugar de Place.Field.ADDRESS (obsoleto).
    Place.Field.GOOGLE_MAPS_URI
Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL *
        Usa en lugar de Place.Field.ICON_URL (obsoleto).
    Place.Field.LOCATION*
        Usa en lugar de Place.Field.LAT_LNG (obsoleto).
    Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.SHORT_FORMATTED_ADDRESS
Place.Field.SUB_DESTINATIONS
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT

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

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

    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 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*
        * Usa en lugar de Place.Field.USER_RATINGS_TOTAL, que está obsoleto.
    Place.Field.WEBSITE_URI

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

  • Los siguientes campos activan el SKU de Text 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

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

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

• Consulta de texto

  Es la cadena de texto en la que se busca, por ejemplo, "restaurante", "calle principal 123" o "mejor lugar para visitar en Buenos Aires". La API devuelve posibles coincidencias en función de esta cadena y ordena los resultados según la relevancia percibida.

  Para configurar el parámetro de consulta de texto, llama al método setTextQuery() cuando compiles el objeto SearchByTextRequest.

  Nota: Para obtener mejores resultados cuando realices búsquedas con un número de teléfono, incluye el código de país seguido de un espacio y configura el regionCode parámetro para que corresponda al código de país. Los formatos de números de teléfono varían según el país, y la API intenta mostrar un resultado para estos diferentes formatos. Para los números de teléfono válidos, la API de Places (nueva) admite el formato E.164. Los caracteres alfabéticos se convierten según la asignación del teclado E.161.

Parámetros opcionales

Usa el SearchByTextRequest objeto para especificar los parámetros opcionales de tu solicitud.

• Tipo incluido

  Restringe los resultados a los lugares que coinciden con el tipo especificado definido por Tabla A. Solo se puede especificar un tipo. Por ejemplo:

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Nota: Los valores de la Tabla B solo se muestran en la respuesta. No puedes usar valores de la Tabla B como filtro.

  Para configurar el parámetro de tipo incluido, llama al método setIncludedType() cuando compiles el objeto SearchByTextRequest.

• Personalización de ubicación

  Especifica un área para buscar. Esta ubicación sirve como personalización, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados fuera del área especificada.

  Puedes especificar la restricción de ubicación o la personalización de ubicación, pero no ambas. Piensa en la restricción de ubicación como la especificación de la región en la que deben estar los resultados, y en la personalización de ubicación como la especificación de la región en la que es probable que estén los resultados o cerca de ella. Ten en cuenta que, cuando usas la personalización de ubicación, los resultados aún pueden estar fuera del área especificada.

  Nota: Si omites la restricción de ubicación y la personalización de ubicación, la API usará la personalización de IP de forma predeterminada. Con la personalización de IP, la API usa la dirección IP del dispositivo para personalizar los resultados.
  Nota: El parámetro locationBias se puede anular si textQuery contiene una ubicación explícita, como Market in Barcelona. En este caso, se ignora locationBias.

  Especifica la región como un Viewport rectangular o como un círculo.

  • Un círculo se define por el punto central y el radio en metros. El radio debe estar entre 0.0 y 50000.0, inclusive. Por ejemplo:

    // Define latitude and longitude coordinates of the center of the search area.
    LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);
    
    // Use the builder to create a SearchByTextRequest object.
    // Set the radius of the search area to 500.0 meters.
    final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
      .setMaxResultCount(10)
      .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

  • Un rectángulo es un viewport de latitud y longitud, representado como dos puntos bajos y altos diagonalmente opuestos. El punto bajo marca la esquina suroeste del rectángulo, y el punto alto representa la esquina noreste del rectángulo.

    Un viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben estar entre -90 y 90 grados inclusive, y los límites de longitud deben estar entre -180 y 180 grados inclusive:

    • Si low = high, el viewport consta de ese punto único.
    • Si low.longitude > high.longitude, el rango de longitud se invierte (el viewport cruza la línea de longitud de 180 grados).
    • Si low.longitude = -180 grados y high.longitude = 180 grados, el viewport incluye todas las longitudes.
    • Si low.longitude = 180 grados y high.longitude = -180 grados, el rango de longitud está vacío.
    • Si low.latitude > high.latitude, el rango de latitud está vacío.

    Se deben completar los valores bajo y alto, y el cuadro representado no puede estar vacío. Un viewport vacío genera un error.

    Por ejemplo, de un viewport rectangular, consulta Solicitudes de Text Search.

    Para configurar el parámetro de personalización de ubicación, llama al método setLocationBias() cuando compiles el objeto SearchByTextRequest.

• Restricción de ubicación

  Especifica un área para buscar. No se muestran resultados fuera del área especificada. Especifica la región como un Viewport rectangular. Consulta la descripción de Personalización de ubicación para obtener información sobre cómo definir el Viewport.

  Puedes especificar la restricción de ubicación o la personalización de ubicación, pero no ambas. Piensa en la restricción de ubicación como la especificación de la región en la que deben estar los resultados, y en la personalización de ubicación como la especificación de la región en la que deben estar los resultados, pero pueden estar fuera del área.

  Nota: Si omites la restricción de ubicación y la personalización de ubicación, la API usará la personalización de IP de forma predeterminada. Con la personalización de IP, la API usa la dirección IP de el dispositivo para personalizar los resultados.

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

• 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), ambos valores incluidos.

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

• Calificación mínima

  Restringe los resultados solo a aquellos cuya calificación promedio de los usuarios sea mayor o igual que este límite. Los valores deben estar entre 0.0 y 5.0 (inclusive) en incrementos de 0.5. Por ejemplo: 0, 0.5, 1.0, ... , 5.0 inclusive. Los valores se redondean a 0.5. Por ejemplo, un valor de 0.6 elimina todos resultados con una calificación inferior a 1.0.

  Para configurar el parámetro de calificación mínima, llama al setMinRating() método cuando compiles el SearchByTextRequest objeto.

• Abierto ahora

  Si es true, muestra solo los lugares que están abiertos en el momento en que se envía la consulta. Si es false, muestra todas las empresas independientemente de su estado de apertura. Los lugares que no especifican los horarios de atención en la base de datos de Google Places se muestran si configuras este parámetro como false.

  Para configurar el parámetro de abierto ahora, llama al método setOpenNow() cuando compiles el objeto SearchByTextRequest.

• Niveles de precios

  De forma predeterminada, los resultados incluyen lugares que brindan servicios en todos los niveles de precios. Para restringir resultados de modo que solo incluyan lugares en niveles de precios particulares, puedes pasar una lista de valores enteros que correspondan a los niveles de precios de los lugares que deseas mostrar:

  • 1: El lugar ofrece servicios económicos.
  • 2: El lugar ofrece servicios a precios moderados.
  • 3: El lugar ofrece servicios costosos.
  • 4: El lugar ofrece servicios muy costosos.
  Nota: El valor entero de 0, que indica que el lugar ofrece servicios gratuitos, se puede incluir en una respuesta, pero no se puede usar como valor de filtro en una solicitud.

  Para configurar el parámetro de niveles de precios, llama al setPriceLevels() método cuando compiles el SearchByTextRequest objeto.

• Preferencia de clasificación

  Especifica cómo se clasifican los resultados en la respuesta según el tipo de consulta:

  • Para una consulta categórica, como "Restaurantes en la Ciudad de México", SearchByTextRequest.RankPreference.RELEVANCE (clasifica los resultados por relevancia de la búsqueda) es el valor predeterminado. Puedes establecer la preferencia de clasificación en SearchByTextRequest.RankPreference.RELEVANCE o SearchByTextRequest.RankPreference.DISTANCE (clasifica los resultados por distancia).
  • Para una consulta no categórica, como "Mountain View, CA", te recomendamos que dejes sin configurar el parámetro de preferencia de clasificación.

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

• 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. Este parámetro también puede tener un efecto de personalización en los resultados de la búsqueda. No hay un valor predeterminado.

  Si el nombre del país del campo de dirección en la respuesta coincide con el código de región, se omite el código de país de la dirección.

  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 SearchByTextRequest objeto.

• Filtrado estricto de tipos

  Se usa con el parámetro de tipo incluido. Cuando se establece en true, solo se muestran los lugares que coinciden con los tipos especificados por el tipo incluido. Cuando es false (el valor predeterminado), la respuesta puede contener lugares que no coinciden con los tipos especificados.

  Para configurar el parámetro de filtrado estricto de tipos, llama al setStrictTypeFiltering() método cuando compiles el SearchByTextRequest objeto.