Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Places API for Android

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou choisir un projet
  2. Activer Google Places API for Android
  3. Créer les clés appropriées
Continuer

Place Autocomplete

Le service Autocomplete (saisie semi-automatique) dans Google Places API for Android renvoie des lieux possibles en réponse à une requête de recherche de l'utilisateur. Lors de la frappe, le service de saisie semi-automatique renvoie des suggestions de lieux tels que des établissements, des adresses et des points d'intérêt.

Vous pouvez ajouter Autocomplete à votre application de plusieurs façons :

Ajouter un widget de saisie semi-automatique

Le widget Autocomplete est une zone de recherche avec une fonctionnalité de saisie semi-automatique intégrée. Lorsque l'utilisateur saisit des termes de recherche, le widget lui présente une liste de lieux à choisir. Lorsque l'utilisateur choisit une option, une instance Place est renvoyée. Votre application peut alors l'utiliser pour obtenir des informations détaillées sur le lieu sélectionné.

Deux options sont possibles pour ajouter un widget Autocomplete à votre application :

Option 1 : Intégrer un fragment PlaceAutocompleteFragment ou SupportPlaceAutocompleteFragment

Pour ajouter un fragment PlaceAutocompleteFragment à votre application, procédez comme suit :

  1. Ajoutez un fragment au fichier de disposition XML de votre activité.
  2. Ajoutez un écouteur à votre activité ou fragment.

Ajouter un fragment PlaceAutocompleteFragment à une activité

Pour ajouter un fragment PlaceAutocompleteFragment à une activité, ajoutez un nouveau fragment intitulé com.google.android.gms.location.places.ui.PlaceAutocompleteFragment à un fichier de disposition XML. Par exemple :

<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"
  />

Remarque : Par défaut, le fragment ne contient ni bordure, ni arrière-plan. Pour offrir une apparence visuelle cohérente, imbriquez le fragment dans un autre élément de disposition tel que CardView.

Ajouter un écouteur PlaceSelectionListener à une activité

L'écouteur PlaceSelectionListener se charge de renvoyer un lieu en réponse à la sélection de l'utilisateur. Le code suivant montre comment créer une référence au fragment et ajouter un écouteur à votre fragment 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);
    }
  });

Utiliser SupportPlaceAutocompleteFragment (anciennes plateformes)

Google Places API requiert une API de niveau 12 ou supérieur pour la prise en charge des objets PlaceAutocompleteFragment. Si vous ciblez une application antérieure à l'API niveau 12, vous pouvez accéder à la même fonctionnalité via la classe SupportPlaceAutocompleteFragment. Vous devez également inclure la bibliothèque de support Android v4. Pour prendre en charge les versions Android antérieures à l'API niveau 12, procédez comme suit :

  • Étendez FragmentActivity ou AppCompatActivity dans votre activité principale.
  • Utilisez SupportPlaceAutocompleteFragment au lieu de PlaceAutocompleteFragment.
  • Utilisez getSupportFragmentManager() au lieu de getFragmentManager().

Option 2 : Utiliser un intent pour lancer l'activité de saisie semi-automatique

