Jetzt starten

Einführung

Die Static Maps API gibt ein Bild (GIF, PNG oder JPEG) als Antwort auf eine HTTP-Anfrage über eine URL zurück. Für jede Anfrage können Sie den Standort der Karte, die Größe des Bilds, die Zoomstufe, den Kartentyp und die Platzierung optionaler Markierungen an Orten auf der Karte angeben. Außerdem können Sie die Markierungen mit alphanumerischen Zeichen kennzeichnen.

Ein Maps Static API-Bild wird in das src-Attribut eines <img>-Tags oder das entsprechende Attribut in anderen Programmiersprachen eingebettet.

In diesem Dokument werden das erforderliche Format von Maps Static API-URLs und die verfügbaren Parameter beschrieben. Außerdem finden Sie dort einige Tipps und Tricks zur Angabe Ihrer URLs.

Hinweis

Dieses Dokument richtet sich an Website- und App-Entwickler, die Maps Static API-Bilder in eine Webseite oder mobile App einbinden möchten. Sie enthält eine Einführung in die Verwendung der API und Referenzmaterial zu den verfügbaren Parametern.

Bevor Sie mit der Entwicklung mit der Maps Static API beginnen, lesen Sie die Anforderungen an die Authentifizierung (Sie benötigen einen API-Schlüssel) und die Informationen zur API-Nutzung und -Abrechnung (Sie müssen die Abrechnung für Ihr Projekt aktivieren).

URL-Parameter

Eine Maps Static API-URL muss folgendermaßen formatiert sein:

https://maps.googleapis.com/maps/api/staticmap?parameters

Wenn auf Ihre Website über HTTPS zugegriffen wird, müssen Sie auch Maps Static API-Bilder über HTTPS laden, um Browsersicherheitswarnungen zu vermeiden. HTTPS wird auch empfohlen, wenn Ihre Anfragen sensible Nutzerdaten enthalten, z. B. den Standort eines Nutzers:

https://maps.googleapis.com/maps/api/staticmap?parameters

Unabhängig davon, ob Sie HTTP oder HTTPS verwenden, sind bestimmte URL-Parameter erforderlich, während andere optional sind. Wie bei URLs üblich, werden alle Parameter durch ein Et-Zeichen (&) getrennt. Die Liste der Parameter und ihre möglichen Werte sind in diesem Dokument aufgeführt.

In der Maps Static API werden Kartenbilder mit den folgenden URL-Parametern definiert:

Standortparameter

  • center (erforderlich, wenn keine Markierungen vorhanden sind) definiert den Mittelpunkt der Karte, der von allen Rändern der Karte gleich weit entfernt ist. Dieser Parameter nimmt einen Standort als kommagetrenntes Paar {latitude,longitude} (z.B. „40.714728,-73.998672“) oder eine Stringadresse (z.B. „Rathaus, New York, NY“) an, die einen eindeutigen Ort auf der Erde identifiziert. Weitere Informationen finden Sie unter Standorte.
  • zoom (erforderlich, wenn keine Markierungen vorhanden sind) definiert die Zoomstufe der Karte, die die Vergrößerung der Karte bestimmt. Dieser Parameter verwendet einen numerischen Wert, der der Zoomstufe der gewünschten Region entspricht. Weitere Informationen finden Sie unter Zoomstufen.

Kartenparameter

  • size (erforderlich) definiert die rechteckigen Abmessungen des Kartenbilds. Dieser Parameter wird als String im Format {horizontal_value}x{vertical_value} angegeben. Mit 500x400 wird beispielsweise eine Karte mit einer Breite von 500 Pixeln und einer Höhe von 400 Pixeln definiert. Bei Karten mit einer Breite von weniger als 180 Pixeln wird ein verkleinertes Google-Logo angezeigt. Dieser Parameter wird vom Parameter scale beeinflusst. Die endgültige Ausgabegröße ist das Produkt aus den Werten für Größe und Skalierung.
  • scale (optional) wirkt sich auf die Anzahl der zurückgegebenen Pixel aus. scale=2 gibt doppelt so viele Pixel wie scale=1 zurück, wobei derselbe Abdeckungsbereich und das gleiche Detaillierungsniveau beibehalten werden (d.h. der Inhalt der Karte ändert sich nicht). Dies ist bei der Entwicklung für hochauflösende Displays nützlich. Der Standardwert ist 1. Zulässige Werte sind 1 und 2. Weitere Informationen finden Sie unter Maßstabswerte.
  • format (optional) definiert das Format des resultierenden Bilds. Die Maps Static API erstellt standardmäßig PNG-Bilder. Es gibt mehrere mögliche Formate, darunter GIF, JPEG und PNG. Welches Format Sie verwenden, hängt davon ab, wie Sie das Bild präsentieren möchten. JPEG bietet in der Regel eine bessere Komprimierung, während GIF und PNG mehr Details liefern. Weitere Informationen finden Sie unter Bildformate.
  • maptype (optional) definiert den Typ der Karte, die erstellt werden soll. Es gibt mehrere mögliche Werte für „maptype“, darunter roadmap, satellite, hybrid und terrain. Weitere Informationen finden Sie unter Maps Static API-Kartentypen.
  • language (optional) definiert die Sprache, die für die Anzeige von Labels auf Kartenkacheln verwendet werden soll. Dieser Parameter wird nur für einige Länderkacheln unterstützt. Wenn die gewünschte Sprache für den Kachelsatz nicht unterstützt wird, wird die Standardsprache für diesen Kachelsatz verwendet.
  • region (optional) definiert die entsprechenden Grenzen, die basierend auf geopolitischen Sensibilisierungen angezeigt werden sollen. Akzeptiert einen Regionscode als zweistelliger ccTLD-Wert („Top-Level-Domain“). Welche Regionen unterstützt werden, sehen Sie in den Details zur Google Maps Platform-Abdeckung.

