Eso es todo.

Para comenzar a desarrollar, consulta nuestra documentación para desarrolladores.

Activar la Google Places API for Android

Para que puedas comenzar, te proporcionaremos orientación en la consola para desarrolladores de Google a fin de que hagas primero algunas acciones:

  1. Crear o seleccionar un proyecto
  2. Activar la Google Places API for Android
  3. Crear claves correspondientes
Continuar

Autocompletado de sitios

El servicio de autocompletado de Google Places API for Android muestra predicciones del sitio en respuesta a consultas de búsqueda de usuarios. A medida que el usuario escribe, el servicio de autocompletado muestra sugerencias para lugares; por ejemplo, negocios, direcciones y puntos de interés.

Puedes agregar el autocompletado a tu app de las siguientes formas:

Agregar un widget de autocompletado

El widget de autocompletado es un cuadro de diálogo de búsqueda con funcionalidad de autocompletado incorporada. Cuando un usuario ingresa términos de búsqueda, el widget presenta una lista de lugares de predicción seleccionables. Cuando el usuario elige una opción, se muestra una instancia de Place, que tu app luego puede usar para obtener información sobre el lugar seleccionado.

Hay dos opciones para agregar el widget de autocompletado a tu app:

Opción 1: Incorporar un PlaceAutocompleteFragment o un SupportPlaceAutocompleteFragment

Para agregar un PlaceAutocompleteFragment a tu app:

  1. Agrega un fragmento al diseño XML de tu actividad.
  2. Agrega un receptor a tu actividad o fragmento.

Agregar PlaceAutocompleteFragment a una actividad

Para agregar PlaceAutocompleteFragment a una actividad, agrega un fragmento nuevo denominado com.google.android.gms.location.places.ui.PlaceAutocompleteFragment a un diseño XML. Por ejemplo:

<fragment
  android:id="@+id/place_autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.gms.location.places.ui.PlaceAutocompleteFragment"
  />

Nota: De forma predeterminada, el fragmento no tiene límite ni fondo. A fin de proporcionar una apariencia visual coherente, anida el fragmento dentro de otro elemento de diseño; por ejemplo, una CardView..

Agregar un PlaceSelectionListener a una actividad

El PlaceSelectionListener permite mostrar un sitio en respuesta a la selección que realiza el usuario. En el siguiente código, se muestra la manera de crear una referencia al fragmento y agregar un receptor a PlaceAutocompleteFragment:

PlaceAutocompleteFragment autocompleteFragment = (PlaceAutocompleteFragment)
getFragmentManager().findFragmentById(R.id.place_autocomplete_fragment);

autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
    @Override
    public void onPlaceSelected(Place place) {
        // TODO: Get info about the selected place.
        Log.i(TAG, "Place: " + place.getName());
    }

    @Override
    public void onError(Status status) {
        // TODO: Handle the error.
        Log.i(TAG, "An error occurred: " + status);
    }
  });

Usar SupportPlaceAutocompleteFragment (plataformas anteriores)

La Google Places API necesita el nivel de API 12 o uno superior para admitir objetos PlaceAutocompleteFragment. Si apuntas a una aplicación anterior al nivel de API 12, puedes acceder a la misma funcionalidad a través de la clase SupportPlaceAutocompleteFragment. También debes incluir la biblioteca de compatibilidad de Android v4. Para admitir versiones de Android anteriores al nivel de API 12, sigue estos pasos:

  • Extiende FragmentActivity o AppCompatActivity en tu actividad principal.
  • Usa SupportPlaceAutocompleteFragment en lugar de PlaceAutocompleteFragment.
  • Usa getSupportFragmentManager() en lugar de getFragmentManager().

Opción 2: Usar una intent para iniciar la actividad de autocompletado

Si deseas que tu app use un flujo de navegación diferente (por ejemplo, activar la experiencia de autocompletado a partir de un ícono en lugar de un campo de búsqueda), tu app puede iniciar el autocompletado por medio de una intent.

Nota: Estos pasos no son necesarios si incorporas un fragmento.

Para iniciar el widget de autocompletado por medio de una intent, sigue estos pasos:

  1. Usa PlaceAutocomplete.IntentBuilder para crear una intent y pasa el modo PlaceAutocomplete deseado. La intent debe llamar a startActivityForResult y pasar un código de solicitud que permita identificar tu intent.
  2. Anula el callback onActivityResult para recibir el sitio seleccionado.

