Von Geocoding v3 zu v4 migrieren

In der Geocoding API v4 werden mehrere neue Methoden eingeführt, die Funktionen der API v3 ersetzen. In diesem Leitfaden wird beschrieben, wie Sie Ihre App so migrieren, dass die neuen v4-Methoden verwendet werden.

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 Version 4-APIs beantragen.

Von v3-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 v4 API werden 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 des harten Filterns in den Anfrageparametern nicht unterstützt. In v4 können Sie Adressinformationen entweder als einzelnen unstrukturierten String im Pfad oder als strukturierte Suchparameter wie address.addressLines, address.locality, address.administrativeArea, address.postalCode und address.regionCode angeben. Strukturierte Parameter fungieren nicht als feste Filter. Stattdessen werden alle angegebenen Komponenten zu einer vollständigen Adresse kombiniert, die die API dann versucht, per Geocoding zu verarbeiten. Die API sucht nach der besten Übereinstimmung für die gesamte angegebene Adresse über alle Komponenten hinweg. Wenn Sie Komponenten strukturiert bereitstellen, kann die API die Absicht besser verstehen, insbesondere wenn die Adressinformationen aus separaten Formularfeldern stammen. So kann die API kleinere Tippfehler oder Unklarheiten in den einzelnen Komponenten besser verarbeiten, da der Informationstyp 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 der API zurückgegeben wird. Die Filterung muss auf den Objekten postalAddress und addressComponents in der Antwort basieren.

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

Beispiele für die clientseitige Filterung

Die folgenden Beispiele zeigen, wie Sie Ergebnisse filtern, um ein ähnliches Verhalten wie beim Filtern von V3-Komponenten für die unterstützten Felder „Land“, „Verwaltungsgebiet“ und „Postleitzahl“ zu erzielen. Es wird nicht empfohlen, nach anderen Feldern zu filtern, da es keine zuverlässigen Filterkriterien gibt.

Nach Land filtern

Gleichen Sie die address.regionCode aus Ihrer Anfrage mit der postalAddress.regionCode in den einzelnen Ergebnissen ab. Die API akzeptiert zwar Kleinbuchstaben für Regionscodes in der Anfrage, gibt sie aber immer in Großbuchstaben in der Antwort 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

Gleichen Sie die address.administrativeArea aus Ihrer Anfrage mit der postalAddress.administrativeArea in jedem Ergebnis ab. Ähnlich wie bei Ländercodes sollten Sie die Eingabe vor dem Vergleich in Großbuchstaben umwandeln. Dies ist nur zuverlässig, wenn die administrativeArea in Ihrer Anfrage mit einer standardmäßigen zweistelligen Abkürzung angegeben ist. Das 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 das Verwaltungsgebiet der Ebene 1 (z.B. „CN“ für Canarias) in addressComponents enthalten sein, während postalAddress.administrativeArea das Gebiet 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 Untereinheit in einigen Fällen in der Adresskomponente für administrative_area_level_n mit n > 1 dargestellt werden. Um die umfassendsten Ergebnisse zu erhalten, 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

Gleichen Sie die address.postalCode aus Ihrer Anfrage mit der postalAddress.postalCode in jedem Ergebnis ab. Sie müssen sowohl die Eingabe- als auch die Ergebnispostleitzahlen vor dem Vergleich normalisieren. Die Normalisierungslogik hängt stark von der Region ab. Bei einem einfachen Ansatz werden Leerzeichen und Bindestriche entfernt und die Groß- und Kleinschreibung wird vereinheitlicht.

Für die Verarbeitung von Postleitzahlpräfixen (z.B. „L2“ im Vereinigten Königreich) oder ‑suffixen (z.B. „+4“ bei 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 fünfstelligen 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 Version 3 der umgekehrten Geocodierung migrieren

Wenn Sie die umgekehrte Geocodierung von v3 verwenden, um Koordinaten in Adressen umzuwandeln, sollten Sie zur v4-Methode Umgekehrte Geocodierung für einen Standort 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 am Antwortfeld

Von v3-Adressdeskriptoren migrieren

Wenn Sie address_descriptor verwenden, um mit Geocoding v3 zusätzliche Informationen zu einem Ort abzurufen, müssen Sie zum Feld 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 v4 API werden 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 am Antwortfeld

Von Geocoding Hyperlocal Data zu Destinations migrieren

Die folgenden Funktionen 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 mit diesem Dokument die SearchDestinations-Methode verwenden, um diese Funktionen zu erhalten. In diesem Dokument wird erläutert, wo diese Funktionen in der SearchDestinations-Antwort 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

Wenn Sie die Eingänge abrufen möchten, die einem destination zugeordnet sind, verwenden Sie das Feld destination.entrances.

Das Format von 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, das einen menschenlesbaren Namen für den Eingang enthält, z. B. „Tor B“.
• location: Dies ist ein Standort vom Typ LatLng, der sich vom Format in der Geocoding API v3 unterscheidet.
• tags: 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 unbedingt nur für ein Gebäude.

Navigationspunkte

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

Das Format eines navigationPoint-Objekts unterscheidet sich geringfügig vom Format des Navigationspunkts in der Geocoding API v3. Jeder Navigationspunkt in destination.navigationPoints hat die folgenden Felder:

• displayName: Dies ist ein neues optionales Feld, das einen menschenlesbaren Namen für den Navigationspunkt enthält, 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, verwenden Sie das Feld displayPolygon der placeView-Objekte im destination, 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. Die placeView enthält außerdem zusätzliche Felder für das Gebäude, die in der Geocoding API v3 nicht vorhanden waren.

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

• destination.primary: Dies ist der Hauptort 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 untergeordnete Ziele des primären Orts enthalten kann. Beispiel: einzelne Wohnungen in einem Gebäude. Dieses Feld enthält normalerweise keinen placeView, der ein Gebäude darstellt.

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

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 haben, das ein Gelände in den folgenden Feldern darstellt:

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

Das Format von placeView.displayPolygon entspricht dem Format für die Umrisslinie von Grundstücken in der Geocoding API v3, also dem GeoJSON-Format, das das RFC 7946-Format verwendet.

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 (v4 SearchDestinations) gibt es kein location_type-Feld. Stattdessen werden räumliche Informationen anders verarbeitet:

• Keine manuelle clientseitige Filterung erforderlich: Während die Standard-Geocodierung mehrere Ergebnisse mit unterschiedlichen Detaillierungsgraden liefert, minimiert die Methode SearchDestinations Mehrdeutigkeiten, indem sie nach Möglichkeit ein einzelnes, optimiertes Ziel auflöst. Kunden müssen dann 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 durch Folgendes angegeben:
  • displayPolygon (für genaue Geometrie).
  • Das Feld structureType im Objekt placeView.
• Zuordnung des Strukturtyps:
  • 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 Felder für die Rückgabe auswählen beschrieben. Die Feldmaske kann auf * gesetzt werden, um alle Felder zurückzugeben, oder Sie können sie auf die gewünschten Felder festlegen. Mit der folgenden API-Anfrage wird beispielsweise die Feldmaske so festgelegt, dass alle Felder empfangen 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. Für JavaScript-Nutzer gibt es keinen direkten Migrationspfad 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. ein Schlüssel, der in einer Umgebungsvariablen oder einem Secret Manager gespeichert ist). So wird sichergestellt, dass Ihr API-Schlüssel nie 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 v3-Backend 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.