Text Search (nueva)

Una búsqueda de texto 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 coincida con la cadena de texto y con cualquier personalización de ubicación establecida.

El servicio es especialmente útil para crear direcciones ambiguas las consultas en un sistema automatizado y los componentes sin dirección de la cadena pueden coincidir con las empresas, así como direcciones IP del proveedor. Algunos ejemplos de consultas de direcciones ambiguas son las direcciones con formato incorrecto o 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 una se establece la ubicación (como región, restricción de ubicación o sesgo de ubicación).

Cómo obtener una lista de lugares mediante una búsqueda de texto

Para realizar una solicitud de búsqueda de texto, 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, de 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á en el objeto GMSPlace también llamada máscara de campo, según lo define GMSPlaceProperty Si no especificas al menos un campo en la lista de campos la lista de campos, entonces la llamada devuelve un error.
• La búsqueda de texto

Esta solicitud de búsqueda de texto de ejemplo especifica que los objetos GMSPlace de respuesta contiene el nombre y el ID de lugar de cada objeto GMSPlace de la búsqueda resultados. También filtra la respuesta para que solo se devuelvan lugares de tipo. "restaurante".

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

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
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(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.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        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 devuelve un array de coincidencias en el forma de GMSPlace objetos, con un objeto GMSPlace por cada lugar coincidente.

Obtener estado de apertura

El objeto GMSPlacesClient contiene una función de miembro llamada isOpenWithRequest (isOpenRequest en Swift y isPlaceOpenRequest en GooglePlacesSwift) que muestra una respuesta que indica si el lugar está abierto en ese momento, según el horario especificado en la llamada.

Este método toma un solo argumento de tipo GMSPlaceIsOpenWithRequest que contiene lo siguiente:

• Un objeto GMSPlace o una cadena que especifique un ID de lugar Para obtener más información sobre cómo crear el objeto Place con los campos necesarios, consulta Detalles del lugar.
  
• Un objeto NSDate (Obj-C) o Date (Swift) opcional que especifique la hora que deseas verificar. Si no se especifica la hora, el valor predeterminado será ahora.
• Un método GMSPlaceOpenStatusResponseCallback para controlar la respuesta.
>

El método GMSPlaceIsOpenWithRequest requiere que se establezcan los siguientes campos en el objeto GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

Si estos campos no se proporcionan en el objeto Place o si pasas un ID de lugar, el método usa GMSPlacesClient GMSFetchPlaceRequest: para recuperarlos.

isOpenWithRequest respuesta

isOpenWithRequest muestra un objeto GMSPlaceIsOpenResponse que contiene un valor booleano llamado status que indica si la empresa está abierta, cerrada o si el estado es desconocido.

Facturación para isOpenWithRequest

• Los campos GMSPlacePropertyUTCOffsetMinutes y GMSPlacePropertyBusinessStatus se cobran según el SKU de Basic Data. El resto del horario de atención se cobra en el SKU de Place Details (Advanced).
• Si tu objeto GMSPlace ya tiene estos campos de una solicitud anterior, no se te volverá a cobrar.

Ejemplo: Realiza una solicitud GMSPlaceIsOpenWithRequest

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

Parámetros obligatorios

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

• Lista de campos

  Especifica qué propiedades de datos de lugar deseas devolver. Pasa una lista de propiedades GMSPlace que especifiquen los campos de datos que se mostrarán. Si omites el campo máscara, la solicitud mostrará un error.

  Las listas de campos constituyen una práctica de diseño recomendada para asegurarse de no solicitar datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos de facturación.

  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 Text Search (Basic):

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

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

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

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

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

• textQuery

  Cadena de texto en la que se realizará la búsqueda, por ejemplo: "restaurante" o "123 Principal o "el mejor lugar para visitar en San Francisco".

Parámetros opcionales

Usa el objeto GMSPlaceSearchByTextRequest para especificar el valor parámetros 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, devuelve solo los lugares que estén abiertos. en el momento en que se envía la consulta. Si es false, mostrar todas las empresas independientemente del estado abierto. Los lugares que no especifican los horarios de atención en la base de datos de Google Places son que se muestra si estableces este parámetro en false.

• isStrictTypeFiltering

  Se usa con el parámetro includeType. Cuando se establece en true, solo lugares que coincidan con los tipos especificados por Se devuelven 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 un sesgo, lo que significa se pueden devolver resultados alrededor de la ubicación especificada, incluso resultados fuera del área especificada.

  Puedes especificar locationRestriction o locationBias, pero no ambos. Piensa en locationRestriction como la especificación región en la que deben estar los resultados y locationBias, ya que que especifica la región a la que los resultados deben estar cerca, pero pueden estar fuera en el área.

  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 50,000.0, inclusive. El radio predeterminado es 0.0. Por ejemplo:

    request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

  • Un rectángulo es un viewport de latitud y longitud, representado por dos en diagonal frente a puntos bajos y altos en diagonal. El punto más bajo marca el suroeste del rectángulo, y el punto alto representa el noreste esquina del rectángulo.

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

    • Si low = high, el viewport consta de lo siguiente: ese 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, el viewport incluye todo longitudes.
    • Si low.longitude = 180 grados y high.longitude = -180 grados, el intervalo de longitud es vacío.
    • Si low.latitude > high.latitude, el rango de latitud está vacío.

• locationRestriction

  Especifica un área de búsqueda. Los resultados fuera del área especificada no se muestran que se devuelven. Especifica la región como una ventana de visualización rectangular. Ver la descripción de locationBias para obtener información sobre cómo definir el viewport.

  Puedes especificar locationRestriction o locationBias, pero no ambos. Piensa en locationRestriction como la especificación región en la que deben estar los resultados y locationBias, ya que que especifica la región a la que los resultados deben estar cerca, pero pueden estar fuera en el área.

• maxResultCount

  Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe ser un valor entre 1 y 20 (predeterminado), ambos incluidos.

• minRating

  Restringe los resultados únicamente a aquellos cuya calificación promedio de los usuarios es superior a 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 son y se redondea al punto decimal 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 lugares que estén marcados con ciertos 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 (clasifica los resultados según la relevancia de la búsqueda) es el valor predeterminado. Puedes establecer rankPreference en .relevance o .distance (clasifica los resultados por distancia).
  • Para una consulta no categórica, como “Mountain View, CA”, recomendamos que deje rankPreference sin configurar.

• regionCode

  El código de región que se usa para dar formato a la respuesta, especificado como una 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 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 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 en tu aplicación se muestra información obtenida de GMSPlacesClient, como fotos y opiniones, también deben exhibirse las atribuciones requeridas.

Por ejemplo, la propiedad reviews del objeto GMSPlacesClient contiene un array de hasta cinco GMSPlaceReview objetos. Cada objeto GMSPlaceReview puede contener atribuciones y atribuciones de autor. Si muestra la opinión en su aplicación, también debe mostrar cualquier atribución o autor atribución.

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