Mithilfe von JavaScript eine Markierung auf Ihrer Google-Karte einfügen

Einführung

In dieser Anleitung erfahren Sie, wie Sie mithilfe von HTML, CSS und JavaScript eine Google-Karte mit einer Markierung auf einer Webseite einfügen. Außerdem erfahren Sie, wie Sie Kartenoptionen festlegen und wie Sie mithilfe von Steuerelement-Slots ein Label zur Karte hinzufügen.

Unten sehen Sie die Karte, die Sie mit dieser Anleitung erstellen. Die Markierung befindet sich am Uluru (auch als Ayers Rock bezeichnet) im Uluṟu-Kata-Tjuṯa-Nationalpark.

Überblick und Webbrowser

Um eine Google-Karte mit einer Markierung auf Ihrer Webseite einzufügen, sind drei Schritte erforderlich:

1. API-Schlüssel anfordern
2. HTML-Seite erstellen
3. Karte mit Markierung hinzufügen

Sie benötigen einen Webbrowser. Wählen Sie aus der Liste der unterstützten Browser einen gängigen Browser wie Google Chrome (empfohlen), Firefox, Safari oder Edge für Ihre Plattform aus.

Schritt 1: API-Schlüssel anfordern

In diesem Abschnitt wird erläutert, wie Sie Ihre Anwendung mit Ihrem eigenen API-Schlüssel bei der Maps JavaScript API authentifizieren können.

So fordern Sie einen API-Schlüssel an:

1. Rufen Sie die Google Cloud Console auf.

2. Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes Projekt aus.

3. Klicken Sie auf Weiter, um die API und die zugehörigen Dienste zu aktivieren.

4. Fordern Sie auf der Seite Anmeldedaten einen API-Schlüssel an und legen Sie die Einschränkungen für den API-Schlüssel fest. Wenn Sie bereits einen API-Schlüssel ohne Einschränkungen oder einen Schlüssel mit Browsereinschränkungen haben, können Sie auch diesen verwenden.

5. Informationen zum Verhindern von Kontingentdiebstahl und zum Sichern Ihres API-Schlüssels finden Sie unter Mit API-Schlüsseln authentifizieren.

6. Aktivieren Sie die Abrechnung. Weitere Informationen finden Sie unter Nutzung und Abrechnung.

7. Nachdem Sie einen API-Schlüssel erhalten haben, klicken Sie auf „YOUR_API_KEY“, um ihn in das folgende Snippet einzufügen. Kopieren Sie das Bootloader-Script-Tag, das Sie auf Ihrer eigenen Webseite verwenden möchten, und fügen Sie es ein.

   <script>
     (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
       key: "YOUR_API_KEY",
       v: "weekly",
       // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
       // Add other bootstrap parameters as needed, using camel case.
     });
   </script>

Schritt 2: HTML-Seite erstellen

Hier ist der Code für eine einfache HTML-Webseite:

<!DOCTYPE html>
<!--
 @license
 Copyright 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Dies ist eine sehr einfache HTML-Seite, auf der ein gmp-map-Element verwendet wird, um eine Karte auf der Seite anzuzeigen. Die Karte ist leer, da wir noch keinen JavaScript-Code hinzugefügt haben.

Code verstehen

In dieser Phase des Beispiels haben wir:

• Die Anwendung wird mithilfe der !DOCTYPE html-Deklaration als HTML5 deklariert.
• Die Maps JavaScript API wird mit dem Bootstrap-Ladeprogramm geladen.
• Ein gmp-map-Element für die Karte erstellen

Anwendung als HTML5 deklarieren

Wir empfehlen, dass Sie ein echtes DOCTYPE-Element innerhalb Ihrer Webanwendung deklarieren. In den Beispielen hier haben wir die Anwendungen über den 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>
  gmp-map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Maps JavaScript API laden

Das Bootstrap-Ladeprogramm bereitet die Maps JavaScript API für das Laden vor. Es werden keine Bibliotheken geladen, bis importLibrary() aufgerufen wird.

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Eine Anleitung zum Abrufen eines eigenen API-Schlüssels finden Sie unter Schritt 3: API-Schlüssel anfordern.

In dieser Phase der Anleitung wird ein leeres Fenster angezeigt, das nur den unformatierten Labeltext enthält. Das liegt daran, dass wir noch keinen JavaScript-Code hinzugefügt haben.

gmp-map-Element erstellen

Damit die Karte auf einer Webseite angezeigt werden kann, muss ein Platz für sie reserviert werden. Dazu wird normalerweise ein gmp-map-Element erstellt, auf das im DOM (Document Object Model) des Browsers verwiesen wird. Sie können dazu auch ein div-Element verwenden (weitere Informationen). Es wird jedoch empfohlen, das gmp-map-Element zu verwenden.

Im folgenden Code wird das Element gmp-map definiert und die Parameter center, zoom und map-id werden festgelegt.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

Die Optionen center und zoom sind immer erforderlich. Im Code oben wird über die Eigenschaft center der API mitgeteilt, wo sich der Mittelpunkt der Karte befinden soll. Mit der Eigenschaft zoom wird die Zoomstufe der Karte festgelegt. Die geringste Stufe ist „Zoom: 0“. Hier wird die gesamte Erde dargestellt. Um heranzuzoomen und die Erde in höherer Auflösung zu sehen, müssen Sie eine höhere Zoomstufe festlegen.

Zoomstufen

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 Maps JavaScript 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 oder Kontinent
• 10: Stadt
• 15: Straßen
• 20: Gebäude

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

