Text Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

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.

El servicio es especialmente útil para realizar consultas de direcciones ambiguas en un sistema automatizado, y los componentes que no son de dirección de la cadena pueden coincidir con empresas y direcciones. Entre los ejemplos de consultas de direcciones ambiguas se incluyen direcciones con formato deficiente o solicitudes que incluyen componentes sin dirección, como nombres de empresas. Las solicitudes como los dos primeros ejemplos pueden mostrar cero resultados, a menos que se establezca una ubicación, como una región, una restricción de ubicación o un sesgo de ubicación.

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 la Búsqueda de Nearby (nueva) requiere un área específica en la que realizar la búsqueda.

“10 High Street, Reino Unido” o “123 Main Street, EE.UU.”	Varias "High Street" en el Reino Unido y varias "Main Street" en EE.UU. La consulta no muestra los resultados deseados, a menos que se establezca una restricción de ubicación.
"ChainRestaurant New York"	Varias ubicaciones de "ChainRestaurant" en Nueva York, sin dirección ni nombre de calle
“10 High Street, Escher, Reino Unido” o “123 Main Street, Pleasanton, EE.UU.”	Solo hay una “High Street” en la ciudad de Escher, Reino Unido, y una sola “Main Street” en la ciudad de Pleasanton, California, EE.UU.
"UniqueRestaurantName New York"	Solo hay un establecimiento con este nombre en Nueva York, por lo que no se necesita una dirección para diferenciarlo.
"pizza restaurants in New York"	Esta consulta contiene su restricción de ubicación y "pizzerías" es un tipo de lugar bien definido. Devuelve varios resultados.
"[phone]"	Esta consulta contiene un número de teléfono. Muestra varios resultados de los lugares asociados con ese número de teléfono. Nota: Para obtener mejores resultados cuando busques un número de teléfono, incluye el código de país seguido de un espacio y establece el parámetro regionCode 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.

Nota: La Búsqueda de texto (nueva) está disponible en el SDK de Places para Android 3.3.0 y versiones posteriores. Para obtener más información, consulta Elige la 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, debes hacer lo siguiente:

• Configura la lista de campos para que incluya 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 objeto SearchByTextRequest que defina la búsqueda.

  • Establece la cadena de consulta de texto en "Comida vegetariana picante".

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

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

• Agrega un OnSuccessListener y obtén los lugares que coincidan del objeto SearchByTextResponse.

Nota: Para obtener más información sobre cómo inicializar PlacesClient, consulta Cómo inicializar 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 envíe 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 ella, incluso si no se muestra una respuesta.

Respuestas de Text Search

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

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

// 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 solo contiene 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 ver más ejemplos de acceso a datos en un objeto Place, consulta Cómo acceder a los campos de datos de objetos de Place.

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 valores Place.Field que especifiquen los campos de datos que se mostrarán. No hay una lista predeterminada de campos que se muestran en la respuesta.

  Las listas de campos son 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 Text Search (solo ID):

    Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME
    
    Notas:

    • El campo Place.Field.NAME dejó de estar disponible en la versión 4.0 del SDK de Places para Android. Usa Place.Field.DISPLAY_NAME en su lugar.
    • El campo RESOURCE_NAME contiene el nombre del recurso de lugar en el formato: places/PLACE_ID. Usa DISPLAY_NAME para acceder al nombre del lugar en forma de texto.

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

    Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, 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
    
    Nota: Los campos Place.Field.ADDRESS, Place.Field.ICON_URL, Place.Field.LAT_LNG y Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE dejaron de estar disponibles en la versión 4.0 del SDK de Places para Android. En su lugar, usa Place.Field.FORMATTED_ADDRESS, Place.Field.ICON_MASK_URL, Place.Field.LOCATION y Place.ACCESSIBILITY_OPTIONS, respectivamente. Place.Field.ACCESSIBILITY_OPTIONS solo está disponible para Place Details (nuevo).

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

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS, Place.Field.INTERNATIONAL_PHONE_NUMBER, 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, Place.Field.WEBSITE_URI,
    
    Nota: Los campos Place.Field.PHONE_NUMBER y Place.Field.USER_RATINGS_TOTAL dejaron de estar disponibles en la versión 4.0 del SDK de Places para Android. En su lugar, usa Place.Field.INTERNATIONAL_PHONE_NUMBER y Place.USER_RATING_COUNT, respectivamente.

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

    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: La versión 4.0 del SDK de Places para Android dio de baja varios campos de datos de Place y agregó campos nuevos. Para obtener más información, consulta Cómo migrar 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 SearchByTextRequest.

