Autocompletar (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Autocomplete (nuevo) devuelve predicciones de lugares en respuesta a una solicitud que incluye una cadena de búsqueda de texto y límites geográficos que controlan el área de búsqueda. La función de autocompletar puede coincidir con palabras completas y subcadenas de la entrada, para resolver nombres de lugares, direcciones y Plus Codes. Tu aplicación puede enviar consultas a medida que el usuario escribe, para proporcionar predicciones de lugares sobre la marcha y de consulta.

Por ejemplo, puedes llamar a Autocomplete utilizando como entrada un string que contiene una entrada parcial del usuario, "Sicilian piz", con el área de búsqueda limitado a San Francisco, CA. La respuesta luego contiene una lista de lugares predicciones que coinciden con la cadena y el área de búsqueda, como el restaurante, llamada "Sicilian Pizza Kitchen".

Las predicciones del sitio mostradas están diseñadas para ser presentadas al usuario para ayudar a ellos a la hora de seleccionar el lugar deseado. Puedes hacer una Place Details (Nuevo) para obtener más información sobre ninguna de las predicciones de sitios mostradas.

Nota: Autocomplete (nuevo) está disponible en el SDK de Places. para Android 3.5.0 y versiones posteriores. Para obtener más información, consulta Elige tu SDK versión.

Solicitudes a Autocomplete (nuevas)

Tu app puede obtener una lista de nombres de lugares previstos. direcciones de la API de Autocomplete con la llamada PlacesClient.findAutocompletePredictions(), pasar un FindAutocompletePredictionsRequest . El siguiente ejemplo muestra una llamada completa a PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Nota: Llamadas realizadas con Place Autocomplete widgets llamar siempre a Place Autocomplete, no Place Autocomplete (nuevo); las llamadas a widgets no se ven afectadas con el método de inicialización.

Nota: Para obtener más información sobre cómo inicializar PlacesClient, consulta Inicializa el cliente de la API de Places.

Puedes usar un CancellationToken para intentar cancelar una solicitud a cualquiera de las clases de solicitud (por ejemplo, FetchPlaceRequest). La cancelación se realiza sobre la base del mejor esfuerzo. Una vez que se emite una solicitud de cancelación, no se devuelve ninguna respuesta. Emitir un token de cancelación NO garantiza que una solicitud en particular se cancelará y es posible que se te cobre la solicitud incluso si no se muestra una respuesta inicial.

Respuestas de Autocomplete (nuevo)

La API muestra un FindAutocompletePredictionsResponse en una Task. El FindAutocompletePredictionsResponse contiene una lista de hasta cinco AutocompletePrediction objetos que representan lugares de predicción. La lista puede estar vacía, si no hay lugar conocido correspondiente a la consulta y los criterios de filtro.

Para cada sitio de predicción, puedes realizar una llamada a los siguientes métodos a fin de recuperar datos de sitios detalles:

• getFullText(CharacterStyle) muestra el texto completo de una descripción de lugar. Esta es una combinación texto principal y secundario. Ejemplo: "Torre Eiffel, Avenue Anatole France, París, Francia”. Además, este método te permite destacar las secciones de la descripción que coincida con la búsqueda con el estilo que elijas, mediante CharacterStyle. El parámetro CharacterStyle es opcional. Establécela en null si no necesitas cualquier resaltado.
• getPrimaryText(CharacterStyle) devuelve el texto principal que describe un lugar. Por lo general, es el nombre del en un lugar específico. Ejemplos: “Torre Eiffel” y “Calle Pitt 123”.
• getSecondaryText(CharacterStyle) muestra el texto secundario de una descripción de lugar. Esto es útil para ejemplo, como segunda línea cuando se muestren las predicciones de autocompletar. Ejemplos: “Avenida Anatole France, París, Francia” y “Sídney, Nueva Gales del Sur”.
• getPlaceId() muestra el ID de lugar del sitio de predicción. Un ID de lugar es una cadena identificador que identifica de forma exclusiva un sitio, que puedes utilizar para recuperar el Place de ese objeto de nuevo más adelante. Para obtener más información sobre los IDs de lugar en Autocomplete, consulta Place Details (Nuevo). En general información sobre los IDs de lugar, consulta la sección ID de lugar descripción general.
• getTypes() muestra la lista de tipos de lugares asociados con este sitio.
• getDistanceMeters() devuelve la distancia en línea recta en metros entre este lugar y las el origen especificado en la solicitud.

Parámetros obligatorios

• Consulta

  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) devuelve posibles coincidencias en función de esta cadena y ordena los resultados según la relevancia percibida.

  Para configurar el parámetro de consulta, llama a setQuery(). cuando compiles el objeto FindAutocompletePredictionsRequest.

