Place Autocomplete (nuevo)

El servicio de Autocomplete (nuevo) es una API de iOS que muestra sugerencias de lugares en respuesta a una solicitud. En la solicitud, especifica una cadena de búsqueda de texto y límites geográficos que controlen el área de búsqueda.

El servicio Autocomplete (nuevo) puede coincidir con palabras completas y subcadenas de la entrada para resolver nombres de lugares, direcciones y Plus Codes. Así, las aplicaciones pueden enviar consultas a medida que el usuario escribe para proporcionar sugerencias de lugares en el momento.

Las sugerencias de lugares son lugares, como empresas, direcciones y lugares de interés, que se basan en la cadena de texto de entrada y el área de búsqueda especificadas.

Por ejemplo, llamas a la API usando como entrada una string que contiene una entrada parcial del usuario, "Sicilian piz", con el área de búsqueda limitada a San Francisco, CA. La respuesta contiene una lista de sugerencias de lugares que coinciden con la cadena y el área de búsqueda, como el restaurante llamado "Sicilian Pizza Kitchen", junto con detalles sobre el lugar.

Las sugerencias de lugares que se muestran están diseñadas para presentarse al usuario, de modo que pueda seleccionar el lugar deseado. Puedes realizar una solicitud a Place Details (nuevo) para obtener más información sobre cualquiera de las sugerencias de lugares que se muestran.

Nota: Debes habilitar la API de autocompletado original para usar la funcionalidad del widget. La API original y la nueva se pueden habilitar al mismo tiempo. Consulta la guía de migración de Place Autocomplete (nuevo) para obtener más información.

Solicitudes de Autocomplete (nuevas)

Llama a un método en GMSPlaceClient para crear una solicitud de autocompletado. Puedes pasar parámetros del objeto GMSAutocompleteRequest. La respuesta proporciona sugerencias de Autocomplete dentro de un objeto GMSAutocompletePlaceSuggestion.

La clave de API y los parámetros query son obligatorios. También puedes incluir GMSAutocompleteSessionToken para asociar solicitudes con una sesión de facturación y GMSAutocompleteFilter para aplicar a los resultados.

Para obtener más información sobre los parámetros obligatorios y opcionales, consulta la sección de parámetros de este documento.

Swift

let token = GMSAutocompleteSessionToken()

let northEastBounds = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWestBounds = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northEastBounds, southWestBounds)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective‑C

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

Respuestas de Autocomplete (nuevo)

El autocompletado muestra un array de hasta cinco instancias de GMSAutocompleteSuggestion. El array contiene lo siguiente:

• placeID
• types: Tipos que se aplican a este lugar.
• distanceMeters: Distancia desde el origen.
• attributedFullText: Es el texto completo legible de una sugerencia.
• attributedPrimaryText: Es el texto principal legible de una sugerencia.
• attributedSecondaryText: Es el texto secundario legible de una sugerencia.
• structuredFormat: Es el nombre específico y el texto que genera ambigüedades, como ciudad o región.

Parámetros obligatorios

búsqueda

Cadena de texto en la que se realiza la búsqueda Especifica palabras completas y subcadenas, nombres de lugares, direcciones y Plus Codes. El servicio Autocomplete (nuevo) muestra posibles coincidencias en función de esta cadena y ordena los resultados según la relevancia percibida.

Parámetros opcionales

Tipos

Un lugar solo puede tener asociado un tipo principal principal de los tipos Tabla A o Tabla B. Por ejemplo, el tipo principal podría ser mexican_restaurant o steak_house.

De forma predeterminada, la API muestra todos los lugares según el parámetro input, independientemente del valor de tipo principal asociado con el lugar. Restringe los resultados para que sean de un tipo primario o de un tipo primario determinado pasando el parámetro types.

Usa este parámetro para especificar hasta cinco valores de tipo de la Tabla A o la Tabla B. Un lugar debe coincidir con uno de los valores de tipo principal especificado que se incluirán en la respuesta.

La solicitud se rechaza con un error INVALID_REQUEST en los siguientes casos:

• Se especifican más de cinco tipos.
• Se especifican todos los tipos no reconocidos.

países

Incluye solo los resultados de la lista de regiones especificadas, indicada como un array de hasta 15 ccTLD ("dominio de nivel superior") de dos caracteres. Si se omite, no se aplican restricciones a la respuesta. Por ejemplo, para limitar las regiones a Alemania y Francia, haz lo siguiente:

Swift

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

Objective‑C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

GooglePlacesSwift

let filter = AutocompleteFilter(countries: ["DE", "FR"])
  

Si especificas locationRestriction y countries, los resultados se ubicarán en el área de intersección de las dos configuraciones.

inputOffset

El desplazamiento de caracteres Unicode basado en cero que indica la posición del cursor en input La posición del cursor puede influir en las predicciones que se muestran. Si está vacío, el valor predeterminado es la longitud de input.

locationBias o locationRestriction