Funktionsparameter

  • map_id (optional) gibt die Kennung für eine bestimmte Karte an. Die Karten-ID verknüpft eine Karte mit einem bestimmten Stil oder einer bestimmten Funktion und muss zum selben Projekt gehören wie der API-Schlüssel, mit dem die Karte initialisiert wurde. Weitere Informationen finden Sie unter Karten-IDs verwenden.
  • markers (optional): Hiermit werden eine oder mehrere Markierungen definiert, die an den angegebenen Stellen am Bild angebracht werden sollen. Dieser Parameter nimmt eine einzelne Markierungsdefinition mit Parametern an, die durch das Pipe-Zeichen (|) getrennt sind. Mehrere Markierungen können innerhalb desselben markers-Parameters platziert werden, sofern sie denselben Stil haben. Sie können zusätzliche Markierungen mit unterschiedlichen Stilen hinzufügen, indem Sie zusätzliche markers-Parameter hinzufügen. Wenn Sie Markierungen für eine Karte angeben, müssen Sie die normalerweise erforderlichen Parameter center und zoom nicht angeben. Weitere Informationen finden Sie unter Markierungen in der Maps Static API.
  • path (optional) definiert einen einzelnen Pfad aus zwei oder mehr verbundenen Punkten, der an den angegebenen Stellen auf das Bild gelegt wird. Dieser Parameter besteht aus einem String von Punktdefinitionen, die durch ein Pipe-Zeichen (|) voneinander getrennt sind, oder eine codierte Polylinie mit dem Präfix enc: in der Standortdeklaration des Pfads. Sie können zusätzliche Pfade angeben, indem Sie zusätzliche path-Parameter hinzufügen. Wenn Sie einen Pfad für eine Karte angeben, müssen Sie die normalerweise erforderlichen Parameter center und zoom nicht angeben. Weitere Informationen finden Sie unter Pfade in der Maps Static API.
  • visible (optional) gibt einen oder mehrere Standorte an, die auf der Karte sichtbar bleiben sollen, ohne dass Markierungen oder andere Indikatoren angezeigt werden. Mit diesem Parameter können Sie dafür sorgen, dass bestimmte Elemente oder Kartenstandorte in der Maps Static API angezeigt werden.
  • style (optional) definiert einen benutzerdefinierten Stil, um die Darstellung eines bestimmten Elements (Straßen, Parks und anderer Elemente) der Karte zu ändern. Dieser Parameter verwendet die Argumente feature und element, um die zu gestaltenden Elemente sowie eine Reihe von Stilvorgängen festzulegen, die auf die ausgewählten Elemente angewendet werden sollen. Sie können mehrere Stile angeben, indem Sie zusätzliche style-Parameter hinzufügen. Weitere Informationen finden Sie im Leitfaden zu stilisierten Karten.

Schlüssel- und Signaturparameter

  • Mit key (erforderlich) können Sie die API-Nutzung Ihrer Anwendung in der Google Cloud Console im Blick behalten und dafür sorgen, dass Google Sie bei Bedarf bezüglich Ihrer Anwendung kontaktieren kann. Weitere Informationen finden Sie unter API-Schlüssel mit der Maps Static API verwenden.
  • signature (empfohlen) ist eine digitale Signatur, mit der geprüft wird, ob Anfragen zur Websitegenerierung, bei denen dein API-Schlüssel verwendet wird, entsprechend autorisiert sind. Anfragen ohne digitale Signatur können fehlschlagen. Weitere Informationen finden Sie unter Digitale Signatur verwenden.

Beschränkung der URL-Größe

URLs für die Maps Static API sind auf 16.384 Zeichen beschränkt. In der Praxis benötigen Sie wahrscheinlich keine längeren URLs, es sei denn, Sie erstellen komplexe Karten mit einer großen Anzahl von Markierungen und Pfaden.

Verwendung der Parameter

Die Maps Static API ist relativ einfach zu verwenden, da sie ausschließlich aus einer parametrisierten URL besteht. In diesem Abschnitt wird erläutert, wie Sie diese Parameter zum Erstellen Ihrer URLs verwenden.

