Es kann losgehen!

Bevor Sie mit der Entwicklung beginnen, lesen Sie bitte unsere Entwicklerdokumentation.

Die Google Maps JavaScript API aktivieren

Zum Einstieg führen wir Sie durch die Google Developers Console, wo Sie vorab Folgendes tun müssen:

  1. Ein Projekt erstellen oder auswählen
  2. Die Google Maps JavaScript API und zugehörige Dienste aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Upgrade einer Google Maps JavaScript API-Anwendung von v2 auf v3

Version 2 der Google Maps JavaScript API ist nicht mehr verfügbar. Dieser Leitfaden soll Entwickler, die die Google Maps JavaScript API v2 bereits verwenden, bei der Migration ihres Codes zu Version 3 unterstützen.

Im Vergleich zu v2 enthält v3 der Google Maps JavaScript API zahlreiche Änderungen. Wenn Sie mit der neuen API arbeiten, werden Sie schnell feststellen, dass es sich nicht nur um ein inkrementelles Upgrade handelt. Die gute Nachricht ist, dass viele großartige neue Funktionen hinzugefügt wurden und die Nutzererfahrung der API aus der Entwicklerperspektive insgesamt verbessert wurde. Wenn Sie ein Upgrade von der Google Maps JavaScript API v2 auf die Google Maps JavaScript API v3 planen, unterstützt dieser Leitfaden Sie in diesem Prozess. Darüber hinaus werden einige wesentliche Änderungen für Nutzer der API v2 hervorgehoben.

Übersicht

Je nach Anwendung variieren die Migrationsprozesse etwas. Einige Schritte sind jedoch in allen Projekten gleich.

  1. Fordern Sie einen neuen Schlüssel an. Die Google Maps JavaScript API verwaltet Schlüssel jetzt mit der Google API Console. Vor Beginn der Migration müssen Sie daher Ihren neuen API-Schlüssel anfordern.
  2. Aktualisieren Sie Ihr API-Bootstrap. Für die meisten Anwendungen wird Google Maps JavaScript API v3 mit dem folgenden Code geladen:
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
    
  3. Aktualisieren Sie den Code. Der Umfang der erforderlichen Änderungen hängt von Ihrer Anwendung ab. Zu den häufigen Änderungen gehören:
    • Verweisen Sie immer auf den Namespace „google.maps“. In v3 wird der gesamte Google Maps JavaScript API-Code nicht im globalen Namespace, sondern im Namespace google.maps.* gespeichert. Zudem wurden die meisten Objekte im Rahmen dieses Prozesses umbenannt. Beispiel: Statt GMap2 laden Sie jetzt google.maps.Map.
    • Entfernen Sie alle Verweise auf veraltete Methoden. Eine Reihe allgemeiner Hilfsprogrammmethoden wie GDownloadURL und GLog wurden entfernt. Ersetzen Sie diese Funktionalität entweder durch Hilfsprogrammbibliotheken von Drittanbietern oder entfernen Sie diese Verweise aus dem Code.
    • (Optional) Fügen Sie dem Code Bibliotheken hinzu. Viele Funktionen wurden in Hilfsprogrammbibliotheken ausgelagert, sodass für jede App nur die erforderlichen Teile der API geladen werden müssen.
    • (Optional) Konfigurieren Sie das Projekt zur Verwendung von Externs der v3. Mit den Externs der v3 können Sie den Code mit dem Closure Compiler validieren oder in Ihrer IDE die automatische Vervollständigung auslösen. Lesen Sie weitere Informationen über die erweiterte Kompilierung und über Externs.
  4. Führen Sie Tests und Iterationen durch. An diesem Punkt haben Sie noch einiges an Arbeit vor sich, sind jedoch auf dem besten Weg zu Ihrer neuen Maps-Anwendung der Version 3.

Änderungen in Version 3 der Google Maps JavaScript API

Bevor Sie die Migration planen, sollten Sie sich mit den Unterschieden zwischen Google Maps JavaScript API v2 und Google Maps JavaScript API v3 vertraut machen. Die neueste Version der Google Maps JavaScript API wurde von Grund auf neu geschrieben. Schwerpunkte waren dabei moderne JavaScript-Programmiertechniken, eine intensivere Nutzung von Bibliotheken und eine vereinfachten API. Der API wurde zahlreiche neue Funktionen hinzugefügt. Viele vertraute Funktionen wurden geändert oder sogar entfernt. In diesem Abschnitt werden einige der Hauptunterschiede zwischen den beiden Releases erläutert.

