Text Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Desarrolladores del Espacio Económico Europeo (EEE)

Text Search (nueva) 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 que se haya establecido.

Además de los parámetros obligatorios, Text Search (nueva) admite el refinamiento de las consultas con parámetros opcionales para obtener mejores resultados.

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

Para realizar una solicitud de Text Search, llama a GMSPlacesClient searchByTextWithRequest:, 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 de la solicitud. Entre los parámetros obligatorios, se incluyen los siguientes:

  • La lista de campos que se mostrarán en el GMSPlace objeto, también llamada la máscara de campo, como se define en GMSPlaceProperty. Si no especificas al menos un campo en la lista de campos o si omites la lista de campos, la llamada muestra un error.
  • La búsqueda de texto.

En esta solicitud de búsqueda de texto de ejemplo, se especifica que los objetos GMSPlace de respuesta contengan el nombre y el ID de 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".

SDK de Places para Swift

let restriction = GMSPlaceRectangularLocationOption(
      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 muestra un array de coincidencias en la forma de GMSPlace objetos, con un GMSPlace objeto por lugar coincidente.

Cómo obtener el estado 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 del tipo GMSPlaceIsOpenWithRequest que contiene lo siguiente:

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.

Respuesta de isOpenWithRequest

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
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 de los horarios de atención se cobran 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: Cómo realizar una solicitud GMSPlaceIsOpenWithRequest

En el siguiente ejemplo, se muestra cómo inicializar un 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
            }
          }];

Paginación

Text Search proporciona un objeto de paginación, el hasNextPage booleano, que se muestra en la primera respuesta a una llamada de Text Search. Si hay una página siguiente disponible, puedes usar la fetchNextPage() función para cargarla.

En el siguiente ejemplo, se muestra cómo verificar si hay una página siguiente disponible y, luego, cargar la página.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

Parámetros obligatorios

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

  • Lista de campos

    Especifica qué propiedades de datos de lugar se deben mostrar. Pasa una lista de GMSPlace propiedades que especifiquen los campos de datos que se deben mostrar. 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 busca, 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 de la búsqueda.

  • includedType

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

  • locationBias

    Especifica un área para buscar. Esta ubicación sirve como una personalización, lo que significa que se pueden mostrar resultados en torno a 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 en la que los resultados deben estar cerca, 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 el punto central y el radio en metros. El radio debe estar entre 0.0 y 50000.0, inclusive. 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 un viewport de latitud y longitud, representado como dos puntos bajos y altos opuestos en diagonal. 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 punto único.
      • 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 para buscar. 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 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 en la que los resultados deben estar cerca, pero pueden estar fuera del área.

  • maxResultCount

    Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe estar entre 1 y 20 (predeterminado), inclusive.

  • minRating

    Restringe los resultados solo a aquellos cuya calificación promedio de los usuarios sea 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 a 0.5 más cercanos. Por ejemplo, un valor de 0.6 elimina todos resultados con una calificación inferior a 1.0.

  • priceLevels

    Restringe la búsqueda a lugares que están 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 consulta categórica, como "Restaurantes en la Ciudad de México", .relevance (clasificar los resultados por relevancia de la búsqueda) es el valor predeterminado. Puedes establecer rankPreference en .relevance o .distance (clasificar los resultados por distancia).
    • Para una consulta no categórica, como "Mountain View, CA", te recomendamos que dejes rankPreference sin configurar.

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

  • shouldIncludePureServiceAreaBusinesses

    Si es true, muestra empresas exclusivamente de servicio en el área 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 aplicación 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 GMSPlaceReview objetos. Cada objeto GMSPlaceReview puede contener atribuciones y atribuciones del autor. Si muestras la opinión en tu aplicación, 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.