Google Maps JavaScript API Version 3

Erste Schritte

  1. Zielgruppe
  2. API-Schlüssel abrufen
  3. Hallo, Welt
  4. Ihre Anwendung als HTML5 deklarieren
  5. Google Maps API laden
  6. Karten-DOM-Elemente
  7. Kartenoptionen
  8. Das Kartenobjekt
  9. Karte laden

Zielgruppe

Diese Dokumentation richtet sich an Personen, die mit den Konzepten der JavaScript-Programmierung und der objektorientierten Programmierung vertraut sind. Sie sollten außerdem aus Sicht des Nutzers mit Google Maps vertraut sein. Im Internet gibt es zahlreiche JavaScript-Anleitungen.

Diese konzeptuelle Dokumentation dient als schneller Einstieg in die Erstellung von Anwendungen mit dem Google Maps API. Wir veröffentlichen auch die Google Maps API-Referenz.

API-Schlüssel abrufen

Alle Google Maps API-Anwendungen* sollten das Google Maps API mithilfe eines API-Schlüssels laden. Die Verwendung eines API-Schlüssels ermöglicht Ihnen die Überwachung der Google Maps API-Nutzung Ihrer Anwendung und stellt sicher, dass Google Sie bei Bedarf im Zusammenhang mit Ihrer Anwendung kontaktieren kann. Wenn die Google Maps API-Nutzung Ihrer Anwendung die Nutzungsbegrenzungen überschreitet, muss das Google Maps API mithilfe eines API-Schlüssels geladen werden, um ein zusätzliches Kontingent zu erwerben.

* Entwickler mit dem Google Maps API für Unternehmen dürfen keinen Schlüssel in ihre Anfragen einfügen. Lesen Sie bitte Google Maps JavaScript API laden, um eine unternehmensspezifische Anleitung zu erhalten.

So erstellen Sie Ihren API-Schlüssel:

  1. Besuchen Sie die Google APIs-Konsole unter https://code.google.com/apis/console und melden Sie sich mit Ihrem Google-Konto an.
  2. Klicken Sie auf den Link Dienste im Menü auf der linken Seite.
  3. Aktivieren Sie den Dienst Google Maps API v3.
  4. Klicken Sie auf den Link API Access im linksseitigen Menü. Ihr API-Schlüssel ist auf der Seite API Access im Abschnitt Simple API Access verfügbar. Google Maps API-Anwendungen verwenden den Schlüssel für Browser-Apps.

Standardmäßig kann ein Schlüssel auf allen Websites verwendet werden. Wir empfehlen dringend, dass Sie die Verwendung Ihres Schlüssels auf von Ihnen verwaltete Domains einschränken, um die Nutzung auf nicht befugten Websites zu vermeiden. Sie können angeben, welche Domains Ihren API-Schlüssel verwenden dürfen. Klicken Sie dazu in der APIs-Konsole auf den Link Zulässige Verweis-URLs bearbeiten... für Ihren Schlüssel.

Hallo, Welt

Anhand eines einfachen Beispiels erhalten Sie am leichtesten einen Einstieg in das Google Maps API. Auf der folgenden Webseite ist eine Karte abgebildet, die auf Sydney in New South Wales, Australien, fokussiert ist:

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
    <style type="text/css">
      html { height: 100% }
      body { height: 100%; margin: 0; padding: 0 }
      #map_canvas { height: 100% }
    </style>
    <script type="text/javascript"
      src="http://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=SET_TO_TRUE_OR_FALSE">
    </script>
    <script type="text/javascript">
      function initialize() {
        var mapOptions = {
          center: new google.maps.LatLng(-34.397, 150.644),
          zoom: 8,
          mapTypeId: google.maps.MapTypeId.ROADMAP
        };
        var map = new google.maps.Map(document.getElementById("map_canvas"),
            mapOptions);
      }
    </script>
  </head>
  <body onload="initialize()">
    <div id="map_canvas" style="width:100%; height:100%"></div>
  </body>
</html>

Beispiel ansehen (map-simple.html)

