Von Geocoding v3 zu v4 migrieren

In der Geocoding API v4 werden mehrere neue Methoden eingeführt, die Funktionen in Version 3 der API ersetzen. In diesem Leitfaden erfahren Sie, wie Sie Ihre App migrieren, um die neuen v4-Methoden zu verwenden.

Sie können Ihre vorhandenen API-Schlüssel mit den neuen v4-Methoden verwenden. Wenn Sie jedoch eine Kontingenterhöhung für Version 3 der API beantragt haben, müssen Sie eine Erhöhung für die neuen APIs der Version 4 beantragen.

Von v3 Forward Geocoding migrieren

Wenn Sie v3-Geocoding zum Geocodieren von Adressen verwenden, sollten Sie zur v4-Methode Adresse geocodieren migrieren, die eine GET-Anfrage akzeptiert.

In der Version 4 der API wurden Namen, Struktur und Unterstützung für mehrere Parameter geändert. Wir empfehlen dringend, eine Feldmaske zu verwenden, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen.

Änderungen an Anfrageparametern

Änderungen an Antwortfeldern

v3-Komponentenfilter reproduzieren

Beim Forward Geocoding in Geocoding v3 gab es den Parameter components, mit dem Ergebnisse für bestimmte Komponenten (z.B. components=country:US) hart gefiltert werden konnten. Beim Forward Geocoding in v4 wird diese Art der harten Filterung in den Anfrageparametern nicht unterstützt. In Version 4 können Sie Adressinformationen entweder als einzelnen unstrukturierten String im Pfad oder als strukturierte Abfrageparameter wie address.addressLines, address.locality, address.administrativeArea, address.postalCode und address.regionCode angeben. Strukturierte Parameter fungieren nicht als harte Filter. Stattdessen werden alle angegebenen Komponenten kombiniert, um die vollständige Adresse zu bilden, die die API zu geocodieren versucht. Die API sucht nach der besten Übereinstimmung für die gesamte angegebene Adresse über alle Komponenten hinweg. Wenn Sie Komponenten strukturiert angeben, kann die API die Absicht besser verstehen, insbesondere wenn die Adressinformationen aus separaten Formularfeldern stammen. So kann die API auch kleinere Tippfehler oder Unklarheiten in den einzelnen Komponenten besser verarbeiten, da der Typ der Informationen in jedem Feld eindeutig ist.

Um ein ähnliches Verhalten wie bei den harten Komponentenfiltern von Version 3 zu erreichen, müssen Sie die clientseitige Filterung für das results-Array implementieren, das von der Version 4-API zurückgegeben wird. Verwenden Sie dazu die Objekte postalAddress und addressComponents in der Antwort.

In der folgenden Tabelle sehen Sie die beste Übereinstimmung zwischen den v3-Filtern components und den v4-Feldern postalAddress:

Beispiele für die clientseitige Filterung

Die folgenden Beispiele zeigen, wie Sie Ergebnisse filtern, um ein ähnliches Verhalten wie bei der v3-Komponentenfilterung für die unterstützten Felder „Land“, „Verwaltungsgebiet“ und „Postleitzahl“ zu erzielen. Es wird nicht empfohlen, nach anderen Feldern zu filtern, da keine zuverlässigen Filterkriterien vorhanden sind.

Nach Land filtern

Vergleichen Sie die address.regionCode aus Ihrer Anfrage mit der postalAddress.regionCode in jedem Ergebnis. Die API akzeptiert zwar Kleinbuchstaben für Regionscodes in der Anfrage, gibt sie in der Antwort aber immer in Großbuchstaben zurück. Sie müssen Ihre Eingabe also vor dem Vergleich in Großbuchstaben normalisieren.

def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')

function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');

Nach Verwaltungsgebiet filtern

