Text Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Text Search 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 establecida.

El servicio resulta particularmente útil para realizar consultas sobre direcciones ambiguas en un sistema automatizado, y los componentes sin dirección de la cadena pueden establecer coincidencias con empresas y direcciones. Entre los ejemplos de consultas de direcciones ambiguas se incluyen direcciones con formato deficiente o solicitudes que incluyen componentes sin dirección, como nombres de empresas. Las solicitudes como los dos primeros ejemplos pueden mostrar 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).

“10 High Street, Reino Unido” o “123 Main Street, EE.UU.” Varias "High Street" en el Reino Unido y varias "Main Street" en EE.UU. La consulta no muestra los resultados deseados, a menos que se establezca una restricción de ubicación.
“Cadena de restaurantes en Nueva York” Varias ubicaciones de "cadena de restaurantes" en Nueva York, sin dirección ni nombre de calle
“10 High Street, Escher, Reino Unido” o “123 Main Street, Pleasanton, EE.UU.” Solo hay una “High Street” en la ciudad de Escher, Reino Unido, y una sola “Main Street” en la ciudad de Pleasanton, California, EE.UU.
"UniqueRestaurantName New York" Solo hay un establecimiento con este nombre en Nueva York, por lo que no se necesita una dirección para diferenciarlo.
"pizza restaurants in New York" Esta consulta contiene su restricción de ubicación y "pizzerías" es un tipo de lugar bien definido. Devuelve varios resultados.
"+1 514-670-8700"

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

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 de la solicitud. Entre los parámetros obligatorios, se incluyen los siguientes:

  • Es la lista de campos que se mostrarán en el objeto GMSPlace, también llamada máscara de campo, como lo define GMSPlaceProperty. 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 búsqueda de texto

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

Swift

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

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

SDK de Places para Swift para iOS (versión preliminar)

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.

Cómo obtener el estado de abierto

El objeto GMSPlacesClient contiene una función 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 la hora especificada 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 de Place.
  • Es un objeto NSDate (Obj-C) o Date (Swift) opcional que especifica la hora que deseas verificar. Si no se especifica una hora, la configuración predeterminada es la actual.
  • 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 no se proporcionan estos campos 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.

Idioma Valor si está abierto Valor si está cerrado Valor si el estado es desconocido
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (versión preliminar) true false nil

Facturación de isOpenWithRequest

  • Los campos GMSPlacePropertyUTCOffsetMinutes y GMSPlacePropertyBusinessStatus se cobran en el SKU de Basic Data. El resto de los horarios de atención se cobran con 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

En el siguiente ejemplo, se muestra cómo inicializar un GMSPlaceIsOpenWithRequest dentro de un objeto GMSPlace existente.

Swift

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

Objective-C

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

GooglePlacesSwift

          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 los parámetros necesarios para la búsqueda.

  • Lista de campos

    Especifica qué propiedades de datos de lugares deseas que se muestren. Pasa una lista de propiedades GMSPlace que especifiquen 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 adicionales.

    Especifica uno o más de los siguientes campos:

    • Los siguientes campos activan el SKU 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

    Es la cadena de texto en la que se realiza la búsqueda, 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 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, muestra todas las empresas, independientemente del estado de apertura. Los lugares que no especifican los horarios de atención en la base de datos de Google Places se mostrarán si estableces este parámetro en false.

  • isStrictTypeFiltering

    Se usa con el parámetro includeType. Cuando se establece 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 para buscar. Esta ubicación funciona como un sesgo, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados fuera del área especificada.

    Puedes especificar locationRestriction o locationBias, pero no ambos. Piensa en locationRestriction como la especificación de la región en la que deben estar los resultados y en locationBias como la especificación de la región a la que deben estar cerca los resultados, pero que puede estar fuera del á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 50000.0, inclusive. El valor predeterminado es 0.0. Por ejemplo:

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

    • Un rectángulo es un viewport de latitud-longitud, representado como dos puntos altos y bajos diagonalmente opuestos. El punto bajo marca la esquina suroeste del rectángulo, y el punto alto representa la esquina noreste 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 oscilar entre -90 y 90 grados inclusive, y los límites de longitud deben oscilar entre -180 y 180 grados inclusive:

      • Si low = high, la ventana de visualización consta de ese punto único.
      • 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, la ventana de visualización 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 para buscar. No se muestran resultados fuera del área especificada. Especifica la región como un viewport rectangular. Consulta 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 de la región en la que deben estar los resultados y en locationBias como la especificación de la región a la que deben estar cerca los resultados, pero que puede estar fuera del área.

  • maxResultCount

    Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe estar comprendido entre 1 y 20 (valor 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 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 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 búsqueda categórica, 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 no configures rankPreference.

  • 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 sesgado 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, se omite el código de país 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 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 del autor.

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