Auch für dieses einfache Beispiel müssen einige Dinge beachtet werden:

  1. Wir deklarieren die Anwendung mithilfe der Deklaration <!DOCTYPE html> als HTML5.
  2. Wir binden das Google Maps JavaScript API mithilfe eines script-Tag ein.
  3. Wir erstellen ein div-Element namens "map_canvas", in das die Karte eingebettet wird.
  4. Wir erstellen ein JavaScript-Objektliteral, das eine Reihe von Karteneigenschaften aufnehmen kann.
  5. Wir schreiben eine JavaScript-Funktion, um ein Kartenobjekt zu erstellen.
  6. Wir initialisieren das Kartenobjekt über das Ereignis onloaddes Tags body.

Diese Schritte werden im Folgenden beschrieben.

Ihre Anwendung als HTML5 deklarieren

Sie sollten einen echten DOCTYPE in Ihrer Webanwendung deklarieren. In den Beispielen hier haben wir unsere Anwendungen mit dem einfachen HTML5-DOCTYPE wie unten dargestellt als HTML5 deklariert:

<!DOCTYPE html>

Die meisten aktuellen Browser rendern Inhalte, die mit diesem DOCTYPE deklariert wurden, im "Standardmodus", d. h. Ihre Anwendung ist stärker browserübergreifend kompatibel. Der DOCTYPE wurde so konzipiert, dass er einfach ausgeblendet wird. Browser, die diese Eigenschaft nicht verstehen, ignorieren sie und verwenden den "Quirks-Modus" zum Anzeigen des Inhalts.

Beachten Sie, dass CSS-Code, der im Quirks-Modus funktioniert, im Standardmodus nicht gültig ist. Im Speziellen müssen alle auf Prozentzahlen basierenden Größen von übergeordneten Blockelementen übernommen werden und wenn einer dieser Vorgänger keine Größe festlegt, wird angenommen, dass sie eine Größe von 0 x 0 Pixeln haben. Aus diesem Grund fügen wir die folgende <style>-Deklaration ein:

<style type="text/css">
  html { height: 100% }
  body { height: 100%; margin: 0; padding: 0 }
  #map_canvas { height: 100% }
</style>

Die CSS-Deklaration gibt an, dass der Karten-Container <div> (namens map_canvas) 100 % der Höhe des HMTL-Teils einnehmen soll. Beachten Sie, dass diese Prozentsätze für <body> und <html> auch ausdrücklich deklariert werden müssen.

Google Maps API laden

<html>
  <head>
    <script type="text/javascript"
      src="http://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=SET_TO_TRUE_OR_FALSE">
    </script>

Die URL in script zeigt auf den Speicherort einer JavaScript-Datei, die alle Symbole und Definitionen lädt, die Sie für die Verwendung des Google Maps APIs benötigen. Dieses script-Tag ist erforderlich.

Der Parameter key enthält den API-Schlüssel Ihrer Anwendung. Weitere Informationen finden Sie unter API-Schlüssel abrufen. Beachten Sie, dass dieser Schlüssel nicht derselbe Schlüssel ist, der mit dem API Version 2 verwendet wird, und dass er über die APIs-Konsole generiert werden muss.

Der Parameter sensor der URL muss enthalten sein und zeigt an, ob diese Anwendung einen Sensor, wie z. B. einen GPS-Peilsender verwendet, um den Standort des Nutzers zu bestimmen. Wie haben bei diesem Beispiel bewusst die Variable set_to_true_or_false beibehalten, um zu betonen, dass Sie diesen Wert auf true oder false setzen müssen.

Nutzer des Google Maps APIs für Unternehmen finden im Abschnitt Google Maps JavaScript API laden in der Unternehmensdokumentation wichtige Informationen zum Laden des Google Maps APIs in ihren Anwendungen.

HTTPS

Ist Ihre Anwendung eines HTTPS-Anwendung, können Sie stattdessen das Google Maps JavaScript API über HTTPS laden:

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=SET_TO_TRUE_OR_FALSE"
  type="text/javascript"></script>

Das Laden des Google Maps APIs über HTTPS ist in SSL-Anwendungen erforderlich, um Sicherheitswarnungen der meisten Browser zu vermeiden. Es ist außerdem für Anwendungen zu empfehlen, die in Anfragen vertrauliche Nutzerdaten enthalten, wie zum Beispiel den Standort eines Nutzers.

Bibliotheken