• Búsqueda de texto

  Es la cadena de texto en la que se realiza la búsqueda, por ejemplo, "restaurante", "calle principal 123" o "mejor lugar para visitar en San Francisco". La API muestra 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.

Parámetros opcionales

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

• Tipo incluido

  Restringe los resultados a los lugares que coinciden con el tipo especificado en la 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 los valores de la Tabla B como filtro.

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

• Sesgo de ubicación

  Especifica un área para buscar. Esta ubicación funciona como un sesgo, 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 el sesgo de ubicación, pero no ambos. 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 el sesgo 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 se usa el sesgo de ubicación, los resultados pueden estar fuera del área especificada.

  Nota: Si omites el sesgo de ubicación y la restricción de ubicación, la API usará el sesgo de IP de forma predeterminada. Con el sesgo de IP, la API usa la dirección IP del dispositivo para sesgar 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-longitud, representado como dos puntos altos y bajos 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 oscilar entre -90 y 90 grados inclusive, y los límites de longitud deben oscilar entre -180 y 180 grados inclusive:

    • Si low = high, la ventana de visualización consta de ese único punto.
    • Si low.longitude > high.longitude, el rango de longitud se invierte (la ventana de visualización cruza la línea de longitud de 180 grados).
    • Si low.longitude = -180 grados y high.longitude = 180 grados, la ventana de visualización 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 propagar los valores bajo y alto, y el cuadro representado no puede estar vacío. Un viewport vacío genera un error.

    Por ejemplo, para ver un viewport rectangular, consulta Solicitudes de búsqueda de texto.

    Para establecer el parámetro de sesgo 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 del sesgo de ubicación para obtener información sobre cómo definir el viewport.

  Puedes especificar la restricción de ubicación o el sesgo de ubicación, pero no ambos. 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 el sesgo de ubicación como la especificación de la región a la que deben estar cerca los resultados, pero que puede estar fuera del área.

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

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

• Recuento máximo de resultados

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

  Para establecer el parámetro de recuento de resultados máximo, 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 superior o igual a 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 al 0.5 más cercano. Por ejemplo, un valor de 0.6 elimina todos los resultados con una calificación inferior a 1.0.

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

• 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 del estado de apertura. Los lugares que no especifican los horarios de atención en la base de datos de Google Places se mostrarán si estableces este parámetro en false.

  Para establecer el parámetro open now, 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 los resultados de modo que solo incluyan lugares con niveles de precios específicos, 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 proporciona servicios gratuitos, se puede incluir en una respuesta, pero no se puede usar como valor de filtro en una solicitud.

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

• Preferencia de clasificación

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

  • Para una búsqueda categórica, como "Restaurantes en la ciudad de Nueva York", el valor predeterminado es SearchByTextRequest.RankPreference.RELEVANCE (clasifica los resultados por relevancia de la búsqueda). 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 no configures el parámetro de preferencia de clasificación.

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

• 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 sesgado 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 “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 de código de región, llama al método setRegionCode() cuando compiles el objeto SearchByTextRequest.

• Filtrado de tipo estricto

  Se usa con el parámetro de tipo de inclusión. Cuando se establece en true, solo se muestran los lugares que coinciden con los tipos especificados por el tipo de inclusión. Cuando false es la opción predeterminada, la respuesta puede contener lugares que no coinciden con los tipos especificados.

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