Text Search

Text Search muestra información sobre un conjunto de lugares en función de una cadena; por ejemplo, "pizza en Nueva York" o "tiendas de zapatos cerca de Ottawa" o "123 Main Street". 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 sin dirección de la cadena pueden coincidir con empresas y direcciones. Algunos ejemplos de consultas de direcciones ambiguas son las direcciones con formato deficiente o las solicitudes que incluyen componentes sin dirección, como los nombres de las empresas. Es posible que las solicitudes como las dos primeros ejemplos no muestren resultados, a menos que se establezca una ubicación, como la región, la restricción de ubicación o el sesgo de ubicación.

"10 High Street, UK" o "123 Main Street, EE.UU." Múltiples "calles principales" en el Reino Unido; varias "calles principales" en EE.UU. La consulta no muestra los resultados deseados, a menos que se establezca una restricción de ubicación.
"Restaurante de cadenas de Nueva York" Varias ubicaciones de "ChainRestaurant" en Nueva York sin dirección ni nombre
"10 High Street, Escher UK" o "123 Main Street, Pleasanton, EE.UU." Solo una "High Street" en la ciudad de Escher, en el Reino Unido, y solo una "Main Street" en la ciudad estadounidense de Pleasanton, CA.
“NombredeRestauranteÚnico Nueva York” Solo un establecimiento con este nombre en Nueva York; no es necesario diferenciar una dirección.
"restaurantes de pizza en Nueva York" Esta consulta contiene su restricción de ubicación, y "pizzería" es un tipo de lugar bien definido. Muestra varios resultados.
"+1 514-670-8700"

Esta consulta contiene un número de teléfono. Muestra varios resultados para los lugares asociados con ese número de teléfono.

Solicitudes de Text Search

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.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, hiciste lo siguiente:

  • Establece la lista de campos para incluir solo Place.Field.ID y Place.Field.NAME. Esto 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 como "Comida vegetariana picante".

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

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

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

Respuestas de Text Search

La clase SearchByTextResponse 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 pasa 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.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 del objeto de Place.

Parámetros obligatorios

  • Lista de campos

    Especifica qué campos de datos de lugar se deben devolver. Pasa una lista de valores Place.Field que especifique los campos de datos que se mostrarán. No hay una lista predeterminada de los 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 innecesarios.

    Especifica uno o más de los siguientes campos:

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

      Place.Field.ID, Place.Field.NAME

    • Los siguientes campos activan el SKU de Text 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.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT y Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

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

  • Consulta de texto

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

Parámetros opcionales

Establece estos parámetros con los métodos de SearchByTextRequest.Builder. Por ejemplo, para establecer el recuento máximo de resultados, llama a SearchByTextRequest.Builder.setMaxResultCount().

  • 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")

  • Sesgo de ubicación

    Especifica un área de búsqueda. Esta ubicación sirve como sesgo, lo que significa que se pueden mostrar resultados en torno a la ubicación especificada, incluso resultados fuera del área especificada.

    Puedes especificar una restricción o sesgo de ubicación, pero no ambos. Piensa en la restricción de ubicación como en la región en la que deben encontrarse los resultados, y en el sesgo de ubicación como en la región donde los resultados deben estar cerca, pero pueden estar fuera del área.

    Especifica la región como una ventana gráfica rectangular o un círculo.

    • Un círculo se define por el punto central y el radio en metros. El radio debe ser de entre 0.0 y 50,000.0, inclusive. El radio predeterminado es 0.0. 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 inferior y superior diagonalmente opuestos. El punto inferior marca la esquina suroeste del rectángulo, y el punto alto representa la esquina noreste del rectángulo.

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

      • Si low = high, el viewport consta de ese único punto.
      • 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 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 Text Search.

  • Restricción de ubicación

    Especifica un área de búsqueda. No se muestran los resultados fuera del área especificada. Especifica la región como una viewport rectangular. Consulta la descripción de Sesgo de ubicación para obtener información sobre cómo definir la viewport.

    Puedes especificar una restricción o sesgo de ubicación, pero no ambos. Piensa en la restricción de ubicación como en la región en la que deben encontrarse los resultados, y en el sesgo de ubicación como en la región donde los resultados deben encontrarse cerca, pero pueden estar fuera del área.

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

  • 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 punto 0.5 más cercano. Por ejemplo, un valor de 0.6 elimina todos los resultados con una calificación inferior a 1.0.

  • 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, se devuelven todas las empresas, independientemente de su estado abierto. Los lugares que no especifican los horarios de atención en la base de datos de Google Places se muestran si estableces este parámetro en false.

  • Niveles de precios

    Restringe la búsqueda a los lugares marcados con determinados niveles de precios. La opción predeterminada es seleccionar todos los niveles de precios.

    Especifica una lista de uno o más de los siguientes valores de número entero:

    • 1 a PRICE_LEVEL_INEXPENSIVE
    • 2: PRICE_LEVEL_MODERATE
    • 3: PRICE_LEVEL_EXPENSIVE
    • 4: PRICE_LEVEL_VERY_EXPENSIVE

  • Preferencia de clasificación

    Especifica cómo se clasifican los resultados en la respuesta. La API usa RELEVANCE de forma predeterminada cuando corresponde. Por ejemplo, para una consulta como "Restaurantes en la Ciudad de Nueva York", el valor predeterminado es RELEVANCE. Para las consultas geográficas, como "Mountain View, CA", o cualquier otro tipo de consultas, no se aplica ningún valor predeterminado y los resultados aparecen en el orden en que los muestra el backend.

    Los valores incluyen los siguientes:

    • SearchByTextRequest.RankPreference.DISTANCE: Clasifica los resultados por distancia.
    • SearchByTextRequest.RankPreference.RELEVANCE: Clasifica los resultados por relevancia.

  • 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. Este parámetro también puede tener un efecto de sesgo 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, este se omite en 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.

  • Filtrado de tipos estricto

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