Beim Laden des Google Maps JavaScript APIs über die http://maps.googleapis.com/maps/api/js-URL können Sie mithilfe des Parameters libraries optional weitere Bibliotheken laden. Bibliotheken sind Codemodule, die zusätzliche Funktionen zum JavaScript API bieten, jedoch nicht geladen werden, wenn sie nicht ausdrücklich angefordert werden. Weitere Informationen finden Sie unter Bibliotheken im Google Maps API Version 3.

API asynchron laden

Möglicherweise möchten Sie den Google Maps API-JavaScript-Code laden, sobald das Laden Ihrer Seite beendet ist, oder bei Bedarf. Dazu können Sie Ihr eigenes <script>-Tag in Reaktion auf ein window.onload-Ereignis oder einen Funktionsaufruf injizieren, aber Sie müssen zusätzlich den Google Maps JavaScript API-Bootstrap anweisen, die Ausführung Ihres Anwendungscodes zu verschieben, bis der Google Maps JavaScript API-Code vollständig geladen ist. Dazu können Sie den Parameter callback verwenden, der als Argument die Funktion akzeptiert, die nach Abschluss des Ladevorgangs des APIs ausgeführt werden soll.

Der folgende Code weist die Anwendung an, das Google Maps API nach vollständigem Laden der Seite zu laden (mithilfe von window.onload) und das Google Maps JavaScript API in ein <script>-Tag innerhalb der Seite zu schreiben. Außerdem wird das API angewiesen, die Funktion initialize() nur auszuführen, wenn das API durch Übergeben von callback=initialize an den Google Maps API-Bootstrap vollständig geladen wurde:

function initialize() {
  var mapOptions = {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  var map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions);
}

function loadScript() {
  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "http://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=TRUE_OR_FALSE&callback=initialize";
  document.body.appendChild(script);
}

window.onload = loadScript;

Beispiel ansehen (map-simple-async.html)

DOM-Kartenelemente

<div id="map_canvas" style="width: 100%; height: 100%"></div>

Damit die Karte auf einer Webseite angezeigt werden kann, muss zunächst ein Platz für sie reserviert werden. Dazu erstellen wir gewöhnlich ein benanntes div-Element, auf das im DOM (Document Object Model) des Browsers verwiesen wird.

Im folgenden Beispiel definieren wir ein <div> mit der Bezeichnung "map_canvas" und legen dessen Größe anhand von Stilattributen fest. Diese Größe wird auf "100 %" festgelegt, sodass sie stets an die Größe von Mobilgeräten angepasst wird. Möglicherweise müssen Sie diese Werte für die Bildschirmgröße und das Padding des Browsers anpassen. Beachten Sie, dass diese Karte ihre Größe immer von dem Element übernimmt, in dem sie sich befindet. Sie müssen daher immer explizit eine Größe für das betreffende <div>-Element angeben.

Kartenoptionen

var mapOptions = {
  center: new google.maps.LatLng(-34.397, 150.644),
  zoom: 8,
  mapTypeId: google.maps.MapTypeId.ROADMAP
};

Zum Initialisieren einer Karte wird zuerst ein Map options-Objekt mit den Karteninitialisierungsvariablen erstellt. Dieses Objekt wird nicht aufgebaut, sondern als Objektliteral erstellt.

var mapOptions = {};

Geografische Breiten- und Längenangaben

Da wir die Karte mittels center an einem bestimmten Punkt zentrieren möchten, erstellen wir ein LatLng-Objekt, das diesen Standort enthält, indem wir die Koordinaten des Standorts in der Reihenfolge { Breitengrad, Längengrad } übergeben:

center = new google.maps.LatLng(-34.397, 150.644)

Das Umwandeln einer Adresse in eine geografische Position wird als Geocodierung bezeichnet. Diese Version des Google Maps APIs unterstützt die Geocodierung. Weitere Informationen finden Sie unter Geocodierung im Kapitel Dienste dieses Handbuchs.

Zoomstufen

Die Anfangsauflösung, in der eine Karte angezeigt werden soll, wird über die Eigenschaft zoom angegeben, wobei die Zoomstufe 0 einer vollständig herausgezoomten Karte der Erde entspricht und durch höhere Zoomstufen eine höhere Auflösung erzielt wird.

zoom: 8

