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 de la cadena sin dirección pueden coincidir con empresas y direcciones. Algunos ejemplos de consultas de direcciones ambiguas son las direcciones con formato incorrecto o las solicitudes que incluyen componentes sin dirección, como nombres de empresas. Las solicitudes como los dos primeros ejemplos pueden devolver 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 diferencia principal entre ambos 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 buscar.
"10 High Street, UK" o "123 Main Street, EE.UU." | varias "High Street" en el Reino Unido; varias "Main Street" en EE.UU. La consulta no muestra resultados deseables, a menos que se establezca una restricción de ubicación. |
"ChainRestaurant 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 US" | Solo una "High Street" en la ciudad de Escher, en el Reino Unido, y una sola "Calle Principal" en la ciudad estadounidense de Pleasanton, California. |
"NombreDeRestaurante exclusivo Nueva York" | Solo hay un establecimiento con este nombre en Nueva York; no es necesario contar con una dirección para diferenciarlos. |
"pizzas 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. Devuelve 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:
Configura la lista de campos para que incluya solo
Place.Field.ID
yPlace.Field.NAME
. Esto significa que los objetosPlace
en la respuesta que representan cada lugar coincidente solo contienen esos dos campos.Usa
SearchByTextRequest.Builder
para crear un objetoSearchByTextRequest
que defina la búsqueda.Establece la cadena de consulta de texto como "Comida vegetariana picante".
Establece la cantidad máxima de lugares de resultado en 10. El valor predeterminado y el máximo son 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 coincidentes del objetoSearchByTextResponse
.
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 objetoPlace
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:
// Specify the list of fields to return. 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 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 devolver. Pasa una lista de valores
Place.Field
especificando los campos de datos que se mostrarán. No hay una lista predeterminada de campos mostrados en la respuesta.Las listas de campos constituyen 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
yPlace.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
yPlace.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
yPlace.Field.TAKEOUT
Para establecer el parámetro de lista de campos, llama al método
setPlaceFields()
cuando compiles el objetoSearchByTextRequest
. -
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 San Francisco". La API muestra posibles coincidencias en función de esta cadena y ordena los resultados según la relevancia percibida.
Para establecer el parámetro de búsqueda de texto, llama al método
setTextQuery()
cuando compiles el objetoSearchByTextRequest
.
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 definido en la Tabla A. Solo se puede especificar un tipo. Por ejemplo:
setIncludedType("bar")
setIncludedType("pharmacy")
Para establecer el parámetro de tipo incluido, llama al método
setIncludedType()
cuando compiles el objetoSearchByTextRequest
.Sesgo de ubicación
Especifica un área de búsqueda. Esta ubicación sirve como una personalización, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluso resultados fuera del área especificada.
Puedes especificar la restricció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, mientras que el sesgo de ubicación especifica la región a la que los resultados deben estar cerca, pero pueden estar fuera de ella.
Especifique la región como una ventana gráfica 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 50,000.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 en diagonal. El punto inferior marca la esquina suroeste del rectángulo y el punto alto representa la esquina nordeste 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 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 solo punto. - Si
low.longitude
>high.longitude
, se invierte el rango de longitud (el viewport cruza la línea de longitud de 180 grados). - Si
low.longitude
= -180 grados yhigh.longitude
= 180 grados, el viewport incluye todas las longitudes. - Si
low.longitude
= 180 grados yhigh.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, para un viewport rectangular, consulta las Solicitudes de Text Search.
Para establecer el parámetro de personalización de ubicación, llama al método
setLocationBias()
cuando compiles el objetoSearchByTextRequest
.- Si
Restricción de ubicación
Especifica un área de búsqueda. No se muestran resultados fuera del área especificada. Especifica la región como una ventana gráfica rectangular. Consulta la descripción de Sesgo de ubicación para obtener información sobre cómo definir el viewport.
Puedes especificar la restricció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, mientras que el sesgo de ubicación especifica la región a la que los resultados deben estar cerca, pero pueden estar fuera de ella.
Para establecer el parámetro de restricción de ubicación, llama al método
setLocationRestriction()
cuando compiles el objetoSearchByTextRequest
.-
Cantidad máxima de resultados
Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe ser un valor entre 1 y 20 (valor predeterminado) inclusive.
Para establecer el parámetro de cantidad máxima de resultados, llama al método
setMaxResultCount()
cuando compiles el objetoSearchByTextRequest
. Calificación mínima
Restringe los resultados solo a aquellos cuya calificación promedio de los usuarios es 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 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.
Para establecer el parámetro de calificación mínima, llama al método
setMinRating()
cuando compiles el objetoSearchByTextRequest
.Abierto ahora
Si es
true
, muestra solo los lugares que están abiertos en el momento en que se envía la consulta. Si esfalse
, muestra 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 enfalse
.Para configurar el parámetro “abrir ahora”, llama al método
setOpenNow()
cuando compiles el objetoSearchByTextRequest
.-
Niveles de precios
De forma predeterminada, los resultados incluyen lugares que proporcionan servicios en todos los niveles de precios. Si quieres restringir los resultados para que solo se incluyan lugares en niveles de precios específicos, puedes pasar una lista de valores enteros correspondientes a los niveles de precios de los lugares que deseas mostrar:
1
: Place proporciona servicios económicos.2
: Place proporciona servicios a precios moderados.3
: Place ofrece servicios costosos.4
: Place ofrece servicios muy costosos.
Para establecer el parámetro de niveles de precios, llama al método
setPriceLevels()
cuando compiles el objetoSearchByTextRequest
. 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 Nueva York",
SearchByTextRequest.RankPreference.RELEVANCE
(resultados de clasificación por relevancia de búsqueda) es el valor predeterminado. Puedes establecer la preferencia de clasificación enSearchByTextRequest.RankPreference.RELEVANCE
oSearchByTextRequest.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 objetoSearchByTextRequest
.- Para una consulta categórica como "Restaurantes en la ciudad de Nueva York",
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 sesgo en los resultados de la búsqueda. No hay un valor predeterminado.
Si el nombre del país del campo de la dirección en la respuesta coincide con el código de región, el código de país se omite 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 del "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 objetoSearchByTextRequest
.Filtrado de tipos 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 esfalse
, el valor predeterminado, la respuesta puede contener lugares que no coinciden con los tipos especificados.Para establecer el parámetro de filtrado de tipos estricto, llama al método
setStrictTypeFiltering()
cuando compiles el objetoSearchByTextRequest
.