Positionen angeben

Die Maps Static API muss Orte auf der Karte genau identifizieren können, um die Karte sowohl auf die richtige Position (mit dem Parameter center) zu fokussieren und/oder optionale Markierungen (mit dem Parameter markers) an Orten auf der Karte zu platzieren. In der Maps Static API werden Zahlen (Breiten- und Längengradwerte) oder Strings (Adressen) verwendet, um diese Orte anzugeben. Diese Werte identifizieren einen geocodierten Standort.

Für einige Parameter (z. B. markers und path) können mehrere Standorte angegeben werden. In diesen Fällen werden die Standorte durch einen senkrechten Strich (|) getrennt.

Breiten- und Längengrade

Breiten- und Längengrade werden mit Ziffern in einem kommagetrennten Textstring mit einer Genauigkeit von sechs Dezimalstellen definiert. „40.714728,-73.998672“ ist beispielsweise ein gültiger Geocodewert. Genauigkeiten über sechs Dezimalstellen werden ignoriert.

Die Werte für den Längengrad basieren auf der Entfernung von Greenwich, England, durch den Nullmeridian. Da sich Greenwich auf dem Breitengrad 51,477222 befindet, können wir einen center-Wert von 51.477222,0 eingeben, um die Karte auf Greenwich zu zentrieren:

Greenwich, England

Die Werte für Breiten- und Längengrad müssen einem gültigen Ort auf der Erdoberfläche entsprechen. Breitengrade können jeden Wert zwischen -90 und 90 haben, während Längengrade jeden Wert zwischen -180 und 180 haben können. Wenn Sie einen ungültigen Breiten- oder Längengrad angeben, wird Ihre Anfrage als fehlerhafte Anfrage abgelehnt.

Adressen

Die meisten Menschen sprechen nicht in Breiten- und Längengraden, sondern geben Orte mithilfe von addresses an. Die Umwandlung einer Adresse in einen geografischen Punkt wird als Geocodierung bezeichnet. Der Maps Static API-Dienst kann die Geocodierung für Sie ausführen, wenn Sie gültige Adressen angeben.

In allen Parametern, in denen Sie einen Breiten-/Längengrad angeben können, können Sie stattdessen einen String angeben, der eine Adresse angibt. Google geocodiert die Adresse und stellt dem Maps Static API-Dienst einen Breiten-/Längengradwert zur Verfügung, der zum Setzen von Markierungen oder Angeben von Standorten verwendet werden kann. Der String muss URL-codiert sein. Adressen wie „Rathaus, Berlin, Deutschland“ müssen beispielsweise in „Rathaus,Berlin,Deutschland“ umgewandelt werden.

Adressen können entweder genaue Standorte wie Straßenadressen, Polylinien wie benannte Routen oder polygonale Gebiete wie Städte, Länder oder Nationalparks sein. Bei polylinearen und polygonalen Ergebnissen verwendet der Maps Static API-Server den Mittelpunkt der Linie/des Gebiets als Adressenmittelpunkt. Falls Sie sich nicht sicher sind, wie eine Adresse geocodiert werden kann, können Sie sie mit diesem Geocoding-Dienstprogramm testen.

Im folgenden Beispiel wird ein statisches Kartenbild für Berkeley, Kalifornien, generiert:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Berkeley, CA

Zoomstufen

Karten in Google Maps haben eine Ganzzahl als „Zoomstufe“, die die Auflösung der aktuellen Ansicht definiert. In der Standardansicht roadmap sind Zoomstufen zwischen 0 (die niedrigste Zoomstufe, bei der die gesamte Welt auf einer Karte zu sehen ist) und 21+ (bis hinunter zu Straßen und einzelnen Gebäuden) möglich. Gebäudeumrisse werden auf der Karte ab Zoomstufe 17 angezeigt, sofern verfügbar. Dieser Wert variiert je nach Region und kann sich im Laufe der Zeit ändern, wenn die Daten aktualisiert werden.

Von Google Maps wird die Zoomstufe 0 festgelegt, sodass die gesamte Erde in der Ansicht umfasst ist. Mit jeder höheren Zoomstufe wird die Genauigkeit sowohl in horizontaler als auch in vertikaler Richtung verdoppelt. Weitere Informationen dazu finden Sie in der Dokumentation zur Google Maps JavaScript API.

Hinweis: Nicht alle Zoomstufen sind für alle Standorte der Erde verfügbar. Die Zoomebenen variieren je nach Standort, da die Daten in einigen Teilen der Welt detaillierter sind als in anderen.

Wenn Sie eine Anfrage für einen Zoomfaktor senden, für den keine Kartenkacheln vorhanden sind, gibt die Maps Static API stattdessen ein leeres Bild zurück.

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

In diesem Beispiel werden zwei Karten von Manhattan mit demselben center-Wert, aber mit den Zoomstufen 12 und 14 angefordert:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Manhattan (Ferndarstellung)  Manhattan (Nahdarstellung)

