Best Practices für die Verwendung von Geocoding API-Webdiensten

Die Google Maps Platform-Webdienste sind eine Sammlung von HTTP-Schnittstellen zu Google-Diensten, die geografische Daten für Ihre Kartenanwendungen bereitstellen.

In diesem Leitfaden werden einige gängige Praktiken beschrieben, die beim Einrichten von Webdienstanfragen und beim Verarbeiten von Dienstantworten hilfreich sind. Eine vollständige Dokumentation der Geocoding API finden Sie im Entwicklerleitfaden.

Was ist ein Webdienst?

Die Webdienste der Google Maps Platform sind eine Schnittstelle, über die Sie Google Maps API-Daten von externen Diensten anfordern und in Ihren Maps-Anwendungen verwenden können. Diese Dienste sind gemäß den Lizenzbeschränkungen in den Nutzungsbedingungen für die Google Maps Platform für die Verwendung in Verbindung mit einer Karte vorgesehen.

Die Webdienste der Maps APIs verwenden HTTP(S)-Anfragen an bestimmte URLs und übergeben URL-Parameter und/oder POST-Daten im JSON-Format als Argumente an die Dienste. Im Allgemeinen geben diese Dienste Daten im Antwortbody entweder als JSON oder XML zurück, um sie von Ihrer Anwendung zu parsen und/oder zu verarbeiten.

Eine typische Geocoding API-Anfrage hat in der Regel das folgende Format:

https://maps.googleapis.com/maps/api/geocode/output?parameters

Dabei gibt output das Antwortformat an (normalerweise json oder xml).

Hinweis: Für alle Geocoding API-Anwendungen ist eine Authentifizierung erforderlich. Weitere Informationen zu Anmeldedaten für die Authentifizierung

SSL/TLS-Zugriff

HTTPS ist für alle Google Maps Platform-Anfragen erforderlich, die API-Schlüssel verwenden oder Nutzerdaten enthalten. Anfragen über HTTP, die sensible Daten enthalten, werden möglicherweise abgelehnt.

Gültige URL erstellen

Es mag den Anschein haben, dass „gültige“ URLs eine Selbstverständlichkeit sind. Das ist jedoch nicht der Fall. So kann beispielsweise eine URL, die in die Adresszeile eines Browsers eingegeben wird, Sonderzeichen wie "上海+中國" enthalten. Der Browser muss diese Zeichen vor der Übertragung intern in eine andere Codierung umwandeln. Ebenso ist es möglich, dass Code, der UTF-8-Eingaben erzeugt oder akzeptiert, URLs mit UTF-8-Zeichen als „gültig“ behandelt; diese Zeichen müssten jedoch vor dem Senden an einen Webbrowser ebenfalls umgewandelt werden. Dieser Vorgang wird als URL-Codierung oder Prozentcodierung bezeichnet.

Sonderzeichen

Sonderzeichen müssen umgewandelt werden, da alle URLs der Syntax entsprechen müssen, die in der Spezifikation Uniform Resource Identifier (URI) angegeben ist. Das bedeutet, dass URLs nur einen Teil der ASCII-Zeichen enthalten dürfen: die bekannten alphanumerischen Symbole und einige reservierte Zeichen, die in den URLs als Steuerzeichen dienen. Hier eine Übersicht:

Beachten Sie bei der Generierung einer URL, dass diese nur die in der Tabelle aufgeführten Zeichen enthalten darf. Die Anpassung der URL an diesen Zeichensatz führt in der Regel zu zwei Problemen, nämlich dass Zeichen weggelassen oder ersetzt werden müssen:

• Die Zeichen, die Sie verarbeiten möchten, sind nicht im obigen Zeichensatz enthalten. So müssen beispielsweise Zeichen ausländischer Sprachen, wie 上海+中國, mithilfe der oben angegebenen Zeichen codiert werden. Auch werden Leerzeichen, die innerhalb von URLs nicht zulässig sind, entsprechend den geltenden Konventionen oftmals durch das Zeichen '+' dargestellt.
• Die Zeichen sind im obigen Zeichensatz als reservierte Zeichen enthalten, müssen aber im ursprünglichen Sinn des Zeichens verwendet werden. So wird beispielsweise ? in URLs für den Beginn eines Abfragestrings verwendet. Möchten Sie es stattdessen für den Text „? and the Mysterions“ verwenden, müssen Sie das Zeichen '?' codieren.

Alle Zeichen, die als URL codiert werden sollen, werden mithilfe des Zeichens '%' und eines Hexadezimalwerts aus zwei Zeichen codiert, der ihrem UTF-8-Zeichen entspricht. So würde zum Beispiel der UTF-8-String 上海+中國 durch die URL-Codierung in %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B umgewandelt. Und aus ? and the Mysterians würde %3F+and+the+Mysterians oder %3F%20and%20the%20Mysterians werden.

