Text Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Desarrolladores del Espacio Económico Europeo (EEE)

Text Search (nueva) 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 con cualquier personalización de ubicación que se haya establecido.

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

Obtén una lista de lugares con Text Search

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, de tipo GMSPlaceSearchByTextResultCallback, para controlar la respuesta.

El objeto GMSPlaceSearchByTextRequest especifica todos los parámetros obligatorios y opcionales de la solicitud. Los parámetros obligatorios incluyen los siguientes:

  • Es la lista de campos que se mostrará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 devuelve un error.
  • La búsqueda de texto.

En este ejemplo de solicitud de Text Search, se especifica que los objetos GMSPlace de la respuesta contengan 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 se muestren lugares del tipo "restaurant".

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 devuelve un array de coincidencias en forma de objetos GMSPlace, con un objeto GMSPlace por cada lugar coincidente.

Obtén el estado de apertura

El objeto GMSPlacesClient contiene una función de miembro llamada isOpenWithRequest (isOpenRequest en Swift y isPlaceOpenRequest en GooglePlacesSwift) que devuelve 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 del lugar.
  • Un objeto opcional NSDate (Obj-C) o Date (Swift) que especifica la hora que deseas verificar. Si no se especifica una hora, el valor predeterminado es 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 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 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 se cierra Valor si se desconoce el estado
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 con el SKU de Basic Data. El resto del horario de atención 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
            }
          }];

Paginación

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

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

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 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 devolverá 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 Essentials ID Only:

      GMSPlacePropertyPlaceID

      Para obtener una lista completa de los campos y sus SKUs asociados, consulta Campos de datos de Place (nuevo).

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

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

      Para obtener una lista completa de los campos y sus SKUs asociados, consulta Campos de datos de Place (nuevo).

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      Para obtener una lista completa de los campos y sus SKUs asociados, consulta Campos de datos de Place (nuevo).

    • 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

      Para obtener una lista completa de los campos y sus SKUs asociados, consulta Campos de datos de Place (nuevo).

  • textQuery

    Es la cadena de texto en la que se basa 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 que se define en 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, solo se devuelven 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 de apertura. 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 (el valor predeterminado), la respuesta puede contener lugares que no coinciden con los tipos especificados.

  • locationBias

    Especifica un área para buscar. Esta ubicación sirve como 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 una forma de especificar la región en la que deben estar los resultados y en locationBias como una forma de especificar la región cerca de la cual deben estar los resultados, aunque 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 diagonalmente opuestos, uno bajo y otro alto. El punto bajo marca la esquina sudoeste 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 comprendidos entre -90 y 90 grados, inclusive, y los límites de longitud deben estar comprendidos 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 para buscar. No se devuelven 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 una forma de especificar la región en la que deben estar los resultados y en locationBias como una forma de especificar la región cerca de la cual deben estar los resultados, aunque 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), ambos incluidos.

  • 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 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 determinados niveles de precios. De forma predeterminada, se seleccionan 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 (clasifica los resultados por relevancia de la búsqueda) es la opción predeterminada. 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 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 sesgo en los resultados de la búsqueda. No hay un valor predeterminado.

    Si el nombre del país del campo de dirección de la respuesta coincide con 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 "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 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 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 atribuciones.