Crear una intent de autocompletado

En el ejemplo siguiente, se muestra la manera de usar PlaceAutocomplete.IntentBuilder para crear una intent y, así, iniciar el widget de autocompletado como una intent:

int PLACE_AUTOCOMPLETE_REQUEST_CODE = 1;
...
try {
    Intent intent =
            new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                    .build(this);
    startActivityForResult(intent, PLACE_AUTOCOMPLETE_REQUEST_CODE);
} catch (GooglePlayServicesRepairableException e) {
    // TODO: Handle the error.
} catch (GooglePlayServicesNotAvailableException e) {
    // TODO: Handle the error.
}

Cuando uses una intent para iniciar el widget de autocompletado, puedes elegir entre los modos de visualización de superposición o pantalla completa. En las siguientes capturas de pantalla, se muestra cada modo de visualización respectivamente:

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
Figura 1: Widget de autocompletado en el modo de superposición. (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
Figura 2: Widget de autocompletado en el modo de pantalla completa (MODE_FULLSCREEN)

Anular el callback onActivityResult

Para recibir una notificación cuando un usuario ha seleccionado un sitio, tu app debe anular el callback onActivityResult() de la actividad y verificar el código de solicitud que pasaste para la intent, tal como se muestra en el siguiente ejemplo.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == PLACE_AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = PlaceAutocomplete.getPlace(this, data);
            Log.i(TAG, "Place: " + place.getName());
        } else if (resultCode == PlaceAutocomplete.RESULT_ERROR) {
            Status status = PlaceAutocomplete.getStatus(this, data);
            // TODO: Handle the error.
            Log.i(TAG, status.getStatusMessage());

        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
    }
}

Restringir los resultados de autocompletado

Puedes configurar el widget de autocompletado para restringir los resultados a una región geográfica específica o filtrar los resultados según uno o más tipos de sitios.

Restringir resultados según una región específica

Para restringir los resultados de autocompletado según una región geográfica específica:

  • Llama a setBoundsBias() en la instancia de PlaceAutocompleteFragment de tu app, o la instancia de IntentBuilder, y pasa una clase LatLngBounds. En el siguiente ejemplo de código, se muestra la manera de llamar a setBoundsBias() en una instancia de fragmento para restringir las sugerencias de autocompletado a una región de Sídney, Australia.
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

Filtrar resultados por tipo de sitio

Para filtrar los resultados de autocompletado según un tipo de sitio específico, llama a AutocompleteFilter.Builder para crear un nuevo AutocompleteFilter, y a setTypeFilter() para configurar el filtro que deseas usar. Luego, pasa el filtro a un fragmento o una intent.

En el siguiente ejemplo de código, se muestra la manera de configurar un AutocompleteFilter en un PlaceAutocompleteFragment para establecer un filtro que muestre solo resultados con una dirección exacta.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

autocompleteFragment.setFilter(typeFilter);

En el siguiente ejemplo de código, se muestra la manera de configurar un AutocompleteFilter en una intent a fin de establecer un filtro que devuelva solo resultados con una dirección exacta.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

Intent intent =
        new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                .setFilter(typeFilter)
                .build(this);

Para obtener información sobre los tipos de sitios, consulta la guía de tipos de sitios y AutocompleteFilter.Builder.

Obtener predicciones del sitio mediante programación

Puedes crear una IU de búsqueda personalizada como alternativa a la IU que se proporciona en el widget de autocompletado. Para ello, tu app debe obtener predicciones del sitio mediante programación. Tu app puede obtener una lista de nombres de sitios o direcciones de predicción a partir del servicio de autocompletado llamando a GeoDataApi.getAutocompletePredictions() y pasando los siguientes parámetros:

  • Obligatorio: una string de query que contenga el texto que ingresó el usuario.
  • Obligatorio: un objeto LatLngBounds que restrinja los resultados a un área específica establecida por límites de latitud y longitud.
  • Opcional: un AutocompleteFilter con un conjunto de tipos de sitios, que puedes usar para restringir los resultados a uno o más tipos de sitios. Se admiten los siguientes tipos de sitios:

    • TYPE_FILTER_NONE: filtro vacío; se muestran todos los resultados.
    • TYPE_FILTER_GEOCODE: devuelve solo resultados de geocodificación, en lugar de resultados de negocios. Usa esta solicitud para eliminar ambigüedades en los resultados en los cuales la ubicación especificada pueda ser indeterminada.
    • TYPE_FILTER_ADDRESS: muestra solo resultados de autocompletado con una dirección exacta. Usa este tipo cuando sepas que el usuario buscará una dirección especificada con precisión.
    • TYPE_FILTER_ESTABLISHMENT: muestra solo sitios correspondientes a negocios.
    • TYPE_FILTER_REGIONS: muestra solo sitios que coinciden con uno de los siguientes tipos:

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIES: muestra solo resultados que coinciden con locality o administrative_area_level_3.