Vergleichen Sie die address.administrativeArea aus Ihrer Anfrage mit der postalAddress.administrativeArea in jedem Ergebnis. Ähnlich wie bei Ländercodes sollten Sie die Eingabe vor dem Vergleich in Großbuchstaben normalisieren. Das ist nur zuverlässig, wenn für administrativeArea in Ihrer Anfrage eine standardmäßige zweibuchstabige Abkürzung angegeben wird. Die postalAddress.administrativeArea in der Antwort stimmt aus mehreren Gründen möglicherweise nicht direkt mit den ISO 3166-2-Code-Suffixen überein. Erstens ist in einigen Gebieten die Unterteilung, die dem ISO 3166-2-Code entspricht, nicht Teil der Standarddarstellung von Postadressen. In Spanien kann beispielsweise die Verwaltungseinheit der Ebene 1 (z.B. „CN“ für Canarias) in addressComponents vorhanden sein, während postalAddress.administrativeArea die Verwaltungseinheit der Ebene 2 (z.B. „Santa Cruz de Tenerife“) enthalten kann. Zweitens wird die Abkürzung der Unterteilung in einigen Gebieten nicht häufig verwendet und in postalAddress.administrativeArea mit einem längeren Namen dargestellt. Aus ähnlichen Gründen stimmt addressComponents.shortText für die Adresskomponente, die der Unterteilung entspricht, möglicherweise nicht mit dem ISO 3166-2-Code-Suffix der Unterteilung überein. Außerdem kann die Unterteilung in einigen Fällen in der Adresskomponente für administrative_area_level_n mit n > 1 dargestellt werden. Für die umfassendsten Ergebnisse sollten Sie sowohl in postalAddress.administrativeArea als auch in allen addressComponents mit dem Typ administrative_area_level_n (z.B. administrative_area_level_1) nach Übereinstimmungen suchen.

def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')

function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');

Nach Postleitzahl filtern

Vergleichen Sie die address.postalCode aus Ihrer Anfrage mit der postalAddress.postalCode in jedem Ergebnis. Sie müssen sowohl die Postleitzahlen für die Eingabe als auch die für das Ergebnis vor dem Vergleich normalisieren. Die Normalisierungslogik hängt stark von der Region ab. Ein einfacher Ansatz besteht darin, Leerzeichen und Bindestriche zu entfernen und eine einheitliche Groß-/Kleinschreibung zu verwenden.

Für die Verarbeitung von Postleitzahlpräfixen (z.B. „L2“ im Vereinigten Königreich) oder ‑suffixen (z.B. „+4“ in US-Postleitzahlen) ist möglicherweise eine erweiterte Normalisierung erforderlich. Die erforderliche Normalisierungslogik hängt vom Land und den Formaten der beteiligten Postleitzahlen ab. Möglicherweise müssen Sie die bereitgestellten Normalisierungsfunktionen anpassen oder eine komplexere Logik für die Regionen implementieren, auf die Sie abzielen.

Das bereitgestellte Beispiel verarbeitet US-Postleitzahlen und ermöglicht den Abgleich mit der 5-stelligen Basis, auch wenn ZIP+4 angegeben oder zurückgegeben wird.

import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')

function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

Von v3 der umgekehrten Geocodierung migrieren

Wenn Sie v3 Reverse Geocoding verwenden, um Koordinaten in Adressen umzuwandeln, sollten Sie zur Methode v4 Reverse geocode a location migrieren, die eine GET-Anfrage akzeptiert.

In der Version 4 der API wurden Namen, Struktur und Unterstützung für mehrere Parameter geändert. Wir empfehlen dringend, eine Feldmaske zu verwenden, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen.

Änderungen an Anfrageparametern

Änderungen an Antwortfeldern

Von v3-Adressdeskriptoren migrieren

Wenn Sie address_descriptor verwenden, um mit Geocoding v3 zusätzliche Informationen zu einem Ort abzurufen, müssen Sie zur Verwendung des Felds landmarks von SearchDestinationsResponse migrieren.

Von v3-Geocoding für Orte migrieren

Wenn Sie place_id verwenden, um die Adresse für eine bestimmte Orts-ID mit Geocoding v3 abzurufen, müssen Sie zur Methode Place Geocoding in Version 4 migrieren, die eine GET-Anfrage akzeptiert.

In der Version 4 der API wurden Namen, Struktur und Unterstützung für mehrere Parameter geändert. Wir empfehlen dringend, eine Feldmaske zu verwenden, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen.

Änderungen an Anfrageparametern

Änderungen an Antwortfeldern

Von der Geocoding Hyperlocal Data API zur Destinations API migrieren

Die folgenden Funktionen in der Geocoding API v3 werden durch die Methode SearchDestinations der Geocoding API v4 ersetzt:

• Einstiege
• Navigationspunkte
• Gebäudeumrisse
• Außengelände