Die API v3 umfasst folgende Änderungen:

  • Eine optimierte Kernbibliothek. Ein Großteil der ergänzenden Funktionen wurden in Bibliotheken verschoben, wodurch die Lade- und Parsingzeiten für die Kern-API verkürzt wurden. Daher werden Karten jetzt auf jedem Gerät schnell geladen.
  • Verbesserte Leistung verschiedener Funktionen, beispielsweise der Polygonwiedergabe und der Markerpositionierung.
  • Ein neuer Ansatz bei den clientseitigen Nutzungsbeschränkungen, um die gemeinsame Nutzung von Adressen zu ermöglichen, die von mobilen Proxys und Unternehmensfirewalls verwendet werden.
  • Unterstützung verschiedener moderner Browser und mobiler Browser. Internet Explorer 6 wird nicht mehr unterstützt.
  • Viele allgemeine Hilfsklassen (GLog oder GDownloadUrl) wurden entfernt. Mittlerweile gibt es zahlreiche hervorragende JavaScript-Bibliotheken, die ähnliche Funktionen bereitstellen, z. B. Closure oder jQuery.
  • Eine HTML5-Implementierung von Street View, die auf allen Mobilgeräten geladen werden kann.
  • Benutzerdefinierte Street View-Panoramen mit eigenen Fotos. Teilen Sie Panoramen von Skihängen, zum Verkauf stehenden Häusern oder anderen interessanten Orten.
  • Anpassungen von formatierten Karten, mit denen Sie die Anzeige von Elementen auf der Basiskarte an Ihren individuellen visuellen Stil anpassen können.
  • Unterstützung für verschiedene neue Dienste, z. B. ElevationService und Distance Matrix.
  • Ein verbesserter Dienst für Wegbeschreibungen bietet alternative Routen, Routenoptimierung (Näherungslösungen für das Problem des Handlungsreisenden), Wegbeschreibungen für Fahrradfahrer (mit Bicycling-Ebene) und mit öffentlichen Verkehrsmitteln sowie ziehbare Wegbeschreibungen.
  • Ein aktualisiertes Geocoding-Format, das genauere Typeninformationen liefert als der Wert accuracy der Google Maps Geocoding API v2.
  • In einer einzelnen Karte werden mehrere Info-Fenster unterstützt.

Upgrade der Anwendung

Ihr neuer Schlüssel

In der Google Maps JavaScript API v3 wird ein neues Schlüsselsystem verwendet. Das bedeutet, dass Ihr v2-Schlüssel nicht mit Ihrer v3-Anwendung funktioniert. Wenn Sie vor der Bereitstellung der Anwendung in der Produktionsumgebung einen v3-Schlüssel hinzufügen, haben Sie folgende Möglichkeiten:

Der Schlüssel wird übergeben, wenn Sie die Google Maps JavaScript API v3 laden. So generieren Sie einen Schlüssel:

  1. Navigieren Sie zu Google API Console und melden Sie sich mit Ihrem Google-Konto an.
  2. Klicken Sie im linken Menü auf die Option Services und aktivieren Sie den Dienst Google Maps JavaScript API v3.
  3. Sobald der Dienst aktiviert wurde, finden Sie Ihren API-Schlüssel auf der Seite API Access im Bereich Simple API Access. Maps API-Anwendungen verwenden den Schlüssel für Browser-Apps.

Client-IDs für Maps APIs for Work-Lizenzen

Wenn Sie über eine Google Maps APIs for Work-Lizenz verfügen, benötigen Sie anstelle eines Schlüssels eine Client-ID. Beachten Sie, dass die beiden nicht zusammen verwendet werden können. Client-IDs ähneln den Schlüsseln zwar, unterscheiden sich jedoch in folgenden Punkten:

  • Google Maps APIs-Anwendungen, die eine Client-ID verwenden, haben möglicherweise Zugriff auf zusätzliche Funktionen, z. B. Maps Analytics, oder unterliegen zusätzlichen Beschränkungen.
  • Ihre Client-ID wird vom Google Cloud Support erstellt und Ihnen im Begrüßungsschreiben zu Maps APIs for Work mitgeteilt. Zur Erstellung oder Suche nach Ihrer Client-ID verwenden Sie nicht die Google API Console.
  • Wenn Sie die Google Maps JavaScript API laden, verwenden Sie anstelle des Parameters key den Parameter client. Beispiel:
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>
  • Client-IDs weisen immer das Präfix gme- auf.

Laden der API