Häufig vorkommende Zeichen, die codiert werden müssen

Folgende häufig vorkommende Zeichen müssen codiert werden:

Die Konvertierung von URLs, die aus Nutzereingaben empfangen werden, kann manchmal Probleme mit sich bringen. Beispielsweise kann ein Nutzer eine Adresse als „5th&Main St.“ eingeben. Im Allgemeinen sollten Sie die URL aus ihren Teilen erstellen und jede Nutzereingabe wortwörtlich betrachten.

Außerdem sind URLs für alle Google Maps Platform-Webdienste und statischen Web APIs auf 16.384 Zeichen beschränkt. Bei den meisten Diensten wird diese Begrenzung selten erreicht. Beachten Sie jedoch, dass bestimmte Dienste einige Parameter haben, die zu langen URLs führen können.

Respektvolle Nutzung der Google APIs

Schlecht konzipierte API-Clients können sowohl das Internet als auch die Google-Server stärker belasten als nötig. Dieser Abschnitt enthält einige bewährte Methoden für Kunden der APIs. Wenn Sie diese Best Practices befolgen, lässt sich vermeiden, dass Ihre Anwendung aufgrund von unbeabsichtigtem Missbrauch der APIs blockiert wird.

Fehler und Wiederholversuche

Informationen zu den Antwortcodes UNKNOWN_ERROR oder OVER_QUERY_LIMIT der Geocoding API finden Sie unter Fehler und Wiederholungen verwalten.

Exponential Backoff

In seltenen Fällen kann beim Ausführen Ihrer Anfrage ein Fehler auftreten. Sie erhalten dann möglicherweise einen 4XX- oder 5XX-HTTP-Antwortcode oder die TCP-Verbindung bricht irgendwo zwischen Ihrem Client und dem Google-Server ab. Oft lohnt es sich, die Anfrage noch einmal zu stellen, da die Folgeanfrage erfolgreich sein kann, wenn die ursprüngliche fehlgeschlagen ist. Es ist jedoch wichtig, nicht einfach wiederholt Anfragen an die Google-Server zu senden. Dieses Looping-Verhalten kann das Netzwerk zwischen Ihrem Kunden und Google überlasten und zu Problemen für viele Parteien führen.

Ein besserer Ansatz ist es, wiederholte Versuche in immer größeren Abständen durchzuführen. Normalerweise wird die Verzögerung bei jedem Versuch um einen Multiplikator erhöht. Dieser Ansatz wird als exponentieller Backoff bezeichnet.

Angenommen, eine Anwendung möchte diese Anfrage an die Time Zone API senden:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Im folgenden Beispiel mit Python wird gezeigt, wie die Anforderung mit exponentiellem Backoff durchgeführt wird:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Außerdem sollten Sie darauf achten, dass sich in der Aufrufabfolge der Anwendung kein Code zum Wiederholen befindet, der zu wiederholten Anfragen in schneller Folge führt.

Synchronisierte Anforderungen

Eine große Anzahl synchronisierter Anfragen an die APIs von Google kann wie ein DDoS-Angriff (Distributed Denial of Service) auf die Infrastruktur von Google aussehen und entsprechend behandelt werden. Um dies zu vermeiden, sollten Sie dafür sorgen, dass API-Anfragen nicht zwischen Clients synchronisiert werden.

Angenommen, eine Anwendung zeigt die Zeit in der aktuellen Zeitzone an. Diese Anwendung stellt wahrscheinlich einen Wecker im Clientbetriebssystem ein, der es zu Beginn der Minute weckt, damit die angezeigte Uhrzeit aktualisiert werden kann. Die Anwendung darf im Rahmen der Verarbeitung, die mit dieser Benachrichtigung verknüpft ist, keine API-Aufrufe ausführen.

API-Aufrufe als Reaktion auf einen festen Wecker sind nicht empfehlenswert, da die API-Aufrufe dann sogar zwischen verschiedenen Geräten auf den Beginn der Minute synchronisiert werden, anstatt gleichmäßig über die Zeit verteilt zu werden. Eine schlecht konzipierte Anwendung, die dies tut, führt zu einem Anstieg der Zugriffe, der zu Beginn jeder Minute sechzigmal höher ist als normal.

Stattdessen wird bei einer guten Lösung ein zweiter Alarm für eine zufällig gewählte Zeit festgelegt. Wenn dieser zweite Alarm ausgelöst wird, ruft die Anwendung alle erforderlichen APIs auf und speichert die Ergebnisse. Wenn die Anwendung die Anzeige zu Beginn der Minute aktualisieren möchte, verwendet sie zuvor gespeicherte Ergebnisse, anstatt die API noch einmal aufzurufen. Bei diesem Ansatz werden API-Aufrufe gleichmäßig über die Zeit verteilt. Außerdem verzögern die API-Aufrufe das Rendering nicht, wenn das Display aktualisiert wird.