Wenn Sie die Geocoding API v3 für die oben genannten Funktionen verwendet haben, können Sie in diesem Dokument nachlesen, wie Sie stattdessen die SearchDestinations-Methode verwenden. In diesem Dokument wird erläutert, wo in der SearchDestinations-Antwort diese Funktionen zu finden sind, und es werden Unterschiede in der Darstellung dieser Funktionen in den API-Antworten zwischen der Geocoding API v3 und der SearchDestinations-Methode der Geocoding API v4 beschrieben.

Einstiege

Verwenden Sie das Feld destination.entrances, um die Eintritte abzurufen, die mit einem destination verknüpft sind.

Das Format eines entrance unterscheidet sich leicht vom Eingangsformat in der Geocoding API v3. Jeder Eintrag in destination.entrances hat die folgenden Felder:

• displayName: Dies ist ein neues optionales Feld mit einem für Menschen lesbaren Namen für den Eingang, z. B. „Tor B“.
• location – Dies ist ein Ort vom Typ LatLng, der sich vom Format der Geocoding API v3 unterscheidet.
• tags: Dies entspricht dem Feld tags der Eingänge aus der Geocoding API v3.
• place: Analog zum Feld buildingPlaceId der Eingänge aus der Geocoding API v3. Die Orts-ID in diesem Feld kann jedoch für einen Ort beliebigen Typs sein, nicht nur für ein Gebäude.

Navigationspunkte

Wenn Sie die Navigationspunkte abrufen möchten, die mit einem destination verknüpft sind, verwenden Sie das Feld destination.navigationPoints.

Das Format von navigationPoint unterscheidet sich leicht vom Format für Navigationspunkte in der Geocoding API v3. Jeder Navigationspunkt in destination.navigationPoints hat die folgenden Felder:

• displayName: Dies ist ein neues optionales Feld mit einem lesbaren Namen für den Navigationspunkt, z. B. „5th Ave“.
• location – Dies ist ein Ort vom Typ LatLng, der sich vom Format der Geocoding API v3 unterscheidet.
• travelModes: Dies entspricht dem Feld restrictedTravelModes der Navigationspunkte aus der Geocoding API v3. Die möglichen Enum-Werte sind dieselben. Der einzige Unterschied besteht darin, dass dieses Feld jetzt die zulässigen Fortbewegungsmittel für den Navigationspunkt und nicht die eingeschränkten Fortbewegungsmittel darstellt.
• usage: Dies ist ein neues Feld, das die vom Navigationspunkt unterstützten Anwendungsfälle enthält.

Gebäudeumrisse

Wenn Sie die mit einem destination verknüpften Gebäudeumrisse abrufen möchten, sollten Sie das Feld displayPolygon der placeView-Objekte im destination verwenden, die Gebäude darstellen. Für jedes placeView können Sie mit dem Feld placeView.structureType prüfen, ob es sich um ein Gebäude handelt. Wenn der Strukturtyp BUILDING ist, können Sie die Gliederung aus dem Feld placeView.displayPolygon abrufen. Das placeView enthält auch zusätzliche Felder für das Gebäude, die in der Geocoding API v3 nicht vorhanden waren.

Ein destination kann ein placeView-Objekt enthalten, das ein Gebäude in den folgenden Feldern darstellt:

• destination.primary: Dies ist der primäre Ort für das Ziel.
• destination.containingPlaces: Dies ist ein wiederkehrendes Feld, das größere Orte enthalten kann, die den primären Ort „enthalten“. Wenn der primäre Ort beispielsweise ein subpremise ist, enthält containingPlaces in der Regel die placeView, die das Gebäude darstellt.
• destination.subDestinations: Dies ist ein wiederkehrendes Feld, das Unterziele des primären Orts enthalten kann. Beispielsweise einzelne Wohneinheiten eines Gebäudes. Dieses Feld enthält in der Regel kein placeView für ein Gebäude.

Das Format von placeView.displayPolygon entspricht dem Format für Gebäudeumrisse in der Geocoding API v3, also dem GeoJSON-Format, das dem RFC 7946-Format entspricht.

Außengelände

Ähnlich wie beim Erstellen von Umrisslinien sollten Sie zum Abrufen der mit einem destination verknüpften Grundstücke das Feld displayPolygon der placeView-Objekte im destination verwenden, die Grundstücke darstellen. Für jede placeView können Sie mit dem Feld placeView.structureType prüfen, ob es sich um einen Grund handelt. Wenn der Strukturtyp GROUNDS ist, können Sie die Gliederung aus dem Feld placeView.displayPolygon abrufen. Das placeView enthält auch zusätzliche Felder für die Gründe, die in der Geocoding API v3 nicht vorhanden waren.