Parámetros opcionales

• Tipos principales

  Una lista de hasta cinco tipos de valores de tipos Tabla A o la Tabla B que se usa para filtrar los sitios devueltos en la respuesta. Un sitio debe coincidir con uno de los valores de tipo primario especificado que se incluirán en la respuesta.

  Un lugar solo puede tener un único tipo principal de tipos Tabla A o la Tabla B asociada con él. Por ejemplo, el tipo principal podría ser "mexican_restaurant" o "steak_house"

  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.

  Para establecer el parámetro de tipos principales, llama a setTypesFilter(). cuando compiles el objeto FindAutocompletePredictionsRequest.

• Países

  Incluye solo los resultados de la lista de países especificados, que se especifica en una lista de hasta 15 ccTLD ("dominio de nivel superior") valores de dos caracteres. Si se omite, no se aplican restricciones a la respuesta. Por ejemplo: para limitar las regiones a Alemania y Francia:

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

  Para establecer el parámetro countries, llama a setCountries(). cuando compiles el objeto FindAutocompletePredictionsRequest.

• Ajuste de entrada

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

  Para establecer el parámetro de desplazamiento de entrada, llama a setInputOffset(). cuando compiles el objeto FindAutocompletePredictionsRequest.

• Sesgo o restricción de la ubicación

  Puedes especificar un sesgo o una restricción de ubicación, pero no ambas, para definir el área de búsqueda. Piensa en la restricción de ubicación como una especificación la región en la que deben encontrarse los resultados y el sesgo de ubicación y se especifica la región a la que deben estar los resultados cerca. La diferencia clave es que con sesgo de ubicación, es posible que aún se devuelvan resultados fuera de la región especificada.

  • Sesgo de ubicación

    Especifica un área de búsqueda. La ubicación es un sesgo, no una restricción, por lo que los resultados fuera del área especificada.

    Para establecer el parámetro de sesgo de ubicación, llama a setLocationBias(). cuando compiles el objeto FindAutocompletePredictionsRequest.

  • Restricción de ubicación

    Especifica un área de búsqueda. Los resultados fuera del área especificada no se muestran que se devuelven.

    Para establecer el parámetro de restricción de ubicación, llama a setLocationRestriction(). cuando compiles el objeto FindAutocompletePredictionsRequest.

  Especifica el sesgo o la región de restricción de la ubicación como una una ventana gráfica 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 las restricciones de ubicación, debe establecer el radio en un valor superior a 0.0. De lo contrario, la solicitud muestra ningún resultado.

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

    Nota: Los tipos de personalización admitidos varían según la versión del SDK. que estás usando. CircularBounds solo está disponible en Autocomplete (nuevo).
    • 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 intervalo de longitud está vacío.

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

• Origen

  Punto de origen a partir del cual se calcula la distancia en línea recta al destino (al que se accede mediante getDistanceMeters()). Si este valor es se omite, no se devolverá la distancia en línea recta. Se debe especificar como coordenadas de latitud y longitud:

  Para establecer el parámetro de origen, llama a setOrigin(). cuando compiles el objeto FindAutocompletePredictionsRequest.