Bildgrößen

Der Parameter size definiert in Verbindung mit center den Abdeckungsbereich einer Karte. Außerdem wird damit die Ausgabegröße der Karte in Pixeln definiert, wenn sie mit dem Wert scale multipliziert wird (standardmäßig 1).

In dieser Tabelle sind die maximal zulässigen Werte für den Parameter size für jeden scale-Wert aufgeführt.

scale=1 scale=2
640x640 640x640 (liefert 1.280 × 1.280 Pixel zurück)

In diesem Beispiel wird ein „Schnitt“ der Erde am Äquator auf Zoomebene 1 angefordert:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Äquator

In diesem Beispiel wird eine kleine Karte mit einer Größe von 100 × 100 Pixeln angefordert, die auf derselben Region zentriert ist. Beachten Sie das kleinere Google-Logo:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Kleine Karte vom Äquator

Skalenwerte

Mit dem Parameter size der Maps Static API wird die Größe einer Karte in Pixeln festgelegt. Eine Karte mit size=200x200 wird also mit 200 × 200 Pixeln zurückgegeben. Auf einem LCD-Computerbildschirm, der in der Regel etwa 100 Pixel pro Zoll (ppi) anzeigt, hat eine Karte mit 200 × 200 Pixeln eine Größe von etwa 5 cm in jeder Dimension.

Mobilgeräte haben jedoch zunehmend hochauflösende Displays mit Pixeldichten über 300 ppi, wodurch entweder:

  • Verkleinern Sie ein Bild mit 200 × 200 Pixeln auf nur 0,7 Zoll, wodurch Labels und Symbole zu klein zum Lesen werden.
  • Das Bild wird skaliert (gezoomt), um die Lesbarkeit zu verbessern. Das Bild wird dadurch unscharf oder pixelig.
Zu klein Zu unscharf

Wenn Sie für Mobilgeräte entwickeln, können Sie den Parameter scale der API verwenden, um Kartenbilder mit höherer Auflösung zurückzugeben, die die oben genannten Probleme beheben. Der Wert scale wird mit size multipliziert, um die tatsächliche Ausgabegröße des Bildes in Pixeln zu ermitteln, ohne den Abdeckungsbereich der Karte zu ändern. Der Standardwert für scale ist 1. Zulässige Werte sind 1 und 2.

Bei einem Skalierungswert von 2 wird beispielsweise derselbe Kartenabdeckungsbereich zurückgegeben wie bei einer Anfrage ohne Angabe der Skalierung, jedoch mit doppelt so vielen Pixeln in jeder Dimension. Dazu gehören Straßen und Beschriftungen, damit sie auf hochauflösenden, kleinen Bildschirmen und bei der Skalierung durch den Browser gut lesbar sind.

150x150 150x150&scale=2

Ein solches Bild funktioniert auch in Desktop-Browsern gut, wenn es in ein img- oder div-Tag eingefügt wird, dessen Höhe und Breite mit CSS festgelegt sind. Der Browser verkleinert das Bild ohne Qualitätsverlust auf die richtige Größe.

Diese Tabelle zeigt drei verschiedene Bildanfragen.

  • Die erste ist für ein Bild mit der Größe 100 x 100 und ohne Angabe eines "scale"-Werts. Auf dem Computer wird er richtig angezeigt, auf einem Mobilgerät ist er jedoch zu klein, um gelesen zu werden.
  • In der zweiten wird die Kartengröße verdoppelt. Auf dem Computer passt das CSS in das angegebene img-Element mit der Größe 100 × 100. Beim Verkleinern des Bildes werden jedoch Straßen und Labels zu klein. Auf dem Mobilgerät hat das Bild die richtige Größe, aber auch hier sind Straßen und Beschriftungen unleserlich.
  • Die dritte Anfrage bezieht sich auf eine 100 × 100 Pixel große Karte mit scale=2. Das Bild wird mit 200 Pixeln Detailwiedergabe zurückgegeben. Auf dem Computer wird es perfekt herunterskaliert, sodass es nicht von der ursprünglichen Anfrage mit 100 × 100 Pixeln zu unterscheiden ist. Der mobile Browser profitiert hingegen von der zusätzlichen Auflösung, die von der API zurückgegeben wird.
Bildanfragen
Gerät 100x100 200x200 100x100&scale=2
Computer
(mit height="100px" und
width="100px" im
img-Tag)
Hohe Auflösung
(simuliert)

Weitere Informationen zur Entwicklung für Mobilgeräte und Displays mit hoher Auflösung finden Sie in den folgenden Artikeln:

Bildformate

Bilder können in mehreren gängigen Webgrafikformaten zurückgegeben werden: GIF, JPEG und PNG. Der Parameter format kann einen der folgenden Werte haben:

  • png8 oder png (Standardeinstellung) gibt das 8‑Bit-PNG-Format an.
  • png32 gibt das 32-Bit-PNG-Format an.
  • gif gibt das GIF-Format an.
  • jpg gibt das Komprimierungsformat JPEG an.
  • jpg-baseline gibt ein nicht progressives JPEG-Komprimierungsformat an.

