Es kann losgehen!

Bevor Sie mit der Entwicklung beginnen, lesen Sie bitte unsere Entwicklerdokumentation.

Die Google Places API for Android aktivieren

Zum Einstieg führen wir Sie durch die Google Developers Console, wo Sie vorab Folgendes tun müssen:

  1. Ein Projekt erstellen oder auswählen
  2. Die Google Places API for Android aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Orte automatisch vervollständigen

Der Dienst zur automatischen Vervollständigung der Google Places API for Android macht als Antwort auf Suchabfragen von Nutzern Vorschläge zu möglichen Orten. Während Nutzer Eingaben machen, gibt der Dienst zur automatischen Vervollständigung Vorschläge für Orte zurück (etwa für Unternehmen, Adressen und Points of Interest).

Sie haben die folgenden Möglichkeiten, Ihrer App eine Funktion zur automatischen Vervollständigung hinzuzufügen:

Autocomplete-Widget hinzufügen

Das Widget zur automatischen Vervollständigung ist ein kleines Suchfenster mit integrierter Autocomplete-Funktion. Wenn ein Nutzer Suchbegriffe eingibt, stellt das Widget eine Liste mit Ortsvorschlägen zur Auswahl. Wenn der Nutzer eine Auswahl vornimmt, wird eine Place-Instanz zurückgegeben, anhand derer Ihre App Details zum ausgewählten Ort abrufen kann.

Um Ihrer App ein Widget zur automatischen Vervollständigung hinzuzufügen, stehen Ihnen zwei Möglichkeiten zur Verfügung:

Möglichkeit 1: Ein PlaceAutocompleteFragment oder SupportPlaceAutocompleteFragment einbetten

Um Ihrer App ein PlaceAutocompleteFragment hinzufügen, gehen Sie wie folgt vor:

  1. Fügen Sie dem XML-Layout Ihrer Aktivität ein Fragment hinzu.
  2. Fügen Sie Ihrer Aktivität oder Ihrem Fragment einen Listener hinzu.

Einer Aktivität ein PlaceAutocompleteFragment hinzufügen

Um einer Aktivität ein PlaceAutocompleteFragment hinzuzufügen, fügen Sie einem XML-Layout ein neues Fragment mit dem Namen com.google.android.gms.location.places.ui.PlaceAutocompleteFragment hinzu. Beispiel:

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

Hinweis: Das Fragment hat standardmäßig keinen Rand und keinen Hintergrund. Um für ein einheitliches visuelles Erscheinungsbild zu sorgen, verschachteln Sie das Fragment innerhalb eines anderen Layoutelements wie CardView.

Einer Aktivität einen PlaceSelectionListener hinzufügen

Der PlaceSelectionListener behandelt die Rückgabe eines Orts als Reaktion auf die Auswahl durch den Nutzer. Der folgende Code zeigt, wie ein Verweis auf das Fragment erstellt und Ihrem PlaceAutocompleteFragment ein Listener hinzugefügt wird:

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

Mit SupportPlaceAutocompleteFragment (ältere Plattformen)

Zur Unterstützung von Objekten vom Typ PlaceAutocompleteFragment erfordert die Google Places API API Level 12 oder höher. Für Anwendungen vor API Level 12 können Sie dieselbe Funktion mithilfe der Klasse SupportPlaceAutocompleteFragment realisieren. Außerdem müssen Sie die Android v4 Support Library hinzufügen. Zur Unterstützung von Android-Versionen vor API Level 12 gehen Sie wie folgt vor:

  • Erweitern Sie FragmentActivity oder AppCompatActivity in Ihrer Hauptaktivität.
  • Verwenden Sie SupportPlaceAutocompleteFragment anstatt PlaceAutocompleteFragment.
  • Verwenden Sie getSupportFragmentManager() anstatt getFragmentManager().

Möglichkeit 2: Autocomplete-Aktivität mit einem Intent starten

Wenn Ihre App einen anderen Navigationsablauf verwenden soll (zum Beispiel, um die automatische Vervollständigung von einem Symbol anstatt von einem Suchfeld aus auszulösen), kann Ihre App die automatische Vervollständigung mit einem Intent starten.

Hinweis: Diese Schritte sind nicht erforderlich, wenn Sie ein Fragment einbetten.

Um das Autocomplete-Widget zu starten, gehen Sie wie folgt vor:

  1. Verwenden Sie PlaceAutocomplete.IntentBuilder , um einen Intent zu erstellen, wobei der gewünschte Modus für PlaceAutocomplete übergeben wird. Der Intent muss startActivityForResult aufrufen und einen Anforderungscode übergeben, der Ihren Intent identifiziert.
  2. Überschreiben Sie den Callback onActivityResult, um den ausgewählten Ort zu erhalten.

Intent für automatische Vervollständigung erstellen

