Text Search devuelve 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 establecida.
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 región, restricción de ubicación o sesgo de ubicación).
"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. |
"Restaurante de cadena de Nueva York" | Varias ubicaciones de "Restaurante de cadena" 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. |
Cómo obtener una lista de lugares con una búsqueda de texto
Realiza una solicitud de Text Search llamando a GMSPlacesClient
searchByTextWithRequest:
y pasando un objeto GMSPlaceSearchByTextRequest
que defina los parámetros de la solicitud y un método de devolución de llamada del tipo GMSPlaceSearchByTextResultCallback
para procesar la respuesta.
El objeto GMSPlaceSearchByTextRequest
especifica todos los parámetros obligatorios y opcionales para la solicitud. Entre los parámetros obligatorios, se incluyen los siguientes:
- La lista de campos que se debe mostrar en el objeto
GMSPlace
, también llamada máscara de campo, según lo defineGMSPlaceProperty
. Si no especificas al menos un campo en la lista de campos o si omites la lista de campos, la llamada mostrará un error. - La consulta de texto.
En este ejemplo de solicitud de búsqueda de texto, se especifica que los objetos GMSPlace
de respuesta contienen el nombre y el ID del lugar de cada objeto GMSPlace
en los resultados de la búsqueda. También filtra la respuesta para que solo se muestren lugares del tipo "restaurante".
Swift
// Create the GMSPlaceSearchByTextRequest object. let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID]; let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue] request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2D(latitude: 20, longitude: 30), CLLocationCoordinate2D(latitude: 40, longitude: 50) ) // Array to hold the places in the response placeResults = []; let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } self.placeResults = results } GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)
Objective‑C
// Create the GMSPlaceSearchByTextRequest object. GMSPlaceSearchByTextRequest *request = [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]]; request.isOpenNow = YES; request.includedType = @"restaurant"; request.maxResultCount = 5; request.minRating = 3.5; request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance; request.isStrictTypeFiltering = YES; request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ]; request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50)); request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } }];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Respuestas de Text Search
La API de Text Search muestra un array de coincidencias en forma de objetos GMSPlace
, con un objeto GMSPlace
por cada lugar coincidente.
Junto con los campos de datos, el objeto GMSPlace
en la respuesta contiene las siguientes funciones de miembro:
-
isOpen
calcula si un lugar está abierto en un momento determinado. isOpenAtDate
calcula si un lugar está abierto en una fecha determinada.
Parámetros obligatorios
Usa el objeto GMSPlaceSearchByTextRequest
para especificar los parámetros necesarios para la búsqueda.
-
Lista de campos
Especifica qué propiedades de datos de lugar deseas devolver. Pasa una lista de propiedades
GMSPlace
en la que se especifican los campos de datos que se mostrarán. Si omites la máscara de campo, la solicitud mostrará un error.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):
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
Los siguientes campos activan el SKU de Text Search (Basic):
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
yGMSPlacePropertyWheelchairAccessibleEntrance
Los siguientes campos activan el SKU de Text Search (Advanced):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
yGMSPlacePropertyWebsite
Los siguientes campos activan el SKU de Text Search (Preferred):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
yGMSPlacePropertyTakeout
-
textQuery
Es la cadena de texto en la que se busca, por ejemplo: "restaurante", "calle principal 123" o "mejor lugar para visitar en San Francisco".
Parámetros opcionales
Usa el objeto GMSPlaceSearchByTextRequest
para especificar los parámetros opcionales de la búsqueda.
includedType
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:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
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
.isStrictTypeFiltering
Se usa con el parámetro
includeType
. Cuando se establece entrue
, solo se muestran los lugares que coinciden con los tipos especificados porincludeType
. Cuando es falso, el valor predeterminado, la respuesta puede contener lugares que no coinciden con los tipos especificados.locationBias
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
locationRestriction
olocationBias
, pero no ambos. Considera quelocationRestriction
especifica la región en la que deben estar los resultados ylocationBias
la región a la que los resultados deben estar cerca, pero que pueden estar fuera del área.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. El radio predeterminado es 0.0. Por ejemplo:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
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.
- Si
locationRestriction
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
locationBias
para obtener información sobre cómo definir el viewport.Puedes especificar
locationRestriction
olocationBias
, pero no ambos. Considera quelocationRestriction
especifica la región en la que deben estar los resultados ylocationBias
la región a la que los resultados deben estar cerca, pero que pueden estar fuera del área.-
maxResultCount
Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe ser un valor entre 1 y 20 (valor predeterminado) inclusive.
minRating
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.
-
priceLevels
Restringe la búsqueda a los lugares marcados en determinados niveles de precios. La opción predeterminada es seleccionar todos los niveles de precios.
Especifica un array de uno o más valores definidos por
PriceLevel
.Por ejemplo:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
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",
.relevance
(resultados de clasificación por relevancia de búsqueda) es el valor predeterminado. Puedes establecerrankPreference
en.relevance
o.distance
(clasificar los resultados por distancia). - Para una consulta no categórica, como "Mountain View, CA", te recomendamos que no configures
rankPreference
.
- Para una consulta categórica como "Restaurantes en la ciudad de Nueva York",
regionCode
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.
Mostrar atribuciones en tu aplicación
Cuando tu app muestra información obtenida de GMSPlacesClient
, como fotos y opiniones, también debe mostrar las atribuciones requeridas.
Por ejemplo, la propiedad reviews
del objeto GMSPlacesClient
contiene un array de hasta cinco objetos GMSPlaceReview
. Cada objeto GMSPlaceReview
puede contener atribuciones y atribuciones de autor.
Si muestras la opinión en tu app, también debes mostrar cualquier atribución o atribución de autor.
Para obtener más información, consulta la documentación sobre las atribuciones.