• Código de la región

  El código de región que se usa para dar formato a la respuesta, incluido el formato de dirección, especificado como una ccTLD ("dominio de nivel superior") un valor de dos caracteres. 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 el código ISO 3166-1 es "gb" (técnicamente para el del "Reino Unido de Gran Bretaña e Irlanda del Norte").

  Nota: El código de región tiene como objetivo representar la región en la que se origina la solicitud. no es necesariamente la región de destino de la consulta.

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

  Para establecer el parámetro del código de región, llama a setRegionCode(). cuando compiles el objeto FindAutocompletePredictionsRequest.

• Token de sesión

  Los tokens de sesión son cadenas generadas por el usuario que hacen un seguimiento Las llamadas de Autocomplete (nuevas) se consideran "sesiones". Autocomplete usa tokens de sesión para agrupar las fases de consulta y selección de una búsqueda de autocompletado del usuario en una sesión discreta para con fines de facturación. La sesión comienza cuando usuario comienza a escribir una consulta y termina cuando selecciona un lugar. Cada sesión puede tener varias búsquedas, seguidas de una selección de lugar. Cuando una sesión haya concluido, el token ya no es válido; la app debe generar un token nuevo para cada sesión. Recomendamos usar tokens de sesión para todas las actividades sesiones de autocompletado (cuando incorporas un fragmento o inicias el autocompletado usando un intent, la API se encarga de esto automáticamente).

  El autocompletado utiliza una AutocompleteSessionToken para identificar cada sesión. La aplicación deberá pasar un nuevo token de sesión al cada nueva sesión, pasa ese mismo token, junto con un ID de lugar, en la llamada posterior a fetchPlace() para recuperar los detalles de Place del lugar que seleccionó el usuario.

  Para establecer el parámetro del token de sesión, llama a setSessionToken(). cuando compiles el objeto FindAutocompletePredictionsRequest.

  Para obtener más información, consulta Tokens de sesión.

Ejemplos de Autocomplete (nuevo)

Cómo usar la restricción y el sesgo de ubicación

Autocomplete (nuevo) utiliza la personalización de IP de forma predeterminada para controlar el área de búsqueda. Con la personalización de IP, la API utiliza la dirección IP de la para sesgar los resultados. Si lo deseas, puedes usar la ubicación restricción o sesgo de ubicación, pero no ambos, para especificar un área de búsqueda.

La restricción de ubicación especifica el área a buscar. Resultados fuera del especificado no se devuelven. 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 5000 metros centrado en San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Con el sesgo de ubicación, la ubicación funciona como un sesgo, lo que significa que se obtienen resultados cerca de la se puede mostrar la ubicación especificada, incluso resultados fuera de la ubicación especificada en una sola área de almacenamiento en etapa intermedia. En el siguiente ejemplo, se cambia la solicitud anterior para usar el sesgo de ubicación:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Usar tipos principales

Usa el parámetro primary types para restringir los resultados de un que tu solicitud sea de un tipo determinado, como se indica en la Tabla A y Table 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 “Soccer” y usa el método principal Parámetro de tipos para restringir los resultados a establecimientos de tipo "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Si omites el parámetro de tipos primarios, los resultados pueden incluir establecimientos de un tipo que quizás no desees, como "athletic_field".

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 del origen al destino en la respuesta (al que se accede con getDistanceMeters()). En este ejemplo, se establece el origen en el centro de San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Atribuciones

Puedes utilizar Autocomplete (nuevo), incluso sin un mapa. Si muestra un mapa, debe ser de Google Maps. Cuando muestres predicciones de el servicio Autocomplete (nuevo) sin un mapa, Debe incluir el logotipo de Google que se muestra intercalado con los resultados o campos de búsqueda. Para más información, consulta Mostrar el logotipo de Google y de los usuarios.