Puedes especificar locationBias o locationRestriction, pero no ambos, para definir el área de búsqueda. Considera que locationRestriction especifica la región en la que deben estar los resultados y locationBias la región a la que los resultados deben estar cerca, pero puede estar fuera de ella.

Nota: Si omites locationBias y locationRestriction, la API usa la personalización de IP de forma predeterminada. Con la personalización de IP, la API usa la dirección IP del dispositivo para personalizar los resultados.

• locationBias especifica un área para buscar. Esta ubicación sirve como una personalización, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluso resultados fuera del área especificada.

• locationRestriction especifica un área para buscar. No se muestran resultados fuera del área especificada.

Especifica la región locationBias o locationRestriction como una vista del puerto 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 valor predeterminado es 0.0. Para locationRestriction, debes establecer el radio en un valor superior a 0.0. De lo contrario, la solicitud no muestra resultados.

Por ejemplo:

Swift

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

Objective‑C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

GooglePlacesSwift

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

Un rectángulo es un viewport de latitud y longitud, representado como dos puntos low y high opuestos en diagonal. Un viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben variar entre -90 y 90 grados inclusive, y los límites de longitud deben variar entre -180 y 180 grados inclusive:

• Si low = high, el viewport consta de ese solo 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.

low y high se deben completar, y el cuadro representado no puede estar vacío. Un viewport vacío genera un error.

Por ejemplo, este viewport abarca por completo la ciudad de Nueva York:

Swift

let high = CLLocationCoordinate2DMake(40.477398, -74.259087)
let low = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

Objective‑C

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

GooglePlacesSwift

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

origin

Es el punto de origen desde el que se calcula la distancia en línea recta hasta el destino (se muestra como distanceMeters). Si se omite este valor, no se mostrará la distancia en línea recta. Se deben especificar como coordenadas de latitud y longitud:

Swift

let filter = GMSAutocompleteFilter()
filter.origin =  CLLocation(latitude: 37.395804, longitude:  -122.077023)
 

Objective‑C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];

GooglePlacesSwift

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude:  -122.077023))
  

regionCode

Es el código de región que se usa para dar formato a la respuesta, especificado como un valor ccTLD ("dominio de nivel superior") de dos caracteres. La mayoría de los códigos de ccTLD 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 del "Reino Unido de Gran Bretaña e Irlanda del Norte").

Si especificas un código de región no válido, la API mostrará un error INVALID_ARGUMENT. El parámetro puede afectar los resultados según la ley aplicable.

sessionToken

Los tokens de sesión son cadenas generadas por el usuario que hacen un seguimiento de las llamadas de Autocomplete (nuevo) como “sesiones”. Autocomplete (nuevo) usa tokens de sesión para agrupar las fases de búsqueda y selección de una búsqueda de autocompletado del usuario en una sesión discreta con fines de facturación. Para obtener más información, consulta Tokens de sesión.

Ejemplos de Autocomplete (nuevo)

Cómo usar locationRestriction y locationBias

Autocomplete (nuevo) usa la personalización de IP de forma predeterminada para controlar el área de búsqueda. Con la personalización de IP, la API usa la dirección IP del dispositivo para personalizar los resultados. De manera opcional, puedes usar locationRestriction o locationBias, pero no ambos, para especificar un área de búsqueda.

La restricción de ubicación especifica el área a buscar. No se muestran resultados fuera del área especificada. En el siguiente ejemplo, se usa la restricción de ubicación para limitar la solicitud a una restricción de ubicación circular con un radio de 5,000 metros centrado en San Francisco:

Swift

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
  })

Objective‑C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Con la personalización de ubicación, la ubicación funciona como una personalización, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluso resultados fuera del área especificada. En el siguiente ejemplo, se cambia la solicitud anterior para usar el sesgo de ubicación:

Swift

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective‑C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Tipos de uso

Usa el parámetro de tipos para restringir los resultados de una solicitud a fin de que sean de un tipo determinado, como se indica en la Tabla A y la Tabla B. Puedes especificar un array de hasta cinco valores. Si se omite, se muestran todos los tipos.

En el siguiente ejemplo, se especifica una cadena de consulta de "Fútbol" y se usa el parámetro de tipos para restringir los resultados a establecimientos de tipo "sporting_goods_store":

Swift

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
    
let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective‑C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
    

Usar origen

Cuando incluyes el parámetro origin en la solicitud, especificado como coordenadas de latitud y longitud, la API incluye la distancia en línea recta desde el origen hasta el destino en la respuesta. La respuesta muestra la distancia como distanceMeters.

En este ejemplo, se establece el origen en el centro de San Francisco:

Swift

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin
    
let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective‑C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

GooglePlacesSwift

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Atribuciones

Puedes usar Autocomplete (nuevo), incluso sin un mapa. Si muestras un mapa, debe ser un mapa de Google. Cuando muestras sugerencias del servicio Autocomplete (nuevo) sin un mapa, debes incluir el logotipo de Google que se muestra intercalado con el campo o los resultados de la búsqueda. Para obtener más información, consulta Cómo mostrar el logotipo de Google y las atribuciones.