Place Autocomplete (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web

El servicio 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 de Autocomplete (nuevo) puede buscar coincidencias para palabras completas y subcadenas de la entrada para resolver nombres de lugares, direcciones y Plus Codes. Por lo tanto, las aplicaciones pueden enviar consultas a medida que el usuario escribe para proporcionar sugerencias de lugares sobre la marcha.

Las sugerencias de lugares son lugares, como empresas, direcciones y puntos 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 con una cadena que contiene una entrada del usuario parcial, "Spagh", con el área de búsqueda limitada a la ciudad de Nueva York. Luego, la respuesta contiene una lista de sugerencias de lugares que coinciden con la cadena de búsqueda y el área de búsqueda, como el restaurante llamado "Cafe Spaghetti", junto con detalles sobre el lugar.

Las sugerencias de lugares que se muestran están diseñadas para que el usuario las vea y seleccione el lugar deseado. Puedes realizar una solicitud de Place Details (New) para obtener más información sobre cualquiera de las sugerencias de lugares que se muestran.

Solicitudes a Autocomplete (nuevo)

Para crear una solicitud de autocompletado, llama a un método en GMSPlaceClient. Puedes pasar parámetros en el objeto GMSAutocompleteRequest. La respuesta proporciona sugerencias de Autocomplete dentro de un objeto GMSAutocompletePlaceSuggestion.

Se requieren la clave de API y los parámetros query. También puedes incluir GMSAutocompleteSessionToken para asociar solicitudes con una sesión de facturación y GMSAutocompleteFilter para aplicarlas 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 northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051)
let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds)
    
let request = GMSAutocompleteRequest(query:"Spagh")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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

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

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)

La función Autocomplete muestra un array de hasta cinco instancias de GMSAutocompleteSuggestion. El array contiene lo siguiente:

  • placeID
  • types: Son los tipos que se aplican a este lugar.
  • distanceMeters: Distancia desde el origen.
  • attributedFullText: Es el texto completo legible por humanos de una sugerencia.
  • attributedPrimaryText: Es el texto principal legible por humanos de una sugerencia.
  • attributedSecondaryText: Es el texto secundario legible por humanos de una sugerencia.
  • structuredFormat: Es el nombre específico y el texto que desambigua, como la ciudad o la región.

Parámetros obligatorios

consulta

Es la cadena de texto en la que se realizará la búsqueda. Especifica palabras completas y subcadenas, nombres de lugares, direcciones y Plus Codes. El servicio de 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 un tipo principal único de los tipos Tabla A o Tabla B asociados con él. 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. Para restringir los resultados a un tipo principal o tipos principales, pasa 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 especificados para incluirse 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 los tipos no reconocidos.

países

Incluye solo los resultados de la lista de regiones especificadas, que se especifican como un array de hasta 15 valores de dos caracteres de ccTLD ("dominio de nivel superior"). 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" ];

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

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

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

inputOffset

Es 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. 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.

  • locationBias especifica un área para la búsqueda. 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.

  • locationRestriction especifica un área para la búsqueda. No se muestran resultados fuera del área especificada.

Especifica la región locationBias o locationRestriction 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. Para locationRestriction, debes establecer el radio en un valor mayor que 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);

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

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 diagonalmente opuestos. 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, 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.

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

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

Swift

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

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

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

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

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

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 de dos caracteres de ccTLD ("dominio de nivel superior"). La mayoría de los códigos 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 de “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 a Autocomplete (nuevo) como "sesiones". Autocomplete (nuevo) usa tokens de sesión para agrupar las fases de consulta y selección de la búsqueda con autocompletado de un usuario en una sesión discreta para realizar la facturación correspondiente. Para obtener más información, consulta Tokens de sesión.

Ejemplos de Autocomplete (nuevo)

Usa locationRestriction y locationBias

Autocomplete (nuevo) usa la polarización de IP de forma predeterminada para controlar el área de búsqueda. Con el sesgo de IP, la API usa la dirección IP del dispositivo para sesgar 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 en la que se realizará la búsqueda. 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:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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

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

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 geográfica, la 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. 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:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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

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

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 types para restringir los resultados de una solicitud a 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 types 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
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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

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

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

Cómo usar el 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 del origen al 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
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))")
        }
      }
    })

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

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

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 muestres sugerencias del servicio Autocomplete (nuevo) sin un mapa, debes incluir el logotipo de Google intercalado con el campo o los resultados de la búsqueda. Para obtener más información, consulta Cómo mostrar el logotipo y las atribuciones de Google.