Para obtener información sobre los tipos de sitios, consulta la guía de tipos de sitios y [AutocompleteFilter.Builder](/android/reference/com/google/android/gms/location/places/AutocompleteFilter.Builder.html#setTypeFilter(int).

En el siguiente ejemplo, se muestra una llamada simplificada a GeoDataApi.getAutocompletePredictions(). Para hallar un ejemplo completo, consulta las apps de ejemplo.

PendingResult<AutocompletePredictionBuffer> result =
    Places.GeoDataApi.getAutocompletePredictions(mGoogleApiClient, query,
        bounds, autocompleteFilter);

La API muestra una clase AutocompletePredictionBuffer en una clase PendingResult. La clase AutocompletePredictionBuffer contiene una lista de objetos AutocompletePrediction que representan sitios de predicción. El búfer puede estar vacío si no existe ningún sitio conocido que corresponda a la consulta y a los criterios de filtro.

Nota: A fin de evitar una pérdida de memoria, debes liberar el objeto AutocompletePredictionBuffer cuando tu app ya no lo necesite. Obtén más información sobre manejo de búferes.

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

  • getFullText(CharacterStyle matchStyle) muestra el texto completo de una descripción del sitio. Esto es una combinación del texto primario y secundario. Ejemplo: “Torre Eiffel, Avenue Anatole France, Paris, Francia”. Además, te permite destacar las secciones de la descripción que coincidan con la búsqueda con un estilo que elijas usando CharacterStyle. El parámetro CharacterStyle es opcional. Fíjalo en null si no necesitas destacar nada.
  • getPrimaryText(CharacterStyle matchStyle) muestra el texto principal que describe un sitio. Por lo general es el nombre del lugar. Ejemplos: “Torre Eiffel" y “Calle Pitt 123”.
  • getSecondaryText(CharacterStyle matchStyle) muestra el texto secundario de una descripción del sitio. Esto resulta útil, por ejemplo, como segunda línea cuando se muestran las predicciones de autocompletado. Ejemplos: “Avenida Anatole France, París, Francia” y “Sídney, Nueva Gales del Sur”.
  • getPlaceId() muestra el ID del sitio de predicción. El ID de sitio es un identificador textual que identifica de manera exclusiva un sitio y que puedes usar para recuperar el objeto Place nuevamente más tarde. Para obtener más información sobre los ID de sitio en Google Places API for Android, consulta Detalles e ID. de sitio. Para obtener información general sobre los ID de sitio, consulta la información general sobre ID de sitio.
  • getPlaceTypes() muestra la lista de los tipos de sitios relacionados con este sitio.

Límites de uso

Mostrar atribuciones en tu app

  • Si tu app usa el servicio de autocompletado mediante programación, tu IU debe mostrar una atribución “Con la tecnología de Google” o aparecer dentro de un mapa de la marca Google.
  • Si tu app usa el widget de autocompletado, no se requiere ninguna acción adicional (la atribución requerida se muestra de manera predeterminada). Si recuperas y muestras información adicional del sitio después de obtener un sitio mediante ID, también debes mostrar atribuciones de terceros.

Para obtener más detalles, consulta la documentación sobre atribuciones.

Solución de problemas

Si bien pueden producirse muchos errores diferentes, la mayoría de los que tu app puede experimentar se deben, por lo general, a errores de configuración (por ejemplo, se usó la clave de API incorrecta o la clave de API se configuróde forma incorrecta) o a errores de cuota (tu app excedió su cuota). Consulta Límites de uso para obtener más información sobre las cuotas.

Los errores que tienen lugar cuando se usan los controles de autocompletado se muestran en el callback onActivityResult(). Llama a PlaceAutocomplete.getStatus() para obtener el mensaje de estado para el resultado.

Enviar comentarios sobre...