Eine Karte der gesamten Erde als einziges Bild anzubieten würde entweder eine riesengroße Karte erfordern oder eine kleine Karte mit einer sehr niedrigen Auflösung. Daher werden Kartenbilder in Google Maps und dem Google Maps API in "Kartenkacheln" und "Zoomstufen" unterteilt. Bei niedrigen Zoomstufen deckt ein kleiner Satz Kartenkacheln ein großes Gebiet ab. Bei höheren Zoomstufen verfügen die Kacheln über eine höhere Auflösung und decken ein kleineres Gebiet ab.

Die folgenden drei Bilder zeigen denselben Standort in Tokio mit den Zoomstufen 0,7 und 18:

Informationen darüber, wie das Google Maps API Kacheln auf Grundlage der aktuellen Zoomstufe lädt, finden Sie in der Kachelkoordinaten-Dokumentation zu den Kartentypen.

Kartentypen

Sie müssen jetzt auch einen anfänglichen Kartentyp explizit angeben.

mapTypeId: google.maps.MapTypeId.ROADMAP

Die folgenden Kartentypen werden unterstützt:

  • ROADMAP zeigt die normalen Standard-2D-Kacheln von Google Maps an.
  • SATELLITE zeigt Fotokacheln an.
  • HYBRID zeigt eine Mischung aus Fotokacheln und eine Kachelebene für markante Merkmale an (Straßen, Ortsnamen).
  • TERRAIN zeigt Reliefkacheln für Erhebungen und Gewässer (Berge, Flüsse usw.) an.

Weitere Informationen über Kartentypen finden Sie im Abschnitt Kartentypen. In den meisten Fällen reicht es jedoch aus, wenn Sie über die Verwendung der grundlegenden Typen Bescheid wissen.

Das Kartenobjekt

var map = new google.maps.Map(document.getElementById("map_canvas"),
    mapOptions);

Die JavaScript-Klasse, die eine Karte darstellt, ist die Klasse Map. Objekte dieser Klasse definieren eine einzelne Karte auf einer Seite. Sie können mehrere Instanzen dieser Klasse erstellen. In diesem Fall definiert jedes Objekt eine separate Karte auf der Seite. Wir erstellen eine neue Instanz dieser Klasse mithilfe des JavaScript-Operators new.

Wenn Sie eine neue Karteninstanz erstellen, geben Sie ein <div>-HTML-Element in der Seite als Container für die Karte an. HTML-Knoten sind untergeordnete Objekte des JavaScript-Objekts document. Eine Referenz zu diesem Element wird über die Methode document.getElementById() hergestellt.

Dieser Code definiert eine Variable (namens map) und weist diese einem neuen Map-Objekt zu. Dabei werden auch die mit dem mapOptions-Objektliteral definierten Optionen übergeben. Diese Optionen dienen zum Initialisieren der Karteneigenschaften. Die Funktion Map() ist als Konstruktor mit folgender Definition bekannt:

Konstruktor Beschreibung
Map(mapDiv:Node, opts?:MapOptions) Erstellt eine neue Karte in einem vorhandenen HTML-Container, bei dem es sich üblicherweise um ein DIV-Element handelt, mithilfe (optionaler) übergebener Parameter.

Karte laden

  <body onload="initialize()">

Während eine HTML-Seite aufgebaut wird, wird das DOM (Document Object Model) umgesetzt, und alle externen Bilder und Skripts werden empfangen und in das document-Objekt aufgenommen. Damit sichergestellt wird, dass die Karte erst nach dem vollständigen Ladevorgang auf die Seite platziert wird, führen wir die Funktion, die das Map-Objekt erzeugt, erst aus, wenn das Element <body> der HTML-Seite ein onload-Ereignis empfängt. Auf diese Weise tritt kein unvorhersehbares Verhalten auf und wir haben mehr Kontrolle darüber, wie und zu welchem Zeitpunkt die Karte dargestellt wird.

Das Attribut onload des Tags body ist ein Beispiel für einen Ereignis-Handler. Das Google Maps JavaScript API bietet außerdem eine Reihe von Ereignissen, mit denen Sie Statusänderungen feststellen können. Weitere Informationen finden Sie unter Kartenereignisse.

Authentifizierung erforderlich

Dazu müssen Sie in Google+ angemeldet sein.

Anmeldung...

Google Developers braucht hierfür Ihre Erlaubnis.