Si vous souhaitez que votre application utilise un autre flux de navigation (par exemple, pour déclencher l'expérience de saisie semi-automatique à partir d'une icône au lieu d'un champ de recherche), votre application peut lancer la saisie semi-automatique en utilisant un intent.

Remarque : Cette procédure est inutile si vous souhaitez intégrer un fragment.

Pour lancer le widget de saisie semi-automatique en utilisant un intent, procédez comme suit :

  1. Utilisez PlaceAutocomplete.IntentBuilder pour créer un intent, en transmettant le mode PlaceAutocomplete voulu. L'intent doit appeler startActivityForResult, en transmettant un code de requête qui identifie votre intention.
  2. Ignorez le rappel onActivityResult pour recevoir le lieu sélectionné.

Créer un intent de saisie semi-automatique

L'exemple ci-dessous montre comment utiliser PlaceAutocomplete.IntentBuilder pour créer un intent afin de lancer le widget Autocomplete en tant qu'intention :

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

Lorsque vous utilisez un intent pour lancer le widget de saisie semi-automatique, vous pouvez choisir entre les modes d'affichage superposition ou plein écran. Les captures d'écran suivantes montrent respectivement chaque mode d'affichage :

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
Figure 1 : Widget Autocomplete en mode superposition (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
Figure 2 : Widget Autocomplete en mode plein écran (MODE_FULLSCREEN)

Ignorer le rappel onActivityResult

Pour recevoir une notification dès qu'un utilisateur a sélectionné un lieu, votre application doit ignorer le rappel onActivityResult() de l'activité, en vérifiant le code de requête que vous avez indiqué pour votre intent, comme indiqué dans l'exemple suivant.

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

Restreindre les résultats de la saisie semi-automatique

Vous pouvez définir le widget de saisie semi-automatique pour limiter les résultats à une région géographique donnée et/ou filtrer les résultats sur un ou plusieurs types de lieu.

Limiter les résultats à une région donnée

Pour limiter les résultats de la saisie semi-automatique à une région géographique donnée :

  • Appelez setBoundsBias() en dehors de l'instance PlaceAutocompleteFragment de votre application, ou de votre instance IntentBuilder, en transmettant un paramètre LatLngBounds. L'exemple de code suivant montre comment appeler setBoundsBias() sur une instance de fragment pour limiter les suggestions de saisie semi-automatique à la région de Sydney, en Australie.
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

Filtrer les résultats par type de lieu

Pour filtrer les résultats de la saisie semi-automatique en fonction d'un type de lieu spécifique, appelez AutocompleteFilter.Builder pour créer un nouveau AutocompleteFilter, en appelant setTypeFilter() pour définir le filtre à utiliser. Transmettez ensuite le filtre à un fragment ou un intent.

L'exemple de code suivant montre comment définir un AutocompleteFilter sur un fragment PlaceAutocompleteFragment afin de créer un filtre qui renvoie uniquement les résultats contenant une adresse précise.

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

autocompleteFragment.setFilter(typeFilter);

L'exemple de code suivant montre comment définir un AutocompleteFilter sur un intent afin de créer un filtre qui renvoie uniquement les résultats contenant une adresse précise.

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

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

Pour plus d'informations sur les types de lieu, voir le guide sur les types de lieu et AutocompleteFilter.Builder.

Obtenir des prédictions de lieu par programmation

Vous pouvez créer une UI de recherche personnalisée pour remplacer celle fournie par le widget de saisie semi-automatique. Pour ce faire, votre application doit recevoir des prédictions de lieu par programmation. Pour que votre application reçoive la liste des noms de lieu et/ou adresses possibles du service de saisie semi-automatique, appelez GeoDataApi.getAutocompletePredictions(), en indiquant les paramètres suivants :

  • Obligatoire : Une chaîne query contenant le texte saisi par l'utilisateur.
  • Obligatoire : Un objet LatLngBounds qui affine les résultats à une zone spécifique représentée par des valeurs de latitude et longitude.
  • Facultatif : Un paramètre AutocompleteFilter contenant un ensemble de types de lieu pouvant être utilisé pour limiter les résultats à un ou plusieurs types de lieu. Les types de lieu suivants sont pris en charge :

    • TYPE_FILTER_NONE – Filtre vide ; tous les résultats sont renvoyés.
    • TYPE_FILTER_GEOCODE – Renvoie uniquement des résultats de géocodage plutôt que des professionnels. Utilisez cette requête pour affiner les résultats lorsque le point géographique spécifié est indéterminé.
    • TYPE_FILTER_ADDRESS – Renvoie uniquement les résultats de la saisie semi-automatique avec une adresse précise. Utilisez ce type de requête lorsque vous savez que l'utilisateur recherche une adresse spécifiée complète.
    • TYPE_FILTER_ESTABLISHMENT – Renvoie uniquement les lieux représentant des professionnels.
    • TYPE_FILTER_REGIONS – Renvoie uniquement des lieux qui correspondent à l'un des types suivants :

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIES – Renvoie uniquement les résultats correspondant à locality ou administrative_area_level_3.

Pour plus d'informations sur les types de lieu, voir le guide sur les types de lieu et AutocompleteFilter.Builder.

L'exemple ci-dessous représente un appel simplifié à GeoDataApi.getAutocompletePredictions(). Pour un exemple complet, voir les exemples d'application.

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

L'API renvoie un AutocompletePredictionBuffer dans un PendingResult. Le paramètre AutocompletePredictionBuffer contient une liste des objets AutocompletePrediction représentant les lieux proposés. La mémoire tampon peut être vide s'il n'existe aucun lieu connu correspondant à la requête et aux critères de filtre.

Remarque : Pour empêcher les fuites de mémoire, vous devez libérer l'objet AutocompletePredictionBuffer lorsque votre application n'en a plus besoin. En savoir plus sur la gestion des tampons.

Pour chaque lieu proposé, vous pouvez appeler les méthodes suivantes afin d'extraire les détails du lieu :

  • getFullText(CharacterStyle matchStyle) renvoie le texte complet de la description du lieu. C'est une combinaison des champs de texte principaux et secondaires. Exemple : « Tour Eiffel, Avenue Anatole France, Paris, France ». Cette méthode vous permet également de mettre en surbrillance les sections de la description correspondant à la recherche dans le style de votre choix, en utilisant CharacterStyle. Le paramètre CharacterStyle est facultatif. Définissez-le sur null si vous n'avez pas besoin de la surbrillance.
  • getPrimaryText(CharacterStyle matchStyle) renvoie le texte principal décrivant un lieu. Il s'agit généralement d'un nom de lieu. Exemples : « Tour Eiffel » et « 123 Pitt Street ».
  • getSecondaryText(CharacterStyle matchStyle) renvoie le texte secondaire de la description du lieu. Utile, par exemple, comme seconde ligne lors de l'affichage des prédictions de saisie semi-automatique. Exemples : « Avenue Anatole France, Paris, France » et « Sydney, Nouvelle-Galles du Sud ».
  • getPlaceId() renvoie l'identifiant du lieu proposé. Un identifiant de lieu est un identifiant texte qui identifie un lieu de façon unique. Il peut être utilisé pour extraire l'objet Place par la suite. Pour plus d'informations sur les identifiants de lieu dans Google Places API for Android, voir Identifiants et détails de lieu. Pour des informations générales sur les identifiants de lieu, voir la présentation des identifiants de lieu.
  • getPlaceTypes() renvoie la liste des types de lieu associés à ce lieu.

Limites d'utilisation

  • L'utilisation de la méthode [GeoDataApi.getAutocompletePredictions()](/android/reference/com/google/android/gms/location/places/GeoDataApi.html#getAutocompletePredictions(com.google.android.gms.common.api.GoogleApiClient, java.lang.String, com.google.android.gms.maps.model.LatLngBounds, com.google.android.gms.location.places.AutocompleteFilter) est soumise à des limites de requête hiérarchisées. Voir la documentation sur les limites d'utilisation.

Afficher les mentions dans votre application

  • Si votre application utilise le service de saisie semi-automatique par programmation, vous devez afficher une mention « Powered by Google » ou la faire apparaître sur une carte Google.
  • Si votre application utilise le widget de saisie semi-automatique, aucune action supplémentaire n'est requise (la mention obligatoire s'affiche par défaut).
  • Si vous extrayez et affichez des informations de lieu supplémentaires après avoir obtenu un lieu par identifiant, vous devez afficher les mentions tierces également.

Pour en savoir plus, voir la documentation sur les mentions.

Résolution des erreurs

Même si tout type d'erreur peut se produire, la majorité des erreurs que votre application peut rencontrer sont dues à des erreurs de configuration (par exemple, utilisation d'une clé d'API incorrecte, ou clé d'API mal configurée), ou à des erreurs de quota (votre application a dépassé son quota). Pour plus d'informations sur les quotas, voir les limites d'utilisation.

Les erreurs qui se produisent au cours de l'utilisation des commandes de saisie semi-automatique sont renvoyées dans le rappel onActivityResult(). Appelez PlaceAutocomplete.getStatus() pour obtenir le message d'état pour le résultat.

Envoyer des commentaires concernant…

location_on
Google Places API for Android