Text Search (nueva)

Text Search devuelve información sobre un conjunto de lugares en función de una cadena. Por ejemplo, "pizza en Nueva York", "tiendas de zapatos cerca de Ottawa" o "Calle Principal 123". El servicio responde con una lista de lugares que coinciden con la cadena de texto y 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 sin dirección de la cadena pueden coincidir con empresas y direcciones. Algunos ejemplos de consultas de dirección ambiguas son las direcciones con un formato incorrecto o las solicitudes que incluyen componentes sin dirección, como nombres de 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).

Obtén una lista de lugares mediante la búsqueda de texto

Para realizar una solicitud de Text Search, llama a GMSPlacesClient searchByTextWithRequest: y pasa un objeto GMSPlaceSearchByTextRequest que defina los parámetros de la solicitud y un método de devolución de llamada del tipo GMSPlaceSearchByTextResultCallback para controlar 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 mostrarán en el objeto GMSPlace, también llamada máscara de campo, según se define en GMSPlaceProperty. Si no especificas al menos un campo de la lista o si omites la lista de campos, la llamada mostrará un error.
• La consulta de texto.

En esta solicitud de búsqueda de texto de ejemplo, se especifica que los objetos GMSPlace de respuesta contienen el nombre y el ID de lugar de cada objeto GMSPlace en los resultados de la búsqueda. También filtra la respuesta para que solo muestre lugares del tipo “restaurante”.

// 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)

// 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;
  }
}];

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 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 los datos de lugar se mostrarán. Pasa una lista de propiedades de GMSPlace que especifique los campos de datos que se mostrarán. Si omites la máscara de campo, la solicitud mostrará un error.

  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):

    GMSPlacePropertyPlaceID, GMSPlacePropertyName

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

    GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyFormattedAddress, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyCoordinate, GMSPlacePropertyPhotos, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport y GMSPlacePropertyWheelchairAccessibleEntrance

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

    GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal y GMSPlacePropertyWebsite

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

    GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine y GMSPlacePropertyTakeout

• textQuery

  Es la cadena de texto en la que se realizará la búsqueda, por ejemplo: "restaurante", "calle principal 123" o "el mejor lugar para visitar en Buenos Aires".

Parámetros opcionales

Usa el objeto GMSPlaceSearchByTextRequest para especificar los parámetros opcionales para la búsqueda.

• includedType

  Restringe los resultados a los lugares que coinciden con el tipo especificado 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 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.

• isStrictTypeFiltering

  Se usa con el parámetro includeType. Cuando se configura en true, solo se muestran los lugares que coinciden con los tipos especificados por includeType. 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 sesgo, lo que significa que se pueden mostrar resultados en torno a la ubicación especificada, incluso resultados fuera del área especificada.

  Puedes especificar locationRestriction o locationBias, pero no ambos. Piensa en locationRestriction como la región en la que se especificarán los resultados, y como en locationBias, como en la región donde los resultados deben encontrarse 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:

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

• locationRestriction

  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 locationBias para obtener información sobre cómo definir la viewport.

  Puedes especificar locationRestriction o locationBias, pero no ambos. Piensa en locationRestriction como la región en la que se especificarán los resultados, y como en locationBias, como en la región donde los resultados deben encontrarse cerca, pero 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 (predeterminado) inclusive.

• minRating

  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.

• priceLevels

  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 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 por categoría, como "Restaurantes en la Ciudad de Nueva York", el valor predeterminado es .relevance (clasifica los resultados por relevancia de la búsqueda). Puedes establecer rankPreference en .relevance o .distance (clasifica los resultados por distancia).
  • Para una consulta no categórica, como "Mountain View, CA", te recomendamos que dejes rankPreference sin configurar.

• regionCode

  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.

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 del autor. Si muestras la opinión en tu app, también debes mostrar cualquier atribución o atribución del autor.

Para obtener más información, consulta la documentación sobre las atribuciones.