Der folgende Code beschreibt die CSS-Attribute, über die die Größe des gmp-map-Elements festgelegt wird.

/* Set the size of the gmp-map element that contains the map */
gmp-map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

Im Code oben wird über das style-Element die Größe von gmp-map festgelegt. Die Breite und Höhe müssen auf mehr als 0 px festgelegt werden, damit die Karte sichtbar ist. In unserem Fall ist für das gmp-map-Element eine Höhe von 400 px und eine Breite von 100% festgelegt, damit die Karte über die gesamte Breite der Webseite angezeigt wird. Es wird empfohlen, die Stile für Höhe und Breite immer explizit festzulegen.

Hinweis:Bei Rasterkarten beträgt die Maximalgröße 6144 × 6144 Pixel.

Steuerelement-Platzierung

Mit der Slotting-Funktion können Sie Ihrer Karte HTML-Formularsteuerelemente hinzufügen. Ein Slot ist eine vordefinierte Position auf der Karte. Mit dem Attribut slot können Sie die gewünschte Position für ein Element festlegen und Elemente im Element gmp-map verschachteln. Im folgenden Snippet sehen Sie, wie ein HTML-Label oben links auf der Karte eingefügt wird.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

Schritt 3: JavaScript-Code hinzufügen

Hier erfahren Sie, wie Sie die Maps JavaScript API in eine Webseite laden und eigenen JavaScript-Code schreiben, um mithilfe der API eine Karte mit einer Markierung einzufügen.

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Hinweis: Lesen Sie sich hierzu den Leitfaden zur Verwendung von TypeScript und Google Maps durch.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

Der obige Code führt die folgenden Schritte aus, wenn initMap() aufgerufen wird:

• Lädt die Bibliotheken maps und marker.
• Ruft das Kartenelement aus dem DOM ab.
• Legt zusätzliche Kartenoptionen für die innere Karte fest.
• Fügt der Karte eine Markierung hinzu.

Kartenobjekt abrufen und Optionen festlegen

innerMap stellt eine Instanz der Map-Klasse dar. Wenn Sie Kartenoptionen festlegen möchten, rufen Sie die innerMap-Instanz aus dem Kartenelement ab und rufen Sie setOptions auf. Im folgenden Snippet wird die innerMap-Instanz aus dem DOM abgerufen und dann setOptions aufgerufen:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Warten Sie, bis die Karte geladen ist.

Wenn Sie das gmp-map-Element verwenden, wird die Karte asynchron geladen. Dies kann zu einer Race-Bedingung führen, wenn während der Initialisierung andere Anfragen gestellt werden (z. B. eine Anfrage zur Standortermittlung oder zu Place Details). Damit Ihr Code erst ausgeführt wird, wenn die Karte vollständig geladen ist, verwenden Sie in der Initialisierungsfunktion einen addListenerOnce-Event-Handler für den inaktiven Zustand:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

So wird sichergestellt, dass der Code erst ausgeführt wird, nachdem die Karte geladen wurde. Der Handler wird während des Lebenszyklus der App nur einmal ausgelöst.

Hinweis zur internen Leistungsoptimierung:

Um den Seitenaufbau zu verbessern, kann die Maps JavaScript API das Laden interaktiver Inhalte intern verzögern, bis sich das Element oder der Container dem Darstellungsbereich nähert. Diese internen Optimierungen können sich jederzeit ohne Vorankündigung ändern. Sie sind als Leistungsverbesserung konzipiert und sollten nicht als Mechanismus für die Abrechnungsverwaltung verwendet werden. Damit die Abrechnung erst erfolgt, wenn ein Element sichtbar ist, sollten Sie die Erstellung im Anwendungscode verschieben.

Vollständiges Codebeispiel

Hier ist der vollständige Beispielcode:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Hinweis: Lesen Sie sich hierzu den Leitfaden zur Verwendung von TypeScript und Google Maps durch.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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>Add a Map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <!-- The map, centered at Uluru, Australia. -->
        <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
            <div id="controls" slot="control-inline-start-block-start">
                <h3>My Google Maps Demo</h3>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Weitere Informationen zu Markierungen:

• Markierungen barrierefrei machen
• Markierungen mit grafischen Symbolen
• Markierungsanimationen

Tipps und Fehlerbehebung

• Weitere Informationen zum Abrufen von Breiten- und Längengraden oder Umwandeln von Adressen in geografische Koordinaten
• Optionen wie Stil und Eigenschaften lassen sich anpassen, um die Karte individuell zu gestalten. Weitere Informationen zum Anpassen von Karten finden Sie unter Cloudbasiertes Gestalten von Karteninhalten und Auf Karten zeichnen.
• Verwenden Sie die Entwicklertools in Ihrem Webbrowser, um Ihren Code zu testen und auszuführen, Fehlerberichte zu lesen und Probleme mit dem Code zu beheben.
• Mit den folgenden Tastenkombinationen können Sie die Konsole in Chrome aufrufen:
  Befehlstaste + Optionstaste + J (Mac) oder Strg + Umschalttaste + J (Windows).

• So rufen Sie die Breiten- und Längengrade für einen Ort in Google Maps ab:

  1. Öffnen Sie Google Maps in einem Browser.
  2. Rechtsklicken Sie auf die genaue Position auf der Karte, für die Sie Koordinaten benötigen.
  3. Wählen Sie im Menü die Breiten- und Längengrade aus.

• Mit dem Geocoding-Dienst können Sie eine Adresse in Breiten- und Längengrade umwandeln. Ausführliche Informationen zu den ersten Schritten mit dem Geocoding-Dienst finden Sie in den Entwicklerleitfäden.