Das nachfolgende Beispiel zeigt, wie Sie mit PlaceAutocomplete.IntentBuilder einen Intent erstellen, um das Autocomplete-Widget als Intent zu starten:

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

Wenn Sie das Autocomplete-Widget mit einem Intent starten, können Sie zwischen dem Überlagerungs- und dem Vollbild-Anzeigemodus wählen. Die folgenden Screenshots zeigen jeweils einen der Anzeigemodi:

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
Abbildung 1: Autocomplete-Widget im Überlagerungsmodus (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
Abbildung 2: Autocomplete-Widget im Vollbildmodus (MODE_FULLSCREEN)

Den Callback onActivityResult überschreiben

Um eine Benachrichtigung zu erhalten, wenn ein Nutzer einen Ort ausgewählt hat, muss das onActivityResult() der Aktivität in der App überschrieben werden, wobei der Anforderungscode geprüft wird, den Sie für den Intent übergeben haben (siehe folgendes Beispiel).

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

Ergebnisse der automatischen Vervollständigung einschränken

Sie können das Autocomplete-Widget so einrichten, dass es bevorzugt Ergebnisse aus einer bestimmten geografischen Region zurückgibt, und Sie können bei den Ergebnissen einen Filter für einen oder mehrere Ortstypen verwenden.

Bei den Ergebnissen eine bestimmte Region bevorzugen

Gehen Sie wie folgt vor, um bei den Ergebnissen der automatischen Vervollständigung eine bestimmte Region zu bevorzugen:

  • Rufen Sie setBoundsBias() aus der Instanz PlaceAutocompleteFragment oder IntentBuilder Ihrer App ab und übergeben Sie LatLngBounds. Mit dem folgenden Codebeispiel wird der Aufruf von setBoundsBias() für eine Fragmentinstanz veranschaulicht, um bei den Vervollständigungsvorschlägen die Region von Sydney in Australien zu bevorzugen.
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

Ergebnisse nach Ortstyp filtern

Um bei der automatische Vervollständigung Ergebnisse nach einem bestimmten Ortstyp zu filtern, rufen Sie AutocompleteFilter.Builder auf, um einen neuen AutocompleteFilter zu erstellen, wobei setTypeFilter() aufgerufen wird, um den zu verwendenden Filter festzulegen. Übergeben Sie anschließend den Filter an ein Fragment oder einen Intent.

Mit dem folgenden Codebeispiel wird die Definition eines AutocompleteFilter für ein PlaceAutocompleteFragment veranschaulicht, um einen Filter festzulegen, mit dem nur Ergebnisse mit einer präzisen Adresse zurückgegeben werden.

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

autocompleteFragment.setFilter(typeFilter);

Mit dem folgenden Codebeispiel wird die Definition eines AutocompleteFilter für ein Intent veranschaulicht, um einen Filter festzulegen, mit dem nur Ergebnisse mit einer präzisen Adresse zurückgegeben werden.

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

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

Weitere Informationen zu Ortstypen finden Sie im Leitfaden zu Ortstypen und in AutocompleteFilter.Builder.

Ortsvorschläge programmgesteuert abrufen

Als Alternative zur UI, die durch das Widget für die automatische Vervollständigung bereitgestellt wird, können Sie eine UI für benutzerdefinierte Suchen erstellen. Hierzu muss Ihre App programmgesteuert Ortsvorschläge abrufen. Durch den Aufruf von GeoDataApi.getAutocompletePredictions() kann Ihre App eine Liste vorgeschlagener Ortsnamen und/oder Adressen vom Autocomplete-Dienst abrufen. Dabei werden die folgenden Parameter übergeben:

  • Erforderlich: Eine Zeichenfolge query mit dem vom Nutzer eingegebenen Text.
  • Erforderlich: Ein Objekt LatLngBounds, das die Ergebnisse in einer bestimmten Gegend bevorzugt, die durch Längen- und Breitengradgrenzwerte angegeben ist.
  • Optional: Ein AutocompleteFilter, der eine Gruppe von Ortstypen enthält, die Sie zum Einschränken der Ergebnisse auf einen oder mehrere Ortstypen verwenden können. Die folgenden Ortstypen werden unterstützt:

    • TYPE_FILTER_NONE – Ein leerer Filter; alle Ergebnisse werden zurückgegeben.
    • TYPE_FILTER_GEOCODE– Gibt nur Geocoding-Ergebnisse und keine Unternehmen zurück. Verwenden Sie diese Anforderung, um die Ergebnisse eindeutig zu machen, wenn der angegebene Standort unbestimmt sein kann.
    • TYPE_FILTER_ADDRESS– Gibt nur automatisch vervollständigte Ergebnisse mit einer exakten Adresse zurück. Verwenden Sie diesen Typ, wenn Sie sicher sind, dass Nutzer vollständig angegebene Adressen suchen.
    • TYPE_FILTER_ESTABLISHMENT– Gibt als Ergebnisse ausschließlich Unternehmen zurück.
    • TYPE_FILTER_REGIONS – Gibt ausschließlich Orte zurück, die einem der folgenden Typen entsprechen:

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIES – Gibt ausschließlich Ergebnisse zurück, die locality oder administrative_area_level_3 entsprechen.

Weitere Informationen zu Ortstypen finden Sie im Leitfaden zu Ortstypen und in AutocompleteFilter.Builder.

Das folgende Beispiel zeigt einen vereinfachten Aufruf von GeoDataApi.getAutocompletePredictions(). Ein vollständiges Beispiel finden Sie bei den Beispiel-Apps.

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

Die API gibt einen AutocompletePredictionBuffer in einem zurück. PendingResult. Der AutocompletePredictionBuffer enthält eine Liste mit Objekten vom Typ AutocompletePrediction, die vorgeschlagene Orte darstellen. Der Puffer kann leer sein, wenn kein bekannter Ort der Abfrage und den Filterkriterien entspricht.

Hinweis: Um einen Speicherverlust zu vermeiden, müssen Sie das Objekt AutocompletePredictionBuffer freigeben, wenn es von Ihrer App nicht mehr benötigt wird. Weitere Informationen finden Sie im Dokument über Puffer.

Für jeden vorgeschlagenen Ort können Sie die folgenden Methoden aufrufen, um Ortsdetails abzurufen:

  • getFullText(CharacterStyle matchStyle) gibt den vollständigen Text einer Ortsbeschreibung zurück. Dies ist die Kombination aus dem primären und sekundären Text. Beispiel: „Eiffel Tower, Avenue Anatole France, Paris, France“. Außerdem können Sie mit dieser Methode mit CharacterStyle die Abschnitte der Beschreibung, die der Suche entsprechen, mit einer Formatierung Ihrer Wahl hervorheben. Der Parameter CharacterStyle ist optional. Wenn Sie keine Hervorhebung wünschen, setzen Sie ihn auf NULL.
  • getPrimaryText(CharacterStyle matchStyle) gibt den Haupttext zur Beschreibung eines Orts zurück. Dies ist in der Regel der Name des Orts. Beispiele: „Eiffel Tower“ oder „123 Pitt Street“.
  • getSecondaryText(CharacterStyle matchStyle) gibt den ergänzenden Text einer Ortsbeschreibung zurück. Dies kann zum Beispiel als zweite Zeile hilfreich sein, wenn Ortsvorschläge angezeigt werden. Beispiele: „Avenue Anatole France, Paris, France“ oder „Sydney, New South Wales“.
  • getPlaceId() gibt die Orts-ID des vorgeschlagenen Orts zurück. Die Orts-ID ist eine Kennung in Textform, mit der ein Ort eindeutig bezeichnet wird und die Sie verwenden können, um später erneut das Objekt Place abzurufen. Weitere Informationen zu Orts-IDs in Google Places API for Android finden Sie unter Orts-IDs und Ortsdaten. Allgemeine Informationen zu Orts-IDs finden Sie in der Übersicht über Orts-IDs.
  • getPlaceTypes() gibt eine Liste der mit diesem Ort verknüpften Ortstypen zurück.

Nutzungsbeschränkungen

Zuordnungen in der App anzeigen

  • Wenn der Dienst zur automatischen Vervollständigung in Ihrer App programmgesteuert verwendet wird, muss Ihre UI entweder eine Zuordnung „Powered by Google“ anzeigen oder innerhalb einer Karte mit der die Markenkennzeichnung Google erscheinen.
  • Wenn in Ihrer App das Widget zur automatischen Vervollständigung verwendet wird, sind keine weiteren Aktionen erforderlich (die erforderliche Zuordnung wird standardmäßig angezeigt).
  • Wenn Sie nach dem Anfordern eines Orts anhand einer ID zusätzliche Ortsinformationen abrufen und anzeigen, müssen Sie auch eine Zuordnung für Inhalte Dritter anzeigen.

Weitere Informationen dazu finden Sie in der Dokumentation zu Zuordnungen.

Fehlerbehebung

Es kann zwar eine Vielzahl unterschiedlicher Fehler auftreten, doch die meisten Fehler Ihrer App sind wahrscheinlich auf Konfigurationsfehler (zum Beispiel Verwendung des falschen API-Schlüssels oder fehlerhafte Konfiguration des API-Schlüssels) oder Kontingentfehler (Überschreitung des App-Kontingents) zurückzuführen. Weitere Informationen zu Kontingenten finden Sie unter Nutzungsbeschränkungen.

Fehler, die bei der Verwendung der Steuerelemente zur automatischen Vervollständigung auftreten, werden im Callback onActivityResult() zurückgegeben. Um die Statusmeldung für das Ergebnis zu erhalten, rufen Sie PlaceAutocomplete.getStatus() auf.

Feedback geben zu...

location_on
Google Places API for Android