Voraussetzungen
Bei allen Anwendungen werden diverse APIs von Google Maps genutzt. Diese müssen unabhängig von den Anwendungen zunächst im System verfügbar gemacht werden. Hierzu muss bei Google ein Konto eröffnet, ein Projekt angelegt und ein sogenannter API-Schlüssel für Google Maps erzeugt werden. Dieser API-Schlüssel muss im ACP unter Konfiguration - Allgemein - System - Browser-API-Schlüssel hinterlegt werden.
Da es sich bei Google Maps grundsätzlich um einen kostenpflichtigen Dienst handelt, müssen zur Nutzung der APIs ein Abrechnungskonto erstellt und Zahlungsinformationen hinterlegt werden. In der Regel muss dabei eine Kreditkarte angegeben werden, damit Google entstehende Kosten direkt einziehen kann. Mehr zu den Kosten unten.
Erstellung des API-Schlüssels
Hierauf wird nicht im Detail eingegangen, da es bereits einige Anleitung im Netz gibt.
Eine nach meiner Bewertung gute deutschsprachige Anleitung ist unter Google Maps Api Key erstellen verfügbar. Im ACP wird zu diesem Zweck auf die englischsprachige Google-Seite Get an API Key verwiesen. Nach Aufruf dieser Seite lässt sich durch Klick auf GET STARTED eine dialogbasierte Erstellung in der gewünschten Sprache starten.
Benötigte APIs
Alle Karten-Anwendungen benötigen mindestens die folgenden Google Maps APIs:
- Maps JavaScript API
- Geocoding API
Anwendungen, wie die Benutzerkarte, die eine Routenplanung ermöglichen, benötigen zudem die folgende Google Maps API:
- Directions API
Mit den Standardeinstellungen nach Schlüsselgenerierung und den o.a. APIs sollten alle Anwendungen mit Kartenfunktionen direkt funktionieren.
Konfiguration im ACP
Nach Eingabe des API-Schlüssels sollte die grundlegende Karten-Konfiguration im ACP überprüft bzw. angepasst werden. Dies erfolgt unter Konfiguration - Allgemein - System - Google Maps. Hier sind insbesondere der Karten-Zoom und die Standard-Kartenposition (Breiten-/Längengrad) interessant, weil sie den Inhalt der Karte direkt nach dem Öffnen festlegen.
Bei der Benutzerkarte kann dies optional auch der Anwendung überlassen werden; sie kann die dargestellte Karte automatisch an die bisherigen Eingaben anpassen.
Bedienung
Die Bedienung der Karte ist bei allen Anwendungen identisch, weil sie identische Schnittstellen zu Google Maps nutzen.
Ortseingaben können entweder über Bewegen eines Markers auf der Karte (wenn angeboten) oder über Eingabe von Text in einem Feld gemacht werden. Bei Letzteren ist zu beachten, dass beim Eingeben des Textes im Hintergrund eine Google Maps-Suche nach passenden Orten gestartet wird. Sobald passende Orte gefunden werden, werden unterhalb des Feldes Vorschläge angezeigt, die gewählt werden können bzw. sollten. Dem entsprechend sollte die Texteingabe eher langsam und mit etwas Geduld erfolgen.
Zeigt Google keine Ergebnisse an, so wurde der Ort nicht gefunden oder es liegt ein Fehler vor. Dann sollte die Funktion der Karte geprüft werden.
Prüfung der Funktion
Wenn die Karte nicht so funktioniert wie gewünscht, sollte immer zunächst über die JavaScript-Konsole im Browser geprüft werden, ob Fehler vorliegen. Die Konsole kann über die Funktionstaste F12 geöffnet werden. Erfahrungsgemäß liegt bei Fehlern eine Fehlkonfiguration des API-Schlüssels im Google-Konto vor.
Ein typischer Fehler ist im Bild dargestellt; hier wurde das Limit für die Nutzung der Geocoding-API überschritten und Google Maps verweigert deswegen die weitere Nutzung der API.Nutzern der Benutzerkarte wird empfohlen, regelmäßig das Protokoll der Benutzerkarte im ACP zu kontrollieren. Dort werden auch Hinweise auf Probleme gespeichert.
Kosten und Einschränkungen
Wie schon erwähnt, ist der Google Kartendienst nicht kostenlos. Für jeden Kartenaufruf und für jeden Aufruf der Geocoding- oder Routing-API berechnet Google einen kleinen Betrag. Dieser liegt je nach API, Funktion und Kostenmodell zwischen 0,004 und 0,014 USD. So muss ein normaler Anwender zum Beispiel für 1.000 Kartenaufrufe immerhin 7,00 USD bezahlen.
Allerdings gewährt Google einen Freibetrag in Höhe von 200,00 USD. Erst, wenn dieser überschritten wird, fallen reale Kosten an. Im u.a. Beispiel fallen also Kosten erst ab dem 28571. Kartenaufruf an - wenn nicht schon Kosten für Geocoding und/oder Routing berechnet wurden.
Um insbesondere bei größeren Communities nicht in eine Kostenfalle zu geraten, empfiehlt es sich die Nutzung des API-Schlüssels sowie der APIs einzuschränken.
Dies erfolgt zum einen über Schlüssel-Einschränkungen, die eine nicht autorisierte Verwendung des Schlüssels und einen Kontingentdiebstahl verhindern sollen; siehe dazu die Seite API-Schlüssel einschränken und umbenennen im Google-Konto. Und zum anderen lassen sich die Kontingente für die erlaubten APIs einschränken. So kann man z.B. festlegen, dass nur 500 Kartenaufrufe pro Tag erlaubt sind. Bei 0,007 USD je Aufruf werden dann im Monat nur maximal ca. 105,00 USD an Kosten für Kartenaufrufe berechnet.
Bei Problemen nach Implementierung von Schlüssel-Einschränkungen sind diese zu überprüfen und ggf. anzupassen. So kann es z.B. zu Problemen führen, wenn man unter Website-Einschränkungen einzelne Seiten einträgt. Erfahrungsgemäß hilft es, nur die Top-Level-Domain mit Schrägstrich und Sternchen einzutragen; z.B. https://meine_seite.de/*.
Zusätzlicher Browser-API-Schlüssel
Bei den Anwendungen Benutzerkarte und Points of Interest besteht die Möglichkeit, einen zusätzlichen Browser-API-Schlüssel für das Geocoding anzugeben, der dann intern für einige Funktionen (Suche, Import, Synchronisation) genutzt wird. Dies erleichtert die Umsetzung von Schlüssel-Einschränkungen des im System genutzten primären Schlüssels. Der zusätzliche Schlüssel sollte mit geeigneten Limits auf die Geocoding-API eingeschränkt werden.
Häufige Fehler
Benutzerkarte aktualisiert nicht
Es funktioniert nicht, wenn der Google API Schlüssel über Referer limitiert ist.
Wenn der API Schlüssel über das Server IP Subnetz limitiert ist, läuft es.