Neben dem Beginn der Minute sollten Sie nicht auch den Beginn einer Stunde und den Beginn eines jeden Tages um Mitternacht für die Synchronisierung verwenden.

Verarbeiten von Antworten

In diesem Abschnitt wird erklärt, wie Sie diese Werte dynamisch aus den Webdienstantworten extrahieren.

Die Google Maps-Webdienste liefern Antworten, die leicht verständlich, aber nicht gerade nutzerfreundlich sind. Wenn Sie eine Abfrage ausführen, möchten Sie wahrscheinlich nicht nur eine Datenmenge anzeigen lassen, sondern einige bestimmte Werte extrahieren. Im Allgemeinen sollten Sie Antworten vom Webservice parsen und nur die Werte extrahieren, die Sie interessieren.

Das verwendete Parseschema hängt davon ab, ob Sie die Ausgabe in XML oder JSON zurückgeben. JSON-Antworten, die bereits in Form von JavaScript-Objekten vorliegen, können im Client in JavaScript selbst verarbeitet werden. XML-Antworten sollten mit einem XML-Prozessor und einer XML-Abfragesprache verarbeitet werden, um Elemente im XML-Format anzusprechen. In den folgenden Beispielen verwenden wir XPath, da es in XML-Verarbeitungsbibliotheken häufig unterstützt wird.

Verarbeiten von XML mit XPath

XML ist ein relativ ausgereiftes Format für strukturierte Informationen, das für den Datenaustausch verwendet wird. XML ist zwar nicht so schlank wie JSON, bietet aber mehr Sprachunterstützung und robustere Tools. Code zur Verarbeitung von XML in Java ist beispielsweise in den javax.xml-Paketen enthalten.

Bei der Verarbeitung von XML-Antworten solltest du eine geeignete Abfragesprache für die Auswahl von Knoten im XML-Dokument verwenden, anstatt davon auszugehen, dass sich die Elemente an absoluten Positionen im XML-Markup befinden. XPath ist eine Sprachsyntax zum eindeutigen Beschreiben von Knoten und Elementen in einem XML-Dokument. Mit XPath-Ausdrücken können Sie bestimmte Inhalte im XML-Antwortdokument identifizieren.

XPath-Ausdrücke

Vorkenntnisse in XPath sind eine große Hilfe beim Entwickeln eines robusten Parsing-Schemas. In diesem Abschnitt geht es darum, wie Elemente in einem XML-Dokument mit XPath adressiert werden, damit Sie mehrere Elemente ansprechen und komplexe Abfragen erstellen können.

XPath verwendet Ausdrücke, um Elemente in einem XML-Dokument auszuwählen. Dabei wird eine Syntax verwendet, die der für Verzeichnispfade verwendeten ähnelt. Mit diesen Ausdrücken werden Elemente in einem XML-Dokumentbaum identifiziert, einem hierarchischen Baum, der dem eines DOM ähnelt. XPath-Ausdrücke sind im Allgemeinen „unersättlich“, d. h., sie stimmen mit allen Knoten überein, die den angegebenen Kriterien entsprechen.

Wir verwenden das folgende abstrakte XML-Beispiel, um unsere Beispiele zu veranschaulichen:

<WebServiceResponse>
 <status>OK</status>
 <result>
  <type>sample</type>
  <name>Sample XML</name>
  <location>
   <lat>37.4217550</lat>
   <lng>-122.0846330</lng>
  </location>
 </result>
 <result>
  <message>The secret message</message>
 </result>
</WebServiceResponse>

Auswahl von Knoten in Ausdrücken

Mit XPath-Auswahlen werden Knoten ausgewählt. Der Stammknoten umfasst das gesamte Dokument. Sie wählen diesen Knoten mit dem speziellen Ausdruck „/“ aus. Der Stammknoten ist nicht der Knoten der obersten Ebene Ihres XML-Dokuments. Er befindet sich tatsächlich eine Ebene über diesem Element der obersten Ebene und enthält es.

Elementknoten repräsentieren die verschiedenen Elemente im XML-Dokumentbaum. Ein <WebServiceResponse>-Element stellt beispielsweise das Element der obersten Ebene dar, das in unserem Beispieldienst oben zurückgegeben wurde. Einzelne Knoten werden entweder über absolute oder relative Pfade ausgewählt, was durch das Vorhandensein oder Fehlen des Zeichens „/“ am Anfang angezeigt wird.

• Absolutpfad: Mit dem Ausdruck „/WebServiceResponse/result“ werden alle <result>-Knoten ausgewählt, die dem Knoten <WebServiceResponse> untergeordnet sind. Beachten Sie, dass beide Elemente vom Stammknoten „/“ abgeleitet sind.
• Relativer Pfad vom aktuellen Kontext: Der Ausdruck „result“ würde mit allen <result>-Elementen im aktuellen Kontext übereinstimmen. Im Allgemeinen müssen Sie sich keine Gedanken über den Kontext machen, da Sie die Ergebnisse von Webdiensten in der Regel über einen einzelnen Ausdruck verarbeiten.

Beide Ausdrücke können durch einen Platzhalterpfad ergänzt werden, der durch einen doppelten Schrägstrich („//“) gekennzeichnet ist. Dieser Platzhalter gibt an, dass im Zwischenpfad null oder mehr Elemente übereinstimmen können. Der XPath-Ausdruck „//formatted_address“ entspricht beispielsweise allen Knoten dieses Namens im aktuellen Dokument. Der Ausdruck //viewport//lat würde mit allen <lat>-Elementen übereinstimmen, die <viewport> als übergeordnetes Element haben.

Standardmäßig werden durch XPath-Ausdrücke alle übereinstimmenden Elemente ausgewählt. Sie können den Ausdruck auf ein bestimmtes Element beschränken, indem Sie ein Prädikat angeben, das in eckige Klammern ([]) gesetzt ist. Der XPath-Ausdruck „/GeocodeResponse/result[2]“ gibt beispielsweise immer das zweite Ergebnis zurück.

    <WebServiceResponse>
     <status>OK</status>
     <result>
      <type>sample</type>
      <name>Sample XML</name>
      <location>
       <lat>37.4217550</lat>
       <lng>-122.0846330</lng>
      </location>
     </result>
     <result>
      <message>The secret message</message>
     </result>
    </WebServiceResponse>
    

    <result>
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    </result>
    <result>
     <message>The secret message</message>
    </result>
    

    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
    

    <message>The secret message</message>
    

     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    

    Sample XML
    

Beachten Sie, dass Sie beim Auswählen von Elementen Knoten auswählen, nicht nur den Text in diesen Objekten. Im Allgemeinen sollten Sie alle übereinstimmenden Knoten durchgehen und den Text extrahieren. Sie können auch Textknoten direkt abgleichen. Weitere Informationen finden Sie unten unter Textknoten .

XPath unterstützt auch Attributknoten. Da alle Google Maps-Webdienste jedoch Elemente ohne Attribute bereitstellen, ist kein Attributabgleich erforderlich.

Auswahl von Text in Ausdrücken

Text in einem XML-Dokument wird in XPath-Ausdrücken über einen Textknoten-Operator angegeben. Der Operator „text()“ gibt an, dass Text aus dem angegebenen Knoten extrahiert wird. Mit dem XPath-Ausdruck „//formatted_address/text()“ wird beispielsweise der gesamte Text innerhalb von <formatted_address>-Elementen zurückgegeben.

    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
    

    The secret message
    

    Sample XML
    

Alternativ können Sie einen Ausdruck auswerten und eine Reihe von Knoten zurückgeben und dann über diesen „Knotensatz“ iterieren, um den Text aus jedem Knoten zu extrahieren. Dieser Ansatz wird im Beispiel unten verwendet.

Weitere Informationen zu XPath finden Sie in der XPath-W3C-Spezifikation.

XPath in Java auswerten

Java bietet umfassende Unterstützung für das Parsen von XML und die Verwendung von XPath-Ausdrücken im javax.xml.xpath.*-Paket. Aus diesem Grund wird im Beispielcode in diesem Abschnitt Java verwendet, um zu veranschaulichen, wie XML verarbeitet und Daten aus XML-Dienstantworten geparst werden.

Wenn Sie XPath in Ihrem Java-Code verwenden möchten, müssen Sie zuerst eine Instanz einer XPathFactory erstellen und newXPath() auf diese Fabrik anwenden, um ein XPath -Objekt zu erstellen. Dieses Objekt kann dann übergebene XML- und XPath-Ausdrücke mit der Methode evaluate() verarbeiten.

Achten Sie bei der Auswertung von XPath-Ausdrücken darauf, alle möglichen „Knotenmengen“ zu durchlaufen, die zurückgegeben werden können. Da diese Ergebnisse als DOM-Knoten im Java-Code zurückgegeben werden, sollten Sie diese mehreren Werte in einem NodeList-Objekt erfassen und über dieses Objekt iterieren, um Text oder Werte aus diesen Knoten zu extrahieren.

Im folgenden Code wird gezeigt, wie ein XPath-Objekt erstellt, ihm XML und ein XPath-Ausdruck zugewiesen und der Ausdruck ausgewertet wird, um die relevanten Inhalte zu drucken.

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}