Google-Karte zeigt Fehler: API-Schlüssel richtig einschränken
Kurz gesagt: Die Google-Karte auf Ihrer Kontaktseite zeigt plötzlich nur noch eine graue Fläche, eine abgedunkelte Karte mit dem Hinweis „for development purposes only“ oder eine Fehlermeldung. Häufig passiert das kurz nachdem jemand den API-Schlüssel abgesichert, die Domain gewechselt oder die Zahlungsdaten im Google-Cloud-Konto geändert hat. Die Ursache steht fast immer in der JavaScript-Konsole des Browsers, als Fehlercode wie RefererNotAllowedMapError. Mit diesem Code lässt sich das Problem gezielt beheben, meist in wenigen Minuten in der Cloud Console.
Welche Art von Karte betroffen ist
Es gibt zwei verbreitete Arten, eine Google-Karte einzubinden:
- Eingebettete Karte per iframe, die man in Google Maps über „Teilen“ und „Karte einbetten“ erhält. Sie braucht keinen eigenen API-Schlüssel und ist von den hier beschriebenen Fehlern in der Regel nicht betroffen.
- Karte über die Maps JavaScript API, oft von einem Theme, Plugin oder Kartenbaustein geladen. Sie braucht einen API-Schlüssel, ein Projekt in der Google Cloud und eine aktive Abrechnung.
Die folgenden Schritte betreffen die zweite Variante. Welche Sie haben, verrät meist der Quelltext der Seite oder die Einstellung des Kartenbausteins.
Den Fehlercode finden
Laut Google schreibt die Maps JavaScript API Fehler- und Warnmeldungen in die JavaScript-Konsole des Browsers. So finden Sie sie:
- Seite mit der Karte im Browser am Rechner öffnen.
- Entwicklerwerkzeuge öffnen, meist mit F12, und den Reiter „Konsole“ wählen.
- Seite neu laden.
- Nach einer Meldung suchen, die mit „Google Maps JavaScript API error“ beginnt und einen Code nennt.
Ein Beispiel zur Veranschaulichung: Ein Reitstall bei Wiener Neustadt hat auf seiner Website eine Karte mit Anfahrt und Reitwegen. Nach einem Hinweis, den API-Schlüssel abzusichern, hat der Betreiber in der Cloud Console Website-Einschränkungen eingetragen. Seitdem zeigt die Karte einen Fehler. In der Konsole steht RefererNotAllowedMapError. Eingetragen war nur https://reitstall-beispiel.at, die Website läuft aber unter https://www.reitstall-beispiel.at.
Die häufigsten Fehlercodes
Die Fehlerliste von Google nennt unter anderem:
- RefererNotAllowedMapError: Die aktuelle Adresse, die die API lädt, steht nicht auf der Liste erlaubter Websites. Prüfen Sie laut Google die Website-Einschränkungen Ihres Schlüssels.
- ApiNotActivatedMapError: Die Maps JavaScript API ist in Ihrem Projekt nicht aktiviert.
- ApiTargetBlockedMapError: Der Schlüssel darf diese API nicht verwenden. Prüfen Sie die API-Einschränkungen des Schlüssels.
- BillingNotEnabledMapError: Für das Projekt ist keine Abrechnung aktiviert.
- InvalidKeyMapError: Der im Skript angegebene Schlüssel wurde nicht gefunden, etwa weil er gelöscht oder falsch kopiert wurde.
Eine abgedunkelte Karte mit dem Wasserzeichen „for development purposes only“ deutet laut Google typischerweise auf Probleme mit dem Schlüssel oder der Abrechnung hin.
Website-Einschränkungen richtig eintragen
Website-Einschränkungen sind sinnvoll: Sie verhindern, dass fremde Seiten Ihren Schlüssel verwenden und Kosten verursachen. Google empfiehlt in seinen Sicherheitshinweisen für Schlüssel, die im Browser verwendet werden, genau diese Einschränkung. Damit sie funktioniert, muss sie vollständig sein.
Laut Google gilt:
- Die ganze Adresse angeben, einschließlich Schema, also
https://, Hostname und gegebenenfalls Port. - Platzhalter für Subdomains sind möglich:
https://*.beispiel.aterlaubt alle Adressen, die auf.beispiel.atenden. - Vorsicht bei vollständigen Pfaden: Die meisten Browser entfernen laut Google aus Datenschutzgründen den Pfad bei Anfragen an andere Domains. Eine Einschränkung auf
https://beispiel.at/kontaktkann deshalb fehlschlagen.
Eine praxistaugliche Liste für viele Betriebe:
https://beispiel.athttps://*.beispiel.atfür www und eventuelle Subdomains
Wenn Sie eine Testumgebung unter einer anderen Domain haben, braucht diese einen eigenen Eintrag oder besser einen eigenen Schlüssel.
API-Einschränkungen prüfen
Zusätzlich zur Website lässt sich ein Schlüssel auf bestimmte Dienste beschränken, etwa nur die Maps JavaScript API. Das ist gut, kann aber zu ApiTargetBlockedMapError führen, wenn Ihre Karte zusätzliche Dienste nutzt, zum Beispiel die Ortssuche oder die Adressumwandlung. Nehmen Sie alle Dienste in die Liste auf, die Ihre Karte tatsächlich braucht, und nicht mehr.
Abrechnung und Projekt
Laut Google muss für die Nutzung der Maps-Platform-Produkte die Abrechnung im Konto aktiviert sein, und jede Anfrage braucht einen gültigen Schlüssel. Wenn eine hinterlegte Zahlungskarte abgelaufen ist oder das Abrechnungskonto vom Projekt getrennt wurde, hört die Karte auf zu funktionieren. Prüfen Sie in der Cloud Console, ob das richtige Projekt mit einem aktiven Abrechnungskonto verknüpft ist. Legen Sie eine Person fest, die Mitteilungen von Google zu diesem Konto erhält und liest.
Wer hat Zugriff auf das Projekt?
Oft weiß im Betrieb niemand mehr, wer die Karte damals eingerichtet hat und mit welchem Google-Konto. Dann wird die Fehlersuche schwierig. Klären Sie deshalb:
- Mit welchem Google-Konto ist das Cloud-Projekt verbunden?
- Wer hat dort Zugriff, und ist mindestens eine Person aus dem Betrieb selbst dabei, nicht nur die frühere Agentur?
- Auf welchen Namen läuft das Abrechnungskonto?
Halten Sie diese Angaben an einer Stelle fest, zusammen mit dem Hinweis, welcher Schlüssel auf welcher Website verwendet wird. Wenn eine Agentur das Projekt verwaltet, lassen Sie sich Zugriff einräumen, damit Sie im Fehlerfall nicht warten müssen.
Nach der Korrektur prüfen
Öffnen Sie nach jeder Änderung die Seite im privaten Fenster, mit und ohne www, am Rechner und am Handy. Die Konsole sollte keine Fehlermeldung mehr zeigen.
Wann eine einfachere Lösung reicht
Viele Websites brauchen keine programmierte Karte. Wenn die Karte nur den Standort zeigt:
- Eine eingebettete Karte per iframe genügt und kommt ohne eigenen Schlüssel aus.
- Ein Routenlink neben der Adresse ist oft nützlicher als jede Karte.
- Ein statisches Kartenbild mit Link zu Google Maps lädt schnell.
Eine programmierte Karte lohnt sich, wenn Sie mehrere Standorte, eigene Markierungen, Filter oder Routen zeigen möchten. Für eine einzige Adresse ist sie meist mehr Aufwand, als sie nützt, und bringt laufende Pflege für Schlüssel und Abrechnung mit sich.
Häufige Fragen
Warum funktioniert die Karte nur ohne www?
Weil in den Website-Einschränkungen nur eine Variante eingetragen ist. Ergänzen Sie die fehlende Variante oder einen Platzhalter für Subdomains.
Kann ich die Einschränkung einfach entfernen?
Technisch ja, empfehlenswert ist es nicht. Ein offener Schlüssel kann von fremden Seiten genutzt werden.
Wie lange dauert es, bis Änderungen wirken?
Oft nur wenige Minuten. Laden Sie die Seite danach neu und prüfen Sie die Konsole erneut.
Ich sehe keine Fehlermeldung, die Karte ist aber leer. Was nun?
Prüfen Sie, ob ein Cookie- oder Einwilligungs-Banner die Karte blockiert, bis zugestimmt wird. Auch das führt zu leeren Flächen.
Wenn Ihre Karte nicht mehr angezeigt wird oder Sie den Schlüssel sicher einrichten möchten, bringen wir die Karte gemeinsam wieder zum Laufen: Karte prüfen lassen.