Primeros pasos

En esta guía se presentan las características de Google Places API for Android y se indica cómo configurar la aplicación para usar la API.

1. Introducción y conceptos
2. Información general de la API
3. Versiones admitidas de la plataforma de Android
4. Configurar tu aplicación
1. Configurar Google Play Services
2. Agregar tu clave de la API
3. Solicitar un aumento de los límites de uso
5. Conectarse a la Places API

Introducción y conceptos

Los puntos de entrada principales de Google Places API for Android son el widget de la IU de PlacePicker, el widget de la IU de Autocomplete, la GeoDataApi y la PlaceDetectionApi.

Al usar Google Places API for Android, puedes compilar aplicaciones basadas en la ubicación que responden de manera contextual a los negocios locales y a otros sitios cerca del dispositivo. Esto significa que puedes compilar aplicaciones completas basadas en sitios que tienen alguna importancia para el usuario a fin de complementar sin complicaciones los servicios basados en la ubicación geográfica ofrecidos por los servicios de ubicación de Android.

Un sitio se define como un espacio físico que tiene un nombre. Otra manera de definir un sitio es cualquier lugar que puedes encontrar en un mapa. Algunos ejemplos son los negocios locales, los puntos de interés y las ubicaciones geográficas. En la API, un sitio se representa mediante la interfaz Place. Esta incluye información como el nombre del sitio y su dirección, la ubicación geográfica, el id. de sitio, el número telefónico, el tipo de sitio, la dirección URL del sitio web, entre otros datos.

Nota: Siempre en que tu app se muestre información sobre sitios obtenida de la Google Places API for Android, la app también debe mostrar todas las atribuciones relevantes que muestra la API. Consulta la documentación sobre la visualización de atribuciones.

Información general de la API

Ayuda a los clientes a explorar el sitio en el que se encuentran y lo que hay a su alrededor:

• Usa el widget de la IU del seleccionador de sitios incorporado, que permite a los usuarios seleccionar un sitio en un mapa interactivo.
• Obtiene el sitio actual; es decir, el sitio de la última ubicación conocida del dispositivo. La API devuelve una lista de sitios posibles e indica la probabilidad relativa de cada uno de ellos.
• Facilita el ingreso de nombres de sitios y direcciones: autocompleta las consultas de los usuarios a medida que escriben. Usa el widget de IU de autocompletado o llama a la API para predicciones de sitios.
• Recupera y muestra mucha información sobre un sitio.
• Acceder a fotos de un sitio en alta definición.

Diferencia tu aplicación suministrando información local actualizada:

• Agrega un sitio a la base de datos de Google Places, a fin de recuperarlo de inmediato desde tu propia aplicación y visualizarlo en otras aplicaciones tras una moderación.
• Informa un sitio para indicar que el dispositivo se encuentra actualmente en un sitio en particular.
• Almacena el place ID exclusivo de uno o más sitios y úsalo para recuperar información sobre el sitio a pedido.

Entre otras características importantes de la API, se encuentran las siguientes:

• Detección precisa del sitio con baja potencia mediante la exploración de wifi.
• Almacenamiento en caché en el dispositivo: Es posible que la mayoría de las solicitudes de Google Places API for Android incluyan un recorrido de ida y vuelta a un servidor de Google; sin embargo, también es posible almacenar datos en caché a nivel local durante 30 días.

Versiones admitidas de la plataforma de Android

Google Places API for Android está disponible para todas las versiones de Android que admite Google Play Services. Consulta la guía de Android sobre la compatibilidad con diferentes versiones de la plataforma.

Configurar tu aplicación

Los siguientes pasos de configuración son obligatorios para todas las aplicaciones que usan Google Places API for Android.

Configurar Google Play Services

Para acceder a Google Places API for Android, el proyecto de desarrollo de tu aplicación debe incluir Google Play Services. Descarga e instala el componente de Google Play Services mediante el Administrador de SDK, y agrega la biblioteca a tu proyecto. Para obtener más detalles, consulta la guía de Android sobre la configuración de Google Play Services.

Agregar tu clave de la API

Nota: Necesitas una clave de API con restricciones de Android, no restricciones de navegador. Puedes usar la misma clave de API para tus aplicaciones de la Google Maps Android API v2 y tus aplicaciones de Google Places API for Android.

Si aún no has obtenido una clave de la API ni habilitado la Google Places API for Android, sigue las instrucciones de la guía de suscripción para obtener una ahora mismo.

Agrega tu clave de la API al manifiesto de tu aplicación; para ello, reemplaza YOUR_API_KEY por tu propia clave de la API, tal como se muestra en el siguiente ejemplo de código:

<application>
  ...
  <meta-data
      android:name="com.google.android.geo.API_KEY"
      android:value="YOUR_API_KEY"/>
</application>

Solicitar un aumento de los límites de uso

El uso de la Google Places API for Android es gratuito e ilimitado para todas las aplicaciones. Sin embargo, para garantizar el uso justo a través de todas las aplicaciones, existen límites de consulta por niveles según servicios específicos en algunos métodos.

Google Places API for Android impone un límite predeterminado de 1000 solicitudes por un período de 24 horas. Si en tu aplicación se excede el límite, esta comenzará a exhibir errores.

Existe un punto de control adicional cuando la aplicación alcanza 150 000 solicitudes por período de 24 horas. Si en tu aplicación se excede el límite, esta comenzará a exhibir errores nuevamente.

Sigue los pasos necesarios para aumentar tu límite con anticipación si esperas exceder el número predeterminado de solicitudes permitidas. Consulta las instrucciones de la guía de límites de uso.

Conectarse a la Places API

Nota: Este paso no es necesario si solo usas el seleccionador de sitios y no empleas ninguna otra parte de Google Places API for Android. En el caso del widget de la IU del seleccionador de sitios, no necesitas conectarte al cliente de Google Play Services.

Las siguientes interfaces proporcionan los puntos de entrada principal a Google Places API for Android:

• La GeoDataApi brinda acceso a la base de datos de información sobre negocios y sitios locales de Google.
• La PlaceDetectionApi proporciona acceso rápido al sitio actual del dispositivo y ofrece la oportunidad de informar la ubicación del dispositivo en un sitio en particular.

Para conectarte a las API, debes crear una instancia del cliente de la Google Play Services API. En el método onCreate() de tu fragmento o actividad, crea una instancia de cliente de la API de Google mediante GoogleApiClient.Builder. Usa el generador para agregar las API obligatorias, como se muestra en el siguiente ejemplo de código:

import com.google.android.gms.common.api.GoogleApiClient;
import com.google.android.gms.common.api.GoogleApiClient.OnConnectionFailedListener;
import android.support.v4.app.FragmentActivity;

public class MyActivity extends FragmentActivity 
        implements OnConnectionFailedListener {
    private GoogleApiClient mGoogleApiClient;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mGoogleApiClient = new GoogleApiClient
                .Builder(this)
                .addApi(Places.GEO_DATA_API)
                .addApi(Places.PLACE_DETECTION_API)
                .enableAutoManage(this, this)
                .build();
    }

    // TODO: Please implement GoogleApiClient.OnConnectionFailedListener to
    // handle connection failures.
}

Tal como se indica en el ejemplo de código, la clase Places proporciona tokens que puedes pasar a GoogleApiClient.Builder para habilitar la GeoDataApi y la PlaceDetectionApi.

Para obtener información detallada sobre cómo usar el cliente, consulta la guía de Android sobre el acceso a las API de Google. En particular, consulta las guías sobre cómo iniciar una conexión y manejar fallas de conexión para obtener más información sobre addConnectionCallbacks() y addOnConnectionFailedListener().