In diesen Beispielen werden Karten in den Formaten gif und png angefordert:

  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=gif&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=png&&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

jpg und jpg-baseline bieten in der Regel die kleinste Bildgröße. Allerdings wird dabei eine „verlustbehaftete“ Komprimierung verwendet, die die Bildqualität beeinträchtigen kann. gif, png8 und png32 bieten eine verlustfreie Komprimierung.

Die meisten JPEG-Bilder sind progressiv, d. h., sie laden zuerst ein gröberes Bild und optimieren die Bildauflösung, sobald mehr Daten eintreffen. Dadurch können Bilder auf Webseiten schnell geladen werden. Dies ist derzeit die am weitesten verbreitete Verwendungsart von JPEG. Für einige Anwendungen von JPEG sind jedoch nicht progressive (Baseline-)Bilder erforderlich. In solchen Fällen sollten Sie das nicht progressive Format jpg-baseline verwenden.

Kartentypen

Mit der Maps Static API können Karten in mehreren Formaten erstellt werden, die unten aufgeführt sind:

  • roadmap (Standardeinstellung) gibt ein Standardbild für Straßenkarten an, wie es normalerweise auf der Google Maps-Website angezeigt wird. Ist kein Wert für maptype angegeben, stellt die Maps Static API standardmäßig roadmap-Kacheln bereit.
  • satellite gibt ein Satellitenbild an.
  • terrain gibt ein Bild einer physischen Reliefkarte an, das Gelände und Vegetation zeigt.
  • hybrid gibt ein Hybridbild aus Satelliten- und Straßenkartenbild an, bei dem eine transparente Schicht mit den wichtigsten Straßen und Ortsnamen über dem Satellitenbild eingeblendet wird.

In diesem Codebeispiel wird der Unterschied zwischen den Typen „Roadmap“ und „Gelände“ veranschaulicht.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Manhattan (normale Karte)  Manhattan (Geländekarte)

Bei Hybridkarten werden Satellitenbilder und gut sichtbare Straßenkartenelemente verwendet, um eine Kombinationskarte zu erstellen. Die folgenden Beispiele zeigen Satelliten- und Hybridkartentypen:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Manhattan (Satellitenkarte)  Manhattan (Geländekarte)

Karten mit benutzerdefinierten Stilen

Passen Sie die Darstellung der Google-Standardkarte an, indem Sie Ihre eigenen Stile anwenden. Weitere Informationen finden Sie im Leitfaden zu Karten mit benutzerdefinierten Stilen.

Markierungen

Mit dem Parameter markers wird eine oder mehrere Markierungen (Kartenmarkierungen) für mehrere Standorte definiert. Jede Markierung, die in einer einzelnen markers-Deklaration definiert ist, muss denselben visuellen Stil haben. Wenn Sie Markierungen mit unterschiedlichen Stilen darstellen möchten, müssen Sie mehrere markers-Parameter mit separaten Stilinformationen angeben.

Der Parameter markers akzeptiert eine Gruppe von Wertzuweisungen (Markierungsdeskriptoren) im folgenden Format:

markers=markerStyles|markerLocation1| markerLocation2|... usw.

Die markerStyles werden am Anfang der markers-Deklaration deklariert und bestehen aus null oder mehr Stilbeschreibungen, die durch das Pipe-Zeichen (|) getrennt sind. Darauf folgt ein Satz von ein oder mehreren Standorten, die ebenfalls durch das Pipe-Zeichen (|) getrennt sind.

Da sowohl die Stil- als auch die Standortinformationen durch einen senkrechten Strich getrennt werden, müssen die Stilinformationen in Markierungsbeschreibungen zuerst aufgeführt werden. Sobald der Maps Static API-Server einen Standort im Markierungs-Descriptor findet, wird davon ausgegangen, dass alle anderen Markierungsparameter ebenfalls Standorte sind.

Markierungsstile

Die Deskriptoren für den Markierungsstil sind eine Reihe von Wertzuweisungen, die durch das Pipe-Zeichen (|) getrennt sind. Dieser Stilbeschreiber definiert die visuellen Attribute, die bei der Anzeige der Markierungen in diesem Markierungsbeschreiber verwendet werden sollen. Diese Stilbeschreibungen enthalten die folgenden Schlüssel/Wert-Zuweisungen:

  • size: (optional) gibt die Größe der Markierung aus dem Satz {tiny, mid, small} an. Wenn kein size-Parameter festgelegt ist, wird die Markierung in ihrer Standardgröße (normal) angezeigt.
  • color: (optional): Gibt eine 24-Bit-Farbe (z. B. color=0xFFFFCC) oder eine vordefinierte Farbe aus dem Satz {black, brown, green, purple, yellow, blue, gray, orange, red, white} an.

    Hinweis: Transparenzen (mit 32‑Bit-Hexadezimalfarbwerten angegeben) werden bei Markierungen nicht unterstützt, bei Pfaden jedoch schon.

  • label: ist optional und gibt ein einzelnes alphanumerisches Zeichen in Großbuchstaben aus dem Satz {A–Z, 0–9} an. Die Verwendung von Großbuchstaben ist in dieser Version der API neu. Nur Standard- und mid-Markierungen können einen alphanumeric-character-Parameter anzeigen. Bei tiny- und small-Markierungen kann kein alphanumerisches Zeichen angezeigt werden.

Größe von Markierungen

Der Wert scale wird mit der Größe des Markierungsbilds multipliziert, um die tatsächliche Ausgabegröße der Markierung in Pixeln zu erhalten. Der Standardwert für die Skalierung ist 1. Zulässige Werte sind 1, 2 und 4.

Die Beschränkung der Pixelgröße für Bilder gilt nach der Skalierung. Wenn die Markierung beispielsweise auf scale:2 festgelegt ist, kann sie größer als die maximale Größe von 4.096 Pixeln sein, solange sie nach dem Skalieren auf weniger als 4.096 Pixel reduziert wird. Verwenden Sie die Markierungsskalierung in Verbindung mit der Kartenskala, wenn Sie Karten mit höherer Auflösung anzeigen.

Markierungspositionen

Jeder Markierungsbeschreiber muss einen oder mehrere Orte enthalten, an denen die Markierung auf der Karte platziert werden soll. Diese Standorte können entweder als Breiten-/Längengrad-Werte oder als addresses angegeben werden. Diese Positionen werden durch einen senkrechten Strich (|) getrennt.

Hinweis: Wenn Sie die Position von Markierungen mithilfe einer Methode angeben, die eine Geocodierung erfordert, z. B. visuell lesbare Adressstrings oder Polylinien, ist die Anfrage auf maximal 15 Markierungen beschränkt. Diese Einschränkung gilt nur für Markierungsstandorte, für die eine Geocodierung erforderlich ist. Das gilt nicht für Markierungen, die mit Breiten- und Längengradkoordinaten angegeben sind.

Die Positionsparameter definieren die Markierungsposition auf der Karte. Wenn sich der Standort nicht auf der Karte befindet, wird die Markierung nicht im erstellten Bild angezeigt, sofern die Parameter center und zoom angegeben sind. Wenn diese Parameter jedoch nicht angegeben werden, erstellt der Static Maps API-Server automatisch ein Bild, das die angegebenen Markierungen enthält. (Siehe Implicit Positioning.)

Hier wird eine Beispielmarkierungsdeklaration angezeigt. Wir definieren einen Satz von Stilen und drei Standorte:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Brooklyn, drei Postleitzahlenbereiche

Wenn wir Markierungen mit unterschiedlichen Stilen definieren möchten, müssen wir mehrere markers-Parameter angeben. Mit diesen markers-Parametern werden drei Markierungen definiert: eine blaue Markierung mit der Kennzeichnung „S“ bei 62.107733, -145.5419, eine kleine grüne Markierung bei „Delta Junction, AK“ und eine mittelgroße gelbe Markierung mit der Kennzeichnung „C“ bei „Tok, AK“. Diese Markierungen werden in diesem Beispiel gezeigt:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Drei Orte in Alaska mit unterschiedlichen Markierungen

Benutzerdefinierte Symbole

Anstelle der Markierungssymbole von Google können Sie Ihre eigenen benutzerdefinierten Symbole verwenden. Benutzerdefinierte Symbole werden mit dem icon-Deskriptor im markers-Parameter angegeben. Beispiel:

markers=icon:URLofIcon|markerLocation

Geben Sie die icon mit einer URL an, die URL-codiert sein muss. Sie können URLs verwenden, die mit URL-Verkürzungsdiensten wie https://goo.gl erstellt wurden. Die meisten URL-Kürzungsdienste haben den Vorteil, dass URLs automatisch codiert werden.

Sie können einen Ankerpunkt für das benutzerdefinierte Symbol angeben. Der Ankerpunkt legt fest, wie das Symbol im Verhältnis zu den angegebenen markers-Positionen platziert wird. Standardmäßig befindet sich der Ankerpunkt eines benutzerdefinierten Symbols in der Mitte unten im Symbolbild. Mit dem anchor-Beschreibungselement in Verbindung mit icon können Sie einen anderen Ankerpunkt angeben. Legen Sie anchor als x- und y-Punkt des Symbols (z. B. 10,5) oder als vordefinierte Ausrichtung mit einem der folgenden Werte fest: top, bottom, left, right, center, topleft, topright, bottomleft oder bottomright. Beispiel:

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

Sie können bis zu fünf eindeutige benutzerdefinierte Symbole pro Anfrage verwenden. Das bedeutet aber nicht, dass auf der Karte maximal fünf Orte markiert sind. Jedes eindeutige Symbol kann für mehrere markers-Standorte auf Ihrer Karte verwendet werden.

Symbolformat:

  • Symbolbilder können im PNG-, JPEG- oder GIF-Format vorliegen. PNG wird empfohlen.
  • Symbole dürfen maximal 4.096 Pixel groß sein (64 × 64 Pixel für quadratische Bilder).
Beispiele für benutzerdefinierte Symbole

In Beispiel 1 werden benutzerdefinierte Symbole erstellt und die Symbole mithilfe von Ankern positioniert.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

Drei australische Städte mit verschiedenen benutzerdefinierten Symbolen, die mit Ankern positioniert sind.

In Beispiel 2 werden dieselben benutzerdefinierten Symbole wie in Beispiel 1 erstellt, aber die Symbolpositionen werden nicht mithilfe von Ankern festgelegt, sondern durch den Standardanker „unten Mitte“.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Drei australische Städte, unterschiedliche benutzerdefinierte Symbole mit Standardpositionierung

Maps Static API-Pfade

Der Parameter path definiert eine Gruppe von mindestens zwei Orten, die über einen Pfad miteinander verbunden sind und als Overlay auf das Kartenbild gelegt werden. Der Parameter path nimmt einen Satz von Wertezuweisungen (Pfaddeskriptoren) im folgenden Format an:

path=pathStyles|pathLocation1|pathLocation2|... usw.

Beachten Sie, dass beide Pfadpunkte durch das Pipe-Zeichen (|) voneinander getrennt sind. Da sowohl Stilinformationen als auch Punktinformationen durch das Pipe-Zeichen abgegrenzt werden, müssen Stilinformationen in jedem Pfad-Descriptor zuerst erscheinen. Sobald der Maps Static API-Server einen Ort im Pfad-Descriptor findet, werden alle anderen Pfadparameter als Orte angenommen.

Pfadstile

Die Pfadstil-Deskriptoren bestehen aus einer Reihe von Wertzuweisungen, die durch das Pipe-Zeichen (|) getrennt sind. Dieser Stilbeschreiber definiert die visuellen Attribute, die beim Darstellen des Pfades verwendet werden sollen. Diese Stilbeschreibungen enthalten die folgenden Schlüssel/Wert-Zuweisungen:

  • weight: (optional): Gibt die Stärke des Pfads in Pixeln an. Wenn kein weight-Parameter festgelegt ist, erscheint der Pfad in der Standardstärke (5 Pixel).
  • color: (optional): Gibt eine Farbe entweder als 24‑Bit- (z. B. color=0xFFFFCC) oder 32‑Bit-Hexadezimalwert (z. B. color=0xFFFFCCFF) oder aus dem Satz {black, brown, green, purple, yellow, blue, gray, orange, red, white} an.

    Wenn ein hexadezimaler 32-Bit-Wert angegeben wird, geben die letzten beiden Zeichen den 8-Bit-Alphatransparenzwert an. Dieser Wert variiert zwischen 00 (völlig transparent) und FF (völlig undurchsichtig). Transparenz wird für Pfade unterstützt, aber nicht für Markierungen.

  • fillcolor: (optional) gibt an, dass der Pfad einen polygonalen Bereich abgrenzt, und gibt die Füllfarbe an, die als Overlay innerhalb dieses Bereichs verwendet werden soll. Die nachfolgenden Standorte müssen keine geschlossene Schleife bilden. Der Maps Static API-Server verbindet den ersten und den letzten Punkt automatisch. Beachten Sie jedoch, dass alle Striche außerhalb des ausgefüllten Bereichs nicht geschlossen werden, es sei denn, Sie geben denselben Start- und Endpunkt an.
  • geodesic: (optional): Gibt an, dass der angeforderte Pfad als geodätische Linie interpretiert werden soll, die der Krümmung der Erde folgt. Bei „false“ wird der Pfad im Bildschirmbereich als gerade Linie gerendert. Die Standardeinstellung ist "false".

Einige Beispiele für Pfaddefinitionen:

  • Dünne blaue Linie, 50% Deckkraft: path=color:0x0000ff80|weight:1
  • Durchgezogene rote Linie: path=color:0xff0000ff|weight:5
  • Durchgängige dicke weiße Linie: path=color:0xffffffff|weight:10

Diese Pfadformate sind optional. Wenn Sie Standardattribute verwenden möchten, können Sie die Pfadattribute überspringen. In diesem Fall besteht das erste „Argument“ des Pfad-Descriptors stattdessen aus dem ersten angegebenen Punkt (Speicherort).

Pfadpunkte

Damit ein Pfad gezeichnet werden kann, müssen dem Parameter path auch zwei oder mehr Punkte übergeben werden. Die Maps Static API verbindet dann den Pfad entlang dieser Punkte in der angegebenen Reihenfolge. Jeder pathPoint wird im pathDescriptor durch das Zeichen | (Pipe) getrennt.

Im folgenden Beispiel wird ein blauer Pfad mit der Standardundurchsichtigkeit von 50% vom Union Square in New York zum Times Square in New York definiert.

Pfad vom Union Square zum Times Square

Der path-Parameter enthält folgende Angaben:

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

Im folgenden Beispiel wird für denselben Pfad stattdessen eine durchgezogene rote Linie mit 100% Deckkraft definiert:

Pfad vom Union Square zum Times Square

Die Details dieses path-Parameters sind:

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

Im nächsten Beispiel wird ein polygonaler Bereich in Manhattan definiert, für den eine Reihe von Kreuzungen als Standorte übergeben wird:

Pfad vom Union Square zum Times Square

Die Besonderheiten dieses path-Parameters:

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

Beachten Sie, dass wir den Pfad selbst unsichtbar und den polygonalen Bereich mit einer Deckkraft von 15% festgelegt haben.

Codierte Polylinien

Anstelle einer Reihe von Standorten können Sie einen Pfad stattdessen als codierte Polylinie deklarieren. Dazu verwenden Sie in der Standortdeklaration von path das Präfix enc:.

Im folgenden Beispiel wird der Verlauf des Alaska Highway von Dawson Creek, BC, nach Delta Junction, AK, mit einer codierten Polylinie dargestellt:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Alaska Highway

Wie bei Standardpfaden können auch codierte Polylinienpfade polygonale Bereiche abgrenzen, wenn dem Parameter path ein fillcolor-Argument übergeben wird.

Im folgenden Beispiel wird eine Polygonfläche für Brooklyn, New York, dargestellt:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Codierte Polylinie in Brooklyn mit Signatur

Darstellungsbereiche

Für Bilder kann ein Darstellungsbereich angegeben werden, indem mit dem Parameter visible sichtbare Orte angegeben werden. Der Parameter visible weist den Maps Static API-Dienst an, eine Karte so zu erstellen, dass die vorhandenen Standorte sichtbar bleiben. Dieser Parameter kann auch mit vorhandenen Markierungen oder Pfaden kombiniert werden, um eine sichtbare Region zu definieren. Wenn Sie einen Darstellungsbereich auf diese Weise definieren, muss keine exakte Zoomstufe angegeben werden.

Im nächsten Beispiel wird eine Karte angefordert, deren Mittelpunkt Boston, Massachusetts, ist und die sowohl das MIT als auch den Harvard Square in Cambridge, Massachusetts, enthält:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Karte von Cambridge

Implizites Positionieren der Karte

Normalerweise müssen Sie die URL-Parameter center und zoom angeben, um den Standort und die Zoomstufe der generierten Karte zu definieren. Wenn Sie jedoch die Parameter markers, path oder visible angeben, kann die Maps Static API die richtige Mitte und Zoomstufe anhand der Position dieser Elemente implizit bestimmen.

Wenn Sie zwei oder mehr Elemente angeben, ermittelt die Maps Static API eine geeignete Mitte und Zoomstufe und lässt großzügige Ränder für die enthaltenen Elemente. In diesem Beispiel wird eine Karte mit San Francisco, Oakland und San Jose, CA, angezeigt:

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Roadmap

Größere Bildgrößen

Wenn Sie Bilder mit einer Größe von mehr als 640 × 640 Pixeln (oder 1.280 × 1.280 Pixeln mit einem Skalierungswert von 2) benötigen, wenden Sie sich bitte an das Supportteam und machen Sie dabei folgende Angaben:

  1. Ihren Anwendungsfall und warum Sie große Bilder benötigen.
  2. Ob Sie die Verwendung anderer APIs der Google Maps Platform (Maps JavaScript API, Maps Embed API, Maps SDK for Android oder Maps SDK for iOS) in Betracht gezogen haben und warum diese nicht Ihren Anforderungen entsprechen.
  3. Screenshots, Mockups oder Beispiele dafür, wie Sie große Bilder verwenden.
  4. Ihre geschätzte monatliche Nutzung für Bilder im großen Format.

Wir prüfen Ihren Antrag anhand der von Ihnen bereitgestellten Informationen und ermitteln, ob Ihr Anwendungsfall den Nutzungsbedingungen der Google Maps Platform entspricht.

Die maximale Größe beträgt 2048 x 2048 Pixel.

Fehlerbehebung und Support

Weitere Informationen zur Verwendung der Maps Static API finden Sie auf der Supportseite.

Die Maps Static API gibt unter Umständen einen Fehler oder eine Warnung aus, wenn ein Fehler auftritt. Achten Sie insbesondere auf Warnungen, wenn Sie feststellen, dass auf der Karte etwas fehlt. Es empfiehlt sich auch, vor dem Start einer neuen Anwendung nach Warnungen zu suchen. Die Warnungen sind möglicherweise nicht sofort sichtbar, da sie im HTTP-Header angezeigt werden. Weitere Informationen finden Sie im Leitfaden zu Fehlern und Warnungen.