Ein destination kann ein placeView-Objekt enthalten, das einen Grund in den folgenden Feldern darstellt:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

Das Format von placeView.displayPolygon entspricht dem Format für den Umriss des Grundstücks in der Geocoding API v3, also dem GeoJSON-Format gemäß RFC 7946.

Genauigkeit der Ergebnisse

In der Geocoding API v3 gab das Feld location_type in der Antwortgeometrie die Genauigkeit der Ergebnisse an. Einige Clients haben Ergebnisse anhand dieser Werte (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER und APPROXIMATE) sortiert oder gefiltert. Bei Standardmigrationen zur Geocoding API v4 wird dieses Feld in granularity umbenannt.

In der Destinations API (Version 4 SearchDestinations) gibt es kein location_type-Feld. Stattdessen werden räumliche Informationen anders verarbeitet:

• Keine manuelle clientseitige Filterung erforderlich: Beim Standard-Geocoding werden mehrere Ergebnisse mit unterschiedlichen Granularitäten zurückgegeben. Die Methode SearchDestinations minimiert Mehrdeutigkeiten, indem sie nach Möglichkeit eine einzelne, optimierte Zieladresse zurückgibt. So müssen Clients nicht mehr nach Standorttyp filtern, um das beste Ergebnis zu ermitteln.
• Räumliche Informationen, die durch Strukturtyp und Anzeigepolygone dargestellt werden: Räumliche Geometrie und Struktur werden angegeben durch:
  • Die displayPolygon (für die genaue Geometrie).
  • Das Feld structureType im Objekt placeView.
• Zuordnung von Strukturtypen:
  • Ein structureType von POINT, BUILDING oder SECTION entspricht im Allgemeinen dem, was zuvor als ROOFTOP bezeichnet wurde.
  • Ein structureType von GROUNDS entspricht in der Regel GEOMETRIC_CENTER.

Feldmaske verwenden, um diese Funktionen anzufordern

Für die Methode SearchDestinations ist eine Feldmaske erforderlich, wie unter Zurückzugebende Felder auswählen beschrieben. Die Feldmaske kann auf * gesetzt werden, um alle Felder zurückzugeben. Sie können sie aber auch auf die gewünschten Felder festlegen. Mit der folgenden API-Anfrage wird beispielsweise die Feldmaske so festgelegt, dass alle Felder abgerufen werden, die zum Abrufen der Eingänge, Navigationspunkte, Gebäudeumrisse und Grundstücke eines Ziels erforderlich sind:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4/geocode/destinations

Sicherheitsaspekte

Die Geocoding API v4 ist als Server-zu-Server-API konzipiert. Es gibt keinen direkten Migrationspfad für JavaScript-Nutzer von Version 3 zu Version 4. Wenn Sie die v4-Methoden direkt über clientseitiges JavaScript (z. B. in einem Browser) mit einem API-Schlüssel aufrufen, ist Ihr API-Schlüssel einem hohen Risiko von Diebstahl und Missbrauch ausgesetzt.

HTTP-Referrer-Einschränkungen sind zwar nützlich, bieten aber keinen ausreichenden Schutz für Webdienstendpunkte, da sie von Angreifern, die den Referer-Header in ihren Anfragen fälschen, problemlos umgangen werden können.

Empfohlene Vorgehensweise

Die empfohlene Methode zur Verwendung der Geocoding API v4 ist über Ihren eigenen Backend-Server. Ihre Clientanwendung sollte Anfragen an diesen Vermittlungsserver senden, der dann die Google API sicher mit einem geschützten API-Schlüssel aufruft (z. B. einem Schlüssel, der in einer Umgebungsvariablen oder einem Secret Manager gespeichert ist). So wird sichergestellt, dass Ihr API-Schlüssel niemals im Frontend-Code offengelegt wird.

Alternativen für clientseitige Anforderungen

Wenn Sie clientseitige Anforderungen haben, die eine Geocodierung erfordern, sollten Sie eine der vorhandenen clientseitigen Lösungen verwenden:

• Geocoding-Dienst in der Maps JavaScript API:Der Geocoding-Dienst verwendet weiterhin das Backend der Version 3 und ist für die Verwendung in einer Browserumgebung konzipiert.
• Places UI Kit:Verwenden Sie das Places UI Kit, einschließlich der Place Autocomplete-Elemente>, für adressbezogene Benutzeroberflächenelemente.