Text Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Desarrolladores del Espacio Económico Europeo (EEE)

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 búsquedas de direcciones ambiguas en un sistema automatizado, y los componentes que no son de dirección de la cadena también pueden coincidir con empresas y direcciones. Algunos ejemplos de búsquedas de direcciones ambiguas son las direcciones con formato incorrecto o las solicitudes que incluyen componentes que no son de 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 una preferencia 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 búsqueda no devuelve los resultados deseados, a menos que se establezca una restricción de ubicación.
"Restaurante de cadena en Nueva York" Varias ubicaciones de "Restaurante de cadena" en Nueva York; no hay dirección ni siquiera nombre de la calle.
"10 High Street, Escher UK" o "123 Main Street, Pleasanton US" Solo hay una "High Street" en la ciudad de Escher, Reino Unido, y solo una "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.
"Pizzerías en Nueva York" Esta búsqueda 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 búsqueda contiene un número de teléfono. Devuelve varios resultados para los lugares asociados a ese número de teléfono.

Obtén una lista de lugares por búsqueda de texto

Realiza una solicitud de Text Search llamando a GMSPlacesClient searchByTextWithRequest:, pasando 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:

  • Lista de campos que se devolverán 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 o si omites la lista de campos, la llamada devolverá un error.
  • Es la búsqueda de texto.

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

SDK de Places para Swift

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
}

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

Respuestas de Text Search

La API de Text Search devuelve un array de coincidencias en forma de objetos GMSPlace, con un objeto GMSPlace por lugar coincidente.

Obtén el estado de apertura

El objeto GMSPlacesClient contiene una función miembro llamada isOpenWithRequest (isOpenRequest en Swift y isPlaceOpenRequest en GooglePlacesSwift) que devuelve una respuesta que indica si el lugar está abierto en este 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 especifica 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.
  • Es un objeto NSDate (Obj-C) o Date (Swift) opcional que especifica la hora que deseas verificar. Si no se especifica una hora, se usará la hora actual de forma predeterminada.
  • Un método GMSPlaceOpenStatusResponseCallback para controlar la respuesta.
    • >

El método GMSPlaceIsOpenWithRequest requiere que se configuren 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 devuelve un objeto GMSPlaceIsOpenResponse que contiene un valor booleano llamado status que indica si la empresa está abierta, cerrada o si se desconoce el estado.

Idioma Valor si está abierto Valor si está cerrado Valor si el estado es desconocido
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Facturación de isOpenWithRequest

  • Los campos GMSPlacePropertyUTCOffsetMinutes y GMSPlacePropertyBusinessStatus se cobran según el SKU de Basic Data. El resto del horario de apertura se cobra según el SKU de Place Details Enterprise.
  • 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 objeto GMSPlaceIsOpenWithRequest dentro de un objeto GMSPlace existente.

SDK de Places para Swift

        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
        }

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

Parámetros obligatorios

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

  • Lista de campos

    Especifica qué propiedades de datos de lugar se deben devolver. Pasa una lista de propiedades GMSPlace que especifiquen los campos de datos que se devolverá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 de Text Search Essentials (solo ID):

      GMSPlacePropertyPlaceID

    • Los siguientes campos activan el SKU de Text Search Pro:

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

    • Los siguientes campos activan el SKU de Text Search Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Los siguientes campos activan el SKU de Text Search Enterprise Plus:

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

  • textQuery

    Es la cadena de texto en la que se basa la búsqueda, por ejemplo, "restaurante", "calle principal 123" o "el 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 por la Tabla A. Solo se puede especificar un tipo. Por ejemplo:

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    Si es true, devuelve solo los lugares que están abiertos en el momento en que se envía la búsqueda. Si es false, se muestran todas las empresas, independientemente de su estado. 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 establece en true, solo se devuelven los lugares que coinciden con los tipos especificados por includeType. Cuando es falso (valor predeterminado), la respuesta puede contener lugares que no coinciden con los tipos especificados.

  • locationBias

    Especifica un área para la búsqueda. Esta ubicación sirve como sesgo, lo que significa que se pueden devolver 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 cerca de la cual deben estar los resultados, pero pueden estar fuera del área.

    Especifica la región como un viewport rectangular o como un círculo.

    • Un círculo se define por un punto central y un radio en metros. El radio debe estar entre 0.0 y 50000.0, ambos incluidos. El radio predeterminado es 0.0. Por ejemplo:

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

    • Un rectángulo es una ventana gráfica de latitud y longitud, representada como dos puntos bajos y altos 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 estar entre -90 y 90 grados inclusive, y los límites de longitud deben estar 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, la ventana gráfica 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 la búsqueda. No se muestran los 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 la ventana gráfica.

    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 cerca de la cual deben estar los resultados, pero pueden estar fuera del área.

  • maxResultCount

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

  • minRating

    Restringe los resultados solo a aquellos cuya calificación promedio de los usuarios sea mayor 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 marcados en 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:

        let request = SearchByTextRequest()
    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", .relevance (ordenar los resultados por relevancia de la búsqueda) es el valor predeterminado. Puedes establecer rankPreference en .relevance o .distance (clasifica los resultados por distancia).
    • Para una búsqueda no categórica, como "Mountain View, CA", te recomendamos que no establezcas 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 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, se omite el código de país de la dirección.

    La mayoría de los códigos de 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 "El Reino Unido de Gran Bretaña e Irlanda del Norte"). El parámetro puede afectar los resultados según la legislación aplicable.

  • shouldIncludePureServiceAreaBusinesses

    Si es true, devuelve empresas puras de área de servicio en los resultados de la búsqueda. Una empresa exclusivamente de servicio en el área es una empresa que visita a los clientes o les entrega sus productos directamente, pero que no los atiende en su dirección comercial.

    Por ejemplo:

    SDK de Places para Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

Mostrar atribuciones en tu aplicación

Cuando tu app muestre información obtenida de GMSPlacesClient, como fotos y opiniones, también deberá 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 del autor.

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