Bei der ersten Änderung, die Sie am Code vornehmen müssen, geht es darum, wie die API geladen wird. In v2 laden Sie die Google Maps JavaScript API durch eine Anforderung an http://maps.google.com/maps. Wenn Sie die Google Maps JavaScript API v3 laden, müssen Sie folgende Änderungen vornehmen:

  1. Laden Sie die API über //maps.googleapis.com/maps/api/js
  2. Entfernen Sie den Parameter file.
  3. Fügen Sie stattdessen den erforderlichen Parameter sensor ein.
  4. Aktualisieren Sie den Parameter key mit Ihrem neuen v3-Schlüssel. Google Maps APIs for Work-Kunden müssen den Parameter client verwenden.
  5. (Nur Google Maps APIs Premium Plan) Stellen Sie sicher, dass der Parameter client so bereitgestellt wird, wie es im Entwickler-Leitfaden für den Google Maps APIs Premium Plan beschrieben ist.
  6. Entfernen Sie den Parameter v, um die neueste veröffentlichte Version anzufordern oder den Wert gemäß dem Schema der v3-Versionsverwaltung zu ändern.
  7. (Optional) Ersetzen Sie den Parameter hl durch language und behalten Sie seinen Wert bei.
  8. (Optional) Fügen Sie den Parameter libraries hinzu, um optionale Bibliotheken zu laden.

Im einfachsten Fall gibt das v3-Bootstrap nur Ihren API-Schlüssel und den Parameter „sensor“ an:

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

Im folgenden Beispiel wird die neueste (experimentelle) Version der Maps JavaScript API v2 in Deutsch angefordert:

<script type="text/javascript" src="//maps.google.com/maps?file=api&v=2.x&sensor=false&key=YOUR_API_KEY&hl=de"></script>

Das folgende Beispiel ist eine entsprechende Anforderung für v3.

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=YOUR_API_KEY&language=de"></script>

Versionsverwaltung

In v3 muss keine spezifische Version geladen werden. Wenn Sie den Versionsparameter auslassen, erhalten Sie die Experimental-Version der API. Sie können auch eine bestimmte Versionsnummer, die neueste (Experimental-)Version oder die stabilste Frozen-Version angeben.

In der folgenden Tabelle wird das Schema der v2-Version der v3-Version zugeordnet.

v2 v3 Anwendungsfall
2.s 3.0 Frozen-Version. Älteste verfügbare Version.
2 3 Release-Version. Neueste stabile Version.
2.x 3.exp Experimental-Version.

Wichtig: Das Google Maps APIs Premium Plan-SLA gilt nicht für die Experimental-Version. Google Maps APIs Premium Plan-Anwendungen müssen die Release- oder Frozen-Version verwenden, damit sie vom SLA abgedeckt sind.

Einführung des Namespace „google.maps“

Die auffälligste Änderung in der Google Maps JavaScript API v3 ist vermutlich die Einführung des Namespace google.maps. Die API v2 platziert alle Objekte standardmäßig im globalen Namespace, was zu Namenskonflikten führen kann. In v3 befinden sich alle Objekte im Namespace google.maps.

Wenn Sie Ihre Anwendung zu v3 migrieren, müssen Sie den Code für die Verwendung des neuen Namespace ändern. Leider ist die Methode, nach „G“ zu suchen und durch „google.maps.“ zu ersetzen, keine erschöpfende Methode, aber es ist eine praktische Faustregel zur Durchsicht des Codes. Nachfolgend erhalten Sie einige Beispiele für äquivalente Klassen in v2 und v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
oder google.maps.PolylineOptions

Entfernen von veraltetem Google-Code

Die Google Maps JavaScript API v3 besitzt Äquivalente für die meisten Funktionen aus v2. Einige Klassen werden jedoch nicht mehr unterstützt. Im Rahmen der Migration müssen Sie diese Klassen entweder durch Hilfsprogrammbibliotheken von Drittanbietern ersetzen oder diese Verweise aus dem Code entfernen. Es gibt zahlreiche hervorragende JavaScript-Bibliotheken, die ähnliche Funktionen bereitstellen, z. B. Closure oder jQuery.

Die folgenden Klassen haben kein Äquivalent in der Google Maps JavaScript API v3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Code im Vergleich

Nachfolgend werden zwei eher einfache Anwendungen verglichen, die mit der API v2 und der API v3 erstellt wurden.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY&sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

Zwischen den beiden Anwendungen gibt es einige offenkundige Unterschiede. Wichtige Änderungen sind:

  • Die Adresse, über die die API geladen wird, wurde geändert.
  • Die Methoden GBrowserIsCompatible() und GUnload() sind in v3 nicht mehr erforderlich und wurden aus der API entfernt.
  • Das Objekt GMap2 wurde durch google.maps.Map als zentrales Objekt in der API ersetzt.
  • Eigenschaften werden jetzt über die Optionenklassen geladen. Im obigen Beispiel werden die drei Eigenschaften center, zoom und mapTypeId, die zum Laden einer Karte erforderlich sind, über das Inline-Objekt MapOptions festgelegt.
  • Die Standardbenutzeroberfläche ist in v3 aktiviert. Sie können sie deaktivieren, indem Sie die Eigenschaft disableDefaultUI im Objekt MapOptions auf „true“ setzen.

Zusammenfassung

Bisher haben Sie einige wichtige Aspekte der Migration der Google Maps JavaScript API v2 auf die Google Maps JavaScript API v3 kennengelernt. Möglicherweise benötigen Sie noch wesentlich mehr Informationen. Das hängt jedoch von Ihrer Anwendung ab. In den folgenden Abschnitten erhalten Sie Anleitungen zur Migration für bestimmte Fälle, die möglicherweise auf Sie zutreffen. Zudem werden mehrere Ressourcen genannt, die während des Upgradeprozesses hilfreich sein können.

  • Die beste Informationsquelle für die API und ihre Funktionsweise ist die Entwicklerdokumentation zur Google Maps JavaScript API v3.
  • In der Referenz zur API v3 erfahren Sie mehr zu neuen Klassen und Methoden in der API v3.
  • Die Community „Stack Overflow“ ist der ideale Ort für Fragen in Bezug auf den Code. Auf der Website werden für Fragen und Antworten zur Google Maps JavaScript API die Tags „google-maps“ und „google-maps-api-3“ verwendet.
  • Google Maps APIs Premium Plan-Kunden wird die Lektüre der Dokumentation zum Google Maps APIs Premium Plan empfohlen.
  • Auf unserer Google Plus-Seite und im Google Geo Developers Blog können Sie sich über die neuesten Änderungen an der API informieren.

Bei Problemen oder Fragen zu diesem Artikel haben Sie die Möglichkeit, sich über den Link Feedback geben oben auf dieser Seite mit uns in Verbindung zu setzen.

Ausführliche Referenz

In diesem Abschnitt werden die bekanntesten Funktionen von Version 2 und Version 3 der Google Maps JavaScript API ausführlich verglichen. Jeder Abschnitt in dieser Referenz ist eine abgeschlossene Einheit. Sie brauchen nicht die gesamte Referenz lesen. Ziehen Sie das Material stattdessen bei Ihrer Migration für die jeweiligen Einzelfälle zurate.

  • Ereignisse – Ereignisse registrieren und bearbeiten.
  • Steuerelemente – Auf der Karte angezeigte Navigationssteuerelemente bearbeiten.
  • Überlagerungen – Objekte auf der Karte hinzufügen und bearbeiten.
  • Kartentypen – die Kacheln, aus denen die Basiskarte besteht.
  • Ebenen – Inhalte als Gruppe hinzufügen und bearbeiten, z. B. KML- oder Traffic-Ebenen.
  • Dienste – Mit den Geocoding-, Directions- oder Street View-Diensten von Google arbeiten.

Ereignisse

Das Ereignismodell für die Google Maps JavaScript API v3 ähnelt vordergründig dem in v2 verwendeten Modell, tatsächlich wurde jedoch einiges geändert.

Steuerelemente

Die Google Maps JavaScript API zeigt die UI-Steuerelemente an, über die Nutzer mit Ihrer Karte interagieren können. Mithilfe der API können Sie das Erscheinungsbild dieser Steuerelemente anpassen.

Überlagerungen

Überlagerungen stellen Objekte dar, die Sie der Karte „hinzufügen“, um Punkte, Linien, Bereiche oder Objektauflistungen festzulegen.

Kartentypen

Die in v2 und v3 verfügbaren Kartentypen weichen geringfügig voneinander ab, aber beide API-Versionen enthalten alle Basiskartentypen. Standardmäßig werden in v2 Straßenkartenkacheln mit der vertrauten Farbgebung verwendet. In v3 muss für die Erstellung des Objekts google.maps.Map hingegen ein spezieller Kartentyp angegeben werden.

Ebenen

Bei Ebenen handelt es sich um Objekte auf der Karte, die aus mindestens einer Überlagerung bestehen. Sie können als einzelne Einheit bearbeitet werden und stellen im Allgemeinen eine Gruppe von Objekten dar.

Dienste

Feedback geben zu...

Google Maps JavaScript API
Google Maps JavaScript API