Übersicht

Plattform auswählen: Android iOS JavaScript

Mit der Maps JavaScript API können Sie Karten mit eigenen Inhalten und Bildern für die Anzeige auf Webseiten und Mobilgeräten anpassen. Die Maps JavaScript API umfasst vier Basiskartentypen (Straßen-, Satelliten-, hybride und Geländekarte), die Sie mithilfe von Ebenen und Stilen, Steuerelementen und Ereignissen sowie verschiedenen Diensten und Bibliotheken anpassen können.

Zielgruppe

Diese Dokumentation richtet sich an Personen, die sich mit JavaScript und objektorientierten Programmierungskonzepten auskennen. Außerdem sollten Sie mit Google Maps aus Sicht des Nutzers vertraut sein. Im Web sind viele JavaScript-Anleitungen verfügbar.

Diese konzeptbezogene Dokumentation soll Ihnen einen schnellen Einstieg in die Verwendung und Entwicklung von Anwendungen mit der Maps JavaScript API ermöglichen. Weitere Informationen sind in der Referenz zur Maps JavaScript API verfügbar.

Hello World

Mit einem einfachen Beispiel gelingt der Einstieg in die Maps JavaScript API am leichtesten. Im folgenden Beispiel wird eine Karte angezeigt, deren Mittelpunkt Sydney, New South Wales, Australien ist.

TypeScript

let map: google.maps.Map;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
#map {
  height: 100%;
}

/*
 * Optional: Makes the sample page fill the window.
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

style.css

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!--
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html
Beispiel ansehen

Testbeispiel

Selbst bei diesem einfachen Beispiel sind einige Dinge zu beachten:

  1. Mithilfe der <!DOCTYPE html>-Deklaration wird die Anwendung als HTML5 deklariert.
  2. Es muss ein div-Element namens „map“ erstellt werden, das die Karte enthält.
  3. Es wird eine JavaScript-Funktion definiert, die eine Karte im div-Element erstellt.
  4. Die Maps JavaScript API wird mit einem script-Tag geladen.

Diese Schritte sind nachfolgend beschrieben.

Anwendung als HTML5 deklarieren

Wir empfehlen, einen echten DOCTYPE in Ihrer Webanwendung zu deklarieren. In den Beispielen hier haben wir die Anwendungen über den einfachen HTML5-DOCTYPE als HTML5 deklariert (siehe unten):

<!DOCTYPE html>

Die meisten aktuellen Browser rendern Inhalte, die mit diesem DOCTYPE deklariert sind, im „Standardmodus“. Ihre Anwendung sollte daher browserübergreifend kompatibler sein. Der DOCTYPE ist für das Prinzip der „Graceful Degradation“ konzipiert. Browser, die ihn nicht verstehen, ignorieren ihn und verwenden den Quirks-Modus, um den Inhalt anzuzeigen.

Bestimmte CSS, die im Quirks-Modus funktionieren, sind im Standardmodus nicht gültig. Insbesondere müssen alle prozentualen Größen von übergeordneten Blockelementen übernommen werden. Wenn für einen der Ancestors keine Größe angegeben ist, wird davon ausgegangen, dass er eine Größe von 0 × 0 Pixeln hat. Daher wird die folgende <style>-Deklaration eingefügt:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Diese CSS-Deklaration gibt an, dass der <div>-Kartencontainer (mit der ID map) 100 % der Höhe des HTML-Textkörpers einnehmen soll. Auch für <body> und <html> müssen diese Prozentsätze ausdrücklich deklariert werden.

Maps JavaScript API laden

Die Maps JavaScript API wird mit einem script-Tag geladen, das direkt (inline) in Ihre HTML-Datei oder dynamisch mit einer separaten JavaScript-Datei eingefügt werden kann. Am besten setzen Sie sich mit beiden Ansätzen auseinander und wählen denjenigen aus, der für die Codestruktur Ihres Projekts am besten geeignet ist.

Inline laden

Um die Maps JavaScript API direkt (inline) in einer HTML-Datei zu laden, fügen Sie wie unten gezeigt ein script-Tag ein.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Dynamisch laden

Im folgenden Beispiel wird die Maps JavaScript API dynamisch über eine separate JavaScript-Datei geladen. Bei diesem Ansatz können Sie Ihren gesamten Code für die Arbeit mit der API über eine separate .js-Datei verwalten. Dies entspricht der Inline-Einbindung des Skript-Tags.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

Dynamisch laden

Das Paket @googlemaps/js-api-loader ist verfügbar, um das dynamische Laden nahtloser zu gestalten. So wird es über NPM installiert:

npm install @googlemaps/js-api-loader

So wird das Paket in die Anwendung importiert:

import { Loader } from "@googlemaps/js-api-loader"

Das Ladeprogramm zeigt eine Promise- und Callback-Oberfläche an. Im Folgenden wird die Verwendung der standardmäßigen Promise-Methode load() veranschaulicht.

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

Skript-Tag-Attribute

In den Beispielen oben sind mehrere empfohlene Attribute für das Tag script festgelegt. Nachfolgend werden die einzelnen Attribute erläutert.

  • src: Die URL, von der die Maps JavaScript API geladen wird, einschließlich aller Symbole und Definitionen, die Sie für die Verwendung der Maps JavaScript API benötigen. In diesem Beispiel hat die URL zwei Parameter: key zum Angeben des API-Schlüssels und callback für den Namen einer globalen Funktion, die aufgerufen werden soll, sobald die Maps JavaScript API vollständig geladen wurde. Weitere Informationen zu URL-Parametern
  • async: Weist den Browser an, das Skript asynchron herunterzuladen und auszuführen. Wenn das Skript ausgeführt wurde, wird die Funktion aufgerufen, die mit dem Parameter callback angegeben wurde.

Bibliotheken

Wenn die Maps JavaScript API über die URL geladen wird, können Sie mithilfe des URL-Parameters libraries optional weitere Bibliotheken laden. Bibliotheken sind Codemodule, die zusätzliche Funktionen für die primäre JavaScript API bieten. Sie werden nur geladen, wenn sie ausdrücklich angefordert werden. Weitere Informationen

API synchron laden

Im script-Tag, mit dem die Maps JavaScript API geladen wird, können das Attribut defer und der Parameter callback weggelassen werden. Dadurch wird das Laden der API blockiert, bis sie vollständig heruntergeladen ist.

Dadurch wird die Seite wahrscheinlich langsamer geladen. Sie können aber nachfolgende Skript-Tags in der Gewissheit schreiben, dass die API bereits geladen ist.

DOM-Kartenelemente

<div id="map"></div>

Damit die Karte auf einer Webseite angezeigt werden kann, muss ein Platz für sie reserviert werden. Dazu wird normalerweise ein benanntes div-Element erstellt, auf das im DOM (Document Object Model) des Browsers verwiesen wird.

Im Beispiel oben haben wir CSS verwendet, um die Höhe des „div“-Elements der Karte auf „100 %“ festzulegen. Dadurch wird die Größe an den Bildschirm des jeweiligen Mobilgeräts angepasst. Möglicherweise müssen Sie die Werte für Breite und Höhe an die Bildschirmgröße und den Abstand des Browsers anpassen. „div“-Elemente übernehmen die Breite in der Regel von ihrem Container. Leere „div“-Elemente haben normalerweise eine Höhe von 0. Daher müssen Sie für <div> immer explizit eine Höhe festlegen.

Kartenoptionen

Für jede Karte sind zwei Optionen erforderlich: center und zoom.

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

Zoomstufen

Die anfängliche Auflösung, mit der die Karte angezeigt werden soll, wird über die zoom-Eigenschaft definiert. Dabei entspricht die Zoomstufe 0 einer vollständig herausgezoomten Karte der Erde. Durch höhere Zoomstufen wird eine höhere Auflösung erzielt.

zoom: 8

Um die gesamte Erde in einem einzigen Bild darzustellen, wäre entweder eine riesige Karte oder eine kleine Karte mit sehr geringer Auflösung erforderlich. Daher werden Kartenbilder in Google Maps und der Google Maps API in Kartenkacheln und Zoomstufen unterteilt. Bei niedrigen Zoomstufen decken wenige Kartenkacheln einen großen Bereich ab. Bei höheren Stufen haben die Kacheln eine höhere Auflösung und decken einen kleineren Bereich ab. Die folgende Liste enthält die ungefähre Detailebene, die Sie bei der jeweiligen Zoomstufe erwarten können:

  • 1: Welt
  • 5: Landmasse/Kontinent
  • 10: Stadt
  • 15: Straßen
  • 20: Gebäude

Die folgenden drei Bilder zeigen Tokio in den Zoomstufen 0, 7 und 18.

Informationen dazu, wie die Maps JavaScript API Kacheln auf Grundlage der aktuellen Zoomstufe lädt, finden Sie im Leitfaden zu Karten- und Kachelkoordinaten.

Map-Objekte

map = new google.maps.Map(document.getElementById("map"), {...});

Die JavaScript-Klasse, mit der Karten dargestellt werden, ist die Map-Klasse. Objekte dieser Klasse definieren eine einzelne Karte auf einer Seite. Sie können mehrere Instanzen dieser Klasse erstellen. Jedes Objekt definiert eine separate Karte auf der Seite. Mit dem JavaScript-Operator new wird eine neue Instanz dieser Klasse erstellt.

Wenn Sie eine neue Karteninstanz erstellen, geben Sie ein <div>-HTML-Element auf der Seite als Container für die Karte an. HTML-Knoten sind untergeordnete Objekte des JavaScript-document-Objekts. Ein Verweis auf dieses Element wird über die Methode document.getElementById() abgerufen.

Dieser Code definiert eine Variable (namens map) und weist sie einem neuen Map-Objekt zu. Die Funktion Map() wird als Konstruktor bezeichnet. Hier ist ihre Definition:

Konstruktor Beschreibung
Map(mapDiv:Node, opts?:MapOptions ) Erstellt eine neue Karte innerhalb des angegebenen HTML-Containers (in der Regel ein „div“-Element). Dazu werden alle (optionalen) Parameter verwendet, die übergeben werden.

Problembehebung

API-Schlüssel- und Abrechnungsfehler

Unter bestimmten Umständen werden dunkle Karten oder „negative“ Street View-Bilder ausgegeben, die mit dem Wasserzeichen „for development purposes only“ (nur für Entwicklungszwecke) versehen sind. Das weist in der Regel auf Probleme mit einem API-Schlüssel oder der Abrechnung hin. Damit Sie Google Maps Platform-Produkte nutzen können, muss die Abrechnung für Ihr Konto aktiviert sein. Außerdem müssen alle Anfragen einen gültigen API-Schlüssel enthalten. Der folgende Ablauf hilft bei der Fehlerbehebung:

Wenn der Code immer noch nicht funktioniert

Brendan Kenny und Mano Marks beschreiben in diesem Video einige häufige Fehler und zeigen Ihnen, wie Sie sie beheben können.

  • Suchen Sie nach Tippfehlern. Denken Sie daran, dass in JavaScript zwischen Groß- und Kleinschreibung unterschieden wird.
  • Sehen Sie sich die Grundlagen an. Einige der häufigsten Probleme treten bei der ersten Kartenerstellung auf. Beispiele:
    • Prüfen Sie, ob Sie in den Kartenoptionen die Eigenschaften zoom und center angegeben haben.
    • Vergewissern Sie sich, dass Sie ein „div“-Element deklariert haben, in dem die Karte auf dem Bildschirm angezeigt wird.
    • Kontrollieren Sie, dass für das „div“-Element für die Karte eine Höhe definiert ist. „div“-Elemente werden standardmäßig mit einer Höhe von 0 erstellt und sind daher nicht sichtbar.
    Sehen Sie sich die Beispielimplementierung an.
  • Verwenden Sie eine JavaScript-Fehlersuche, z. B. die, die in den Chrome-Entwicklertools verfügbar ist. Suchen Sie zuerst in der JavaScript-Konsole nach Fehlern.
  • Posten Sie Fragen auf Stack Overflow. Richtlinien für gute Fragen sind auf der Supportseite verfügbar.