Die statischen Web-APIs der Google Maps Platform sind eine Sammlung von HTTP-Schnittstellen, mit denen Bilder generiert werden, die sich direkt in Ihre Webseite einbetten lassen.
Die Webdienste der Google Maps Platform sind eine Sammlung von HTTP-Schnittstellen, die geografische Daten für Ihre Kartenanwendungen bereitstellen.
In diesem Leitfaden werden einige gängige Verfahren beschrieben, die für das Einrichten von Bild- und Webdienstanfragen und das Verarbeiten von Dienstantworten nützlich sind. Weitere Informationen zur Street View Static API finden Sie im Entwicklerhandbuch.
Die Street View Static API verhält sich wie eine statische Web-API, während der Metadatendienst als Webdienst fungiert. Weitere Informationen zum Metadatendienst finden Sie unter Street View-Bildmetadaten.
Was ist eine Static Web API?
Mit den Static Web APIs der Google Maps Platform können Sie ein Google Maps-Bild in Ihre Webseite einbetten, ohne dass JavaScript oder dynamischer Seitenaufbau erforderlich ist. Die statischen Web-APIs erstellen ein Bild basierend auf URL-Parametern, die über eine Standard-HTTPS-Anfrage gesendet werden.
Eine typische Anfrage an die Street View Static API hat folgendes Format:
https://www.googleapis.com/streetview/z/x/y?parameters
Was ist ein Webdienst?
Die Webdienste der Google Maps Platform sind eine Schnittstelle, über die Sie 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 Google Maps-APIs verwenden HTTP- oder HTTPS-Anfragen an bestimmte URLs und übergeben URL-Parameter oder POST-Daten im JSON-Format als Argumente an die Dienste. Im Allgemeinen geben diese Dienste Daten im Antworttext als JSON-Datei zurück, die von Ihrer Anwendung geparst oder verarbeitet werden kann.
Eine Metadatenanfrage an die Street View Static API hat folgendes Format:
https://maps.googleapis.com/maps/api/streetview/parameters
SSL- und TLS-Zugriff
HTTPS ist für alle Google Maps Platform-Anfragen erforderlich, die API-Schlüssel verwenden oder Nutzerdaten enthalten. Anfragen über HTTP, die vertrauliche 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:
| Zeichensatz | Zeichen | Verwendung in der URL |
|---|---|---|
| Alphanumerisch | a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 | Textstrings, Schemas (http), Portangaben (8080) usw. |
| Nicht reserviert | - _ . ~ | Textstrings |
| Reserviert | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Steuerzeichen und/oder Textstrings |
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:
| Unsicheres Zeichen | Codierter Wert |
|---|---|
| Leerzeichen | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
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 Zeichenbeschränkung selten erreicht. Beachten Sie jedoch, dass bestimmte Dienste einige Parameter haben, die zu langen URLs führen können.
Höfliche Verwendung von Google APIs
Schlecht konzipierte API-Clients können das Internet und Server stark belasten. Dieser Abschnitt enthält Best Practices für API-Clients. Wenn Sie diese Best Practices befolgen, können Sie verhindern, dass Ihre Anwendung aufgrund eines unbeabsichtigten Missbrauchs der APIs blockiert wird.
Exponentielle Backoffs
In seltenen Fällen kann bei Ihrer Anfrage ein Fehler auftreten. Möglicherweise erhalten Sie einen HTTP-Antwortcode 4xx oder 5xx oder die TCP-Verbindung schlägt irgendwo zwischen Ihrem Client und dem Google-Server fehl. Oft lohnt es sich, die Anfrage noch einmal zu senden, da die Folgeanfrage erfolgreich sein kann, wenn die ursprüngliche Anfrage fehlgeschlagen ist. Es ist jedoch wichtig, nicht wiederholt Anfragen an die Google-Server zu senden. Dieses Schleifenverhalten kann das Netzwerk zwischen Ihrem Client und Google überlasten und Probleme für viele Beteiligte verursachen.
Ein besserer Ansatz ist es, wiederholte Versuche in immer größeren Abständen durchzuführen. Die Verzögerung erhöht sich in der Regel mit jedem Versuch um einen Multiplikationsfaktor. Dieser Ansatz wird als exponentieller Backoff bezeichnet.
Angenommen, eine Anwendung sendet die folgende Anfrage an die Time Zone API:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331161200&key=YOUR_API_KEYIm folgenden Python-Beispiel wird gezeigt, wie die Anfrage mit exponentiellem Backoff gestellt wird:
import json import time import urllib.error import urllib.parse import urllib.request # The maps_key defined in the following code 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 the request didn't produce an IOError, parse the result. result = json.load(response) if result["status"] == "OK": return result["timeZoneId"] elif result["status"] != "UNKNOWN_ERROR": # Many API errors can't be fixed by a retry, such as # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry. if __name__ == "__main__": tz = timezone(39.6034810, -119.6822510, 1331161200) print(f"Timezone: {tz}")
Achten Sie darauf, dass es in der Aufrufkette der Anwendung keinen Wiederholungscode gibt, der zu wiederholten Anfragen in schneller Folge führt.
Synchrone Anfragen
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 dieses Problem zu vermeiden, sollten API-Anfragen nicht zwischen Clients synchronisiert werden.
Angenommen, Sie haben eine Anwendung, die die Uhrzeit in der aktuellen Zeitzone anzeigt. Diese Anwendung stellt wahrscheinlich einen Wecker im Client-Betriebssystem ein, um es zu Beginn der Minute zu wecken, damit die angezeigte Zeit aktualisiert werden kann. Führen Sie in der Anwendung keine API-Aufrufe im Rahmen der Verarbeitung im Zusammenhang mit diesem Alarm aus.
API-Aufrufe als Reaktion auf einen festen Alarm sind nicht empfehlenswert, da die API-Aufrufe dann mit dem Beginn der Minute synchronisiert werden, auch zwischen verschiedenen Geräten, anstatt gleichmäßig über die Zeit verteilt zu werden. Eine schlecht konzipierte Anwendung, die dies tut, erzeugt zu Beginn jeder Minute eine Trafficspitze, die das 60-Fache des normalen Traffics beträgt.
Stattdessen können Sie die Anwendung so entwerfen, dass ein zweiter Alarm zu einer zufällig ausgewählten Zeit eingestellt wird. Wenn dieser zweite Alarm ausgelöst wird, ruft die Anwendung alle erforderlichen APIs auf und speichert die Ergebnisse. Wenn die Anwendung ihre Anzeige zu Beginn der Minute aktualisiert, 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 die Anzeige aktualisiert wird.
Abgesehen vom Beginn der Minute sollten Sie keine anderen gängigen Synchronisierungszeiten wie den Beginn einer Stunde und den Beginn eines Tages um Mitternacht als Ziel festlegen.
Antworten verarbeiten
Da das genaue Format einzelner Antworten auf eine Webdienst-Anfrage nicht garantiert ist (einige Elemente können fehlen oder an mehreren Stellen vorhanden sein), sollten Sie nicht davon ausgehen, dass das für eine bestimmte Antwort zurückgegebene Format für verschiedene Abfragen identisch ist. Verarbeiten Sie stattdessen die Antwort und wählen Sie mithilfe von Ausdrücken die entsprechenden Werte aus.
In diesem Abschnitt wird erläutert, wie Sie diese Werte dynamisch aus Webdienstantworten extrahieren.
Die Google Maps-Webdienste liefern Antworten, die zwar verständlich, aber nicht nutzerfreundlich sind. Wenn Sie eine Abfrage ausführen, möchten Sie wahrscheinlich nicht eine Reihe von Daten anzeigen, sondern einige bestimmte Werte extrahieren. Im Allgemeinen parsen Sie Antworten vom Webdienst und extrahieren nur die Werte, die Sie interessieren.
Das verwendete Parsingschema hängt davon ab, ob Sie die Ausgabe im JSON-Format zurückgeben. JSON-Antworten liegen bereits in Form von JavaScript-Objekten vor und können in JavaScript auf dem Client verarbeitet werden.