Erste Schritte

Einführung

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

Ein Maps Static API-Bild ist in das Attribut src eines <img>-Tags oder dessen Äquivalent 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 hier einige Tipps und Tricks für die Angabe Ihrer URLs.

Hinweis

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

Bevor Sie mit der Maps Static API entwickeln, sehen Sie sich die Authentifizierungsanforderungen (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) an.

URL-Parameter

Eine Maps Static API-URL muss das folgende Format haben:

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

Wenn der Zugriff auf Ihre Website über HTTPS erfolgt, müssen Sie Maps Static API-Bilder auch über HTTPS laden, um Sicherheitswarnungen des Browsers zu vermeiden. HTTPS wird auch empfohlen, wenn Ihre Anfragen vertrauliche Nutzerinformationen wie den Standort des Nutzers enthalten:

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

Bei Verwendung von HTTP oder HTTPS sind bestimmte URL-Parameter erforderlich, während andere optional sind. Wie bei URLs üblich, werden alle Parameter durch das Et-Zeichen (&) getrennt. Die Liste der Parameter und ihrer möglichen Werte sind in diesem Dokument aufgeführt.

In der Maps Static API werden Kartenbilder mithilfe der folgenden URL-Parameter definiert:

Standortparameter

• center (erforderlich, wenn keine Markierungen vorhanden sind) definiert die Kartenmitte, mit gleichem Abstand von allen Rändern der Karte. Dieser Parameter verwendet einen Standort entweder als kommagetrenntes {Breitengrad,Längengrad}-Paar (z.B. „40.714728,-73.998672“) oder als Stringadresse (z.B. „city hall, new york, ny“), die einen eindeutigen Standort auf der Erde angibt. Weitere Informationen finden Sie unter Standorte.
• zoom (erforderlich, wenn keine Markierungen vorhanden sind) definiert die Zoomstufe der Karte, mit der die Vergrößerungsstufe der Karte bestimmt wird. Dieser Parameter verwendet einen numerischen Wert, der der Zoomstufe des gewünschten Bereichs entspricht. Weitere Informationen finden Sie unter Zoomstufen.

Zuordnungsparameter

• size (erforderlich) definiert die Größe der rechteckigen Form des Kartenbildes. 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 der Größen- und Skalierungswerte.
• scale (optional) wirkt sich auf die Anzahl der zurückgegebenen Pixel aus. scale=2 gibt doppelt so viele Pixel zurück wie scale=1. Dabei bleibt der Abdeckungsbereich und die Detailebene gleich (der Inhalt der Karte ändert sich also nicht). Dies ist nützlich bei der Entwicklung für hochauflösende Displays. Der Standardwert ist 1. Zulässige Werte sind 1 und 2. Weitere Informationen finden Sie unter Skalierungswerte.
• format (optional) definiert das Format des Bilds. Die Maps Static API erstellt standardmäßig PNG-Bilder. Es gibt verschiedene 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 stärkere Komprimierung, GIF und PNG liefern mehr Details. Weitere Informationen finden Sie unter Bildformate.
• maptype (optional) definiert den Typ der zu erstellenden Karte. 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) legt die Sprache fest, in der Labels auf Kartenkacheln angezeigt werden sollen. Dieser Parameter wird nur für einige Länderkacheln unterstützt. Wenn die angeforderte Sprache für den Kachelsatz nicht unterstützt wird, wird die Standardsprache für diesen Kachelsatz verwendet.
• region (optional) definiert die anzuzeigenden Grenzen basierend auf geopolitischen Aspekten. Akzeptiert einen Regionscode, der als zweistelliger ccTLD-Wert („Top-Level-Domain“) angegeben wird. Informationen zu den unterstützten Regionen finden Sie unter 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 Element 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) definiert eine oder mehrere Markierungen, die an den angegebenen Positionen zum Bild hinzugefügt werden. Für diesen Parameter wird eine einzelne Markierungsdefinition verwendet, wobei die einzelnen Parameter durch einen senkrechten Strich (|) getrennt sind. In einem markers-Parameter können mehrere Markierungen platziert werden, sofern sie denselben Stil aufweisen. Durch zusätzliche markers-Parameter können Sie weitere Markierungen mit unterschiedlichen Stilen 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 Maps Static API-Markierungen.
• path (optional) definiert einen einzelnen Pfad mit zwei oder mehr verbundenen Punkten, der an bestimmten Orten auf das Bild gelegt werden soll. Dieser Parameter wird als String aus Punktdefinitionen angegeben, die durch ein Pipe-Zeichen (|) getrennt sind, oder als codierte Polylinie mit dem Präfix enc: innerhalb 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 Maps Static API-Pfade.
• visible (optional) gibt einen oder mehrere Standorte an, die auf der Karte sichtbar bleiben sollen, auch wenn keine Markierungen oder anderen Indikatoren angezeigt werden. Mit diesem Parameter sorgen Sie dafür, dass bestimmte Elemente oder Kartenpositionen in der Maps Static API angezeigt werden.
• style (optional) definiert einen benutzerdefinierten Stil, um die Darstellung eines bestimmten Kartenelements (Straßen, Parks und andere Elemente) zu ändern. Dieser Parameter verwendet die Argumente feature und element, mit denen die zu formatierenden Elemente angegeben werden, sowie eine Reihe von Stilvorgängen, die auf die ausgewählten Elemente angewendet werden sollen. Sie können mehrere Stile bereitstellen, indem Sie zusätzliche style-Parameter hinzufügen. Weitere Informationen finden Sie im Leitfaden zu Karten mit benutzerdefinierten Stilen.

Schlüssel- und Signaturparameter

• Mit key (erforderlich) können Sie die API-Nutzung Ihrer Anwendung in der Google Cloud Console beobachten 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.

URL-Größenbeschränkung

Maps Static API-URLs sind auf 16.384 Zeichen beschränkt. In der Praxis brauchen Sie längere URLs wahrscheinlich nicht, es sei denn, Sie erstellen komplizierte Karten mit einer großen Anzahl von Markierungen und Pfaden.

Parameterverwendung

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.

Standorte angeben

Die Maps Static API muss Standorte auf der Karte präzise identifizieren können, damit die Karte mit dem Parameter center an der richtigen Position fokussiert und/oder optionale Ortsmarkierungen (mit dem Parameter markers) an Orten auf der Karte platziert werden können. Die Maps Static API verwendet Zahlen (Breiten- und Längengradwerte) oder Strings (Adressen), um diese Standorte anzugeben. Diese Werte identifizieren einen geocodierten Standort.

Verschiedene Parameter (z. B. die Parameter markers und path) nehmen mehrere Positionen an. In diesen Fällen werden die Positionen durch einen senkrechten Strich (|) getrennt.

Breiten- und Längengrade

Breiten- und Längengrade werden durch Ziffern in einer durch Kommas getrennten Textzeichenfolge mit einer Genauigkeit von sechs Dezimalstellen definiert. „40.714728,-73.998672“ ist beispielsweise ein gültiger Geocode-Wert. Eine Genauigkeit, die über sechs Dezimalstellen hinausgeht, wird ignoriert.

Die Längengradwerte basieren auf der Entfernung von Greenwich in England, der Heimat des Nullmeridians. Da Greenwich beim Breitengradwert 51.477222 liegt, können wir für center den Wert 51.477222,0 eingeben, um die Karte bei Greenwich zu zentrieren:

Breiten- und Längengradwerte müssen einem gültigen Standort auf der Erdoberfläche entsprechen. Für den Breitengrad können alle Werte zwischen -90 und 90 und für den Längengrad alle Werte zwischen -180 und 180 angegeben werden. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als fehlerhaft abgelehnt.

Adressen

Die meisten Menschen sprechen nicht in Breiten- und Längengraden. Standorte werden durch Adressen bezeichnet. Das Umwandeln einer Adresse in einen geografischen Punkt wird als Geocoding bezeichnet. Wenn Sie gültige Adressen angeben, kann die Maps Static API eine Geocodierung für Sie vornehmen.

In jedem Parameter, für den Sie einen Breiten- und Längengrad angeben können, können Sie stattdessen einen String angeben, der eine address angibt. Google geocodiert die Adresse und stellt dem Maps Static API-Dienst einen Breiten- und Längengradwert zur Verfügung, der zum Platzieren von Markierungen oder Angeben von Standorten verwendet wird. Der String sollte URL-codiert sein, sodass Adressen wie "City Hall, New York, NY" z. B. in "City+Hall,New+York,NY" umgewandelt werden sollten.

Beachten Sie, dass Adressen entweder genaue Standorte wie Adressen, Polylinien wie benannte Routen oder polygonale Gebiete wie Städte, Länder oder Nationalparks widerspiegeln können. Bei polygonalen und polygonalen Ergebnissen verwendet der Maps Static API-Server den Mittelpunkt der Linie bzw. des Bereichs als Adressmittelpunkt. Wenn Sie Zweifel daran haben, wie eine Adresse geocodiert werden kann, können Sie die Adresse 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

Zoomstufen

Karten in Google Maps haben eine ganzzahlige Zoomstufe, die die Auflösung der aktuellen Ansicht definiert. In der Standardansicht roadmap sind Zoomstufen zwischen 0 (niedrigste Zoomstufe, bei der die ganze Welt auf einer Karte zu sehen ist) und 21+ (bis hin zu Straßen und einzelnen Gebäuden) möglich. Gebäudeumrisse werden, sofern verfügbar, auf der Karte um die Zoomstufe 17 herum angezeigt. Dieser Wert unterscheidet sich von Bereich zu Bereich und kann sich im Laufe der Zeit ändern, wenn sich die Daten entwickeln.

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

Hinweis: Nicht alle Vergrößerungsstufen sind für alle Standorte weltweit verfügbar. Die Zoomstufen variieren je nach Standort, da die Daten in einigen Teilen der Welt detaillierter sind als an anderen.

Wenn Sie eine Anfrage für eine Zoomstufe senden, in der 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 jeder 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

  

Bildgrößen

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

Diese Tabelle enthält die maximal zulässigen Werte für den Parameter size bei jedem scale-Wert.

scale=1	scale=2
640x640	640x640 (gibt 1280 x 1280 Pixel zurück)

In diesem Beispiel wird ein Ausschnitt der Erde am Äquator mit Zoomstufe 1 angefordert:

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

In diesem Beispiel wird eine kleine Karte der Größe 100 × 100 Pixel angefordert, die auf dieselbe 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

Skalierungswerte

Der size-Parameter der Maps Static API definiert die Größe einer Karte in Pixeln, sodass eine Karte mit size=200x200 als 200 × 200 Pixel zurückgegeben wird. Auf einem LCD-Computermonitor, der normalerweise etwa 100 ppi (Pixel pro Zoll) anzeigt, hat eine Karte mit 200 × 200 eine Größe von etwa 2 Zoll in jeder Dimension.

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

• Die Größe eines Bildes mit 200 × 200 Pixeln wird auf nur 0,7 Zoll reduziert, wodurch Labels und Symbole zu klein zum Lesen sind, oder
• Das Bild wird skaliert (gezoomt), um die Lesbarkeit zu verbessern, was zu einem unscharfen oder verpixelten Bild führt.

Zu klein	Zu unscharf

Bei der Entwicklung für Mobilgeräte können Sie den Parameter scale der API verwenden, um Kartenbilder mit höherer Auflösung zurückzugeben und die oben genannten Probleme zu 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 Wert von „scale“ von 2 wird derselbe Kartenabdeckungsbereich zurückgegeben wie bei einer Anfrage ohne „scale“-Angabe, aber mit doppelt so vielen Pixeln in jeder Dimension. Dies schließt Straßen und Labels ein, damit sie auf hohen Auflösungen, kleinen Bildschirmen und bei Skalierung durch den Browser 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 und die Höhe und Breite mithilfe von CSS festgelegt wird. 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 100x100 ohne angegebenen Skalierungswert. Er wird auf dem Desktop korrekt angezeigt, ist aber auf einem Mobilgerät zu klein, um ihn zu lesen.
• Bei der zweiten Bildanforderung 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 Labels unleserlich.
• Die dritte Anfrage ist für eine Karte im Format 100 × 100 mit scale=2. Das Bild wird mit 200 Pixeln Details zurückgegeben. Auf dem Desktop wird es perfekt verkleinert, sodass es nicht mehr von der ursprünglichen Anfrage im Format 100 x 100 zu unterscheiden ist. Der mobile Browser profitiert 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 zum Entwickeln für mobile und hochauflösende Displays finden Sie in den folgenden Lesematerialien:

• Supporting Multiple Screens (Unterstützung mehrerer Bildschirme) in der Android-Entwicklerdokumentation
• Empfehlungen von Webkit.org zum Entwickeln von High DPI-Websites.
• Supporting High-Resolution Screens in der iOS-Entwicklerbibliothek.

Bildformate

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

• 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 JPEG-Komprimierungsformat 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. Bei der Komprimierung kann jedoch die Bildqualität beeinträchtigt werden. gif, png8 und png32 bieten eine verlustfreie Komprimierung.

Die meisten JPEG-Bilder sind progressiv. Dies bedeutet, dass früher ein gröberes Bild geladen wird und die Bildauflösung verfeinert wird, wenn mehr Daten eingehen. Dadurch können Bilder auf Webseiten schnell geladen werden. Dies ist die derzeit am meisten verbreitete Verwendungsart von JPEG. Für einige JPEG-Anwendungen sind jedoch nicht progressive (Baseline-)Bilder erforderlich. In solchen Fällen können Sie das nicht progressive Format jpg-baseline verwenden.

Kartentypen

Mit der Maps Static API werden Karten in den folgenden Formaten erstellt:

• roadmap (Standardeinstellung) gibt ein standardmäßiges Straßenkartenbild an, wie es normalerweise auf der Google Maps-Website angezeigt wird. Wenn kein maptype-Wert angegeben ist, stellt die Maps Static API standardmäßig roadmap-Kacheln bereit.
• satellite gibt ein Satellitenbild an.
• terrain gibt ein Kartenbild mit einem physischen Relief an, das das Gelände und die Vegetation wiedergibt.
• 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 sehen Sie den Unterschied zwischen Straßenkarten- und Geländetypen.

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

  

Für Hybridkarten werden Satellitenbilder und markante 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

  

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) an mehreren Standorten definiert. Jede Markierung, die in einer einzelnen markers-Deklaration definiert wird, muss denselben visuellen Stil haben. Wenn Markierungen mit unterschiedlichen Stilen angezeigt werden sollen, 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.

Der Satz von markerStyles wird am Anfang der markers-Deklaration deklariert und besteht aus null oder mehr Stildeskriptoren, die durch ein Pipe-Zeichen (|) voneinander getrennt sind, gefolgt von einer oder mehreren Positionen, die ebenfalls durch ein Pipe-Zeichen (|) voneinander getrennt sind.

Da sowohl die Stil- als auch die Standortinformationen durch einen senkrechten Strich getrennt werden, müssen die Stilinformationen in Markierungsdeskriptoren an erster Stelle stehen. Sobald der Maps Static API-Server im Markierungsdeskriptor einen Standort erkennt, wird angenommen, dass es sich bei allen anderen Markierungsparametern ebenfalls um Standorte handelt.

Markierungsstile

Bei den Markierungsstildeskriptoren handelt es sich um eine Reihe von Wertzuweisungen, die durch ein Pipe-Zeichen (|) getrennt sind. Dieser Stildeskriptor definiert die visuellen Attribute, die beim Anzeigen der Markierungen in diesem Markierungsdeskriptor verwendet werden sollen. Diese Stildeskriptoren enthalten die folgenden Schlüssel/Wert-Zuweisungen:

• size: ist optional und gibt die Größe der Markierung an. {tiny, mid, small} Wenn kein size-Parameter festgelegt ist, wird die Markierung in der 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.

  Transparenzen (angegeben mit 32-Bit-Hexadezimal-Farbwerten) werden in Markierungen nicht unterstützt, für Pfade hingegen schon.

• label: (optional) gibt ein einzelnes großgeschriebenes alphanumerisches Zeichen aus der Gruppe {A-Z, 0-9} an. Die Verwendung von Großbuchstaben ist in dieser Version der API neu. Nur in Markierungen der Standardgröße und der Größe mid kann ein alphanumeric-character-Parameter angezeigt werden. In tiny- und small-Markierungen kann kein alphanumerisches Zeichen angezeigt werden.

Markierungsskalierung

Der Wert scale wird mit der Bildgröße der Markierung 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 gesetzt ist, kann sie größer als die maximale Größe von 4.096 Pixeln sein, solange sie nach der Skalierung auf weniger als 4.096 Pixel reduziert wird. Verwenden Sie die Markierungsskalierung in Verbindung mit der Kartenskalierung, wenn Karten mit höherer Auflösung angezeigt werden sollen.

Markierungspositionen

Jeder Markierungsdeskriptor muss einen oder mehrere Standorte enthalten, mit denen festgelegt wird, wo die Markierung auf der Karte platziert werden soll. Diese Standorte können entweder als Breiten-/Längengradwerte oder als Adressen angegeben werden. Diese Positionen werden durch einen senkrechten Strich (|) getrennt.

Hinweis: Wenn Sie die Position von Markierungen mithilfe einer Methode angeben, die Geocoding erfordert, z. B. visuell lesbare Adressstrings oder Polylinien, ist die Anfrage auf maximal 15 Markierungen beschränkt. Dieses Limit gilt nur für Markierungspositionen, für die eine Geocodierung erforderlich ist. Sie gilt nicht für Markierungspositionen, die mit Breiten-/Längenkoordinaten angegeben werden.

Die Positionsparameter definieren die Markierungsposition auf der Karte. Wenn der Standort außerhalb der Karte liegt, wird die Markierung nicht auf dem erstellten Bild angezeigt, sofern die Parameter center und zoom angegeben sind. Werden diese Parameter nicht angegeben, erstellt der Maps Static API-Server automatisch ein Bild mit den angegebenen Markierungen. Weitere Informationen finden Sie unter Implizite Positionierung.

Hier sehen Sie ein Beispiel für eine Markierungsdeklaration. Beachten Sie, dass wir einen Satz von Stilen und drei Positionen definieren:

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

Wenn Sie Markierungen mit unterschiedlichen Stilen definieren möchten, müssen Sie mehrere markers-Parameter angeben. Mit diesen markers-Parametern werden drei Markierungen definiert: eine blaue Markierung mit dem Label „S“ bei 62.107733, -145.5419, eine winzige grüne Markierung bei „Delta Junction, AK“ und eine mittelgroße gelbe Markierung mit dem Label „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

Benutzerdefinierte Symbole

Statt die Markierungssymbole von Google zu verwenden, können Sie auch eigene, benutzerdefinierte Symbole verwenden. Benutzerdefinierte Symbole werden mit dem Deskriptor icon im Parameter markers angegeben. Beispiel:

markers=icon:URLofIcon|markerLocation

Geben Sie icon mithilfe einer URL an. Diese sollte URL-codiert sein. Sie können URLs verwenden, die von URL-Kürzungsdiensten wie https://goo.gl erstellt wurden. Die meisten URL-Kürzungsdienste bieten den Vorteil, dass sie URLs automatisch codieren.

Sie können einen Ankerpunkt für das benutzerdefinierte Symbol angeben. Der Ankerpunkt legt fest, wie das Symbol in Bezug auf die angegebenen markers-Positionen platziert wird. Standardmäßig befindet sich der Ankerpunkt eines benutzerdefinierten Symbols in der unteren Mitte des Symbolbildes. Mit dem anchor-Deskriptor 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. Diese Einschränkung bedeutet jedoch nicht, dass Sie nur 5 markierte Standorte auf der Karte haben. Jedes eindeutige Symbol kann mit mehr als einem markers-Standort auf der Karte verwendet werden.

Symbolformat:

• Symbolbilder können im PNG-, JPEG- oder GIF-Format vorliegen. Empfohlen wird PNG.
• Symbole können eine maximale Größe von bis zu 4096 Pixeln haben (64 x 64 bei quadratischen Bildern).

Beispiele für benutzerdefinierte Symbole

In Beispiel 1 werden benutzerdefinierte Symbole erstellt und 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

In Beispiel 2 werden die gleichen benutzerdefinierten Symbole wie in Beispiel 1 erstellt. Die Symbolpositionen werden jedoch nicht mithilfe von Ankern festgelegt, sondern gestützt auf den Standardanker unten in der 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

Maps Static API-Pfade

Mit dem Parameter path wird ein oder mehrere Standorte definiert, die über einen Pfad als Overlay auf dem Kartenbild dargestellt werden. Der Parameter path akzeptiert eine Gruppe von Wertzuweisungen (Pfaddeskriptoren) im folgenden Format:

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

Beide Pfadpunkte werden durch einen senkrechten Strich (|) voneinander getrennt. Da sowohl Stilinformationen als auch Punktinformationen durch einen senkrechten Strich getrennt werden, müssen die Stilinformationen in Pfaddeskriptoren an erster Stelle stehen. Sobald der Maps Static API-Server einen Standort im Pfaddeskriptor findet, wird angenommen, dass es sich bei allen anderen Pfadparametern ebenfalls um Standorte handelt.

Pfadstile

Bei den Pfadstildeskriptoren handelt es sich um eine Reihe von Wertzuweisungen, die durch ein Pipe-Zeichen (|) getrennt sind. Dieser Stildeskriptor definiert die visuellen Attribute, die bei der Anzeige des Pfads verwendet werden sollen. Diese Stildeskriptoren enthalten die folgenden Schlüssel/Wert-Zuweisungen:

• weight: (optional) gibt die Stärke des Pfads in Pixeln an. Wenn kein weight-Parameter festgelegt ist, wird der Pfad mit der Standardstärke (5 Pixel) angezeigt.

• color: (optional) gibt eine Farbe als 24-Bit- (Beispiel: color=0xFFFFCC) oder 32-Bit-Hexadezimalwert (Beispiel: color=0xFFFFCCFF) oder aus dem Satz {black, brown, green, purple, yellow, blue, gray, orange, red, white} an.

  Wenn ein 32-Bit-Hexadezimalwert angegeben wird, geben die letzten beiden Zeichen den 8-Bit-Alphatransparenzwert an. Dieser Wert variiert zwischen 00 (vollständig transparent) und FF (vollständig undurchsichtig). Transparenzen werden in Pfaden unterstützt, für Markierungen aber nicht.

• fillcolor: (optional) gibt an, dass der Pfad eine Polygonfläche abgrenzt, und gibt die Füllfarbe an, die als Overlay in diesem Bereich verwendet werden soll. Bei den folgenden Standorten muss es sich nicht um eine geschlossene Schleife handeln. Der Maps Static API-Server verbindet den ersten und den letzten Punkt automatisch miteinander. Beachten Sie jedoch, dass jeder Strich außerhalb des ausgefüllten Bereichs nur dann geschlossen wird, wenn Sie ausdrücklich dieselbe Start- und Endposition angeben.
• 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 als gerade Linie im Bildschirmbereich gerendert. Die Standardeinstellung ist "false".

Hier einige Beispiele für Pfaddefinitionen:

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

Diese Pfadformate sind optional. Wenn Standardattribute gewünscht werden, können Sie die Definition der Pfadattribute überspringen. In diesem Fall besteht das erste „Argument“ des Pfaddeskriptors anstelle des ersten deklarierten Punkts (Standort).

Pfadpunkte

Zum Zeichnen eines Pfades müssen dem path-Parameter auch mindestens zwei Punkte übergeben werden. Die Maps Static API verbindet dann den Pfad entlang dieser Punkte in der angegebenen Reihenfolge. Jeder pathPoint wird im pathDescriptor angegeben und durch ein senkrechtes Strichzeichen (|) getrennt.

Im folgenden Beispiel wird ein blauer Pfad mit einer Standardopazität von 50% von Union Square New York bis Times Square, NY definiert.

Die Angaben des path-Parameters sind:

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 derselbe Pfad stattdessen mit einer durchgehenden roten Linie mit 100% Deckkraft definiert:

Die Angaben dieses path-Parameters lauten:

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 Polygon in Manhattan definiert und eine Reihe von Kreuzungen als Standorte übergeben:

Die Angaben dieses path-Parameters lauten:

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

Der Pfad selbst ist unsichtbar und die polygonale Fläche hat eine Deckkraft von 15 %.

Codierte Polylinien

Anstelle einer Reihe von Standorten können Sie einen Pfad als codierte Polylinie angeben. Verwenden Sie dazu das Präfix enc: in der Standortdeklaration von path.

Im folgenden Beispiel wird der Verlauf des Alaska Highway von Dawson Creek, BC, bis 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}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Wie bei Standardpfaden können codierte Polylinienpfade auch Polygonbereiche abgrenzen, wenn ein fillcolor-Argument an den Parameter path übergeben wird.

Im folgenden Beispiel wird ein polygonaler Bereich für Brooklyn, New York, hervorgehoben:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Viewports

Für Bilder kann ein Darstellungsbereich angegeben werden, indem mit dem Parameter visible sichtbare Positionen angegeben werden. Mit dem Parameter visible wird der Maps Static API-Dienst angewiesen, eine Karte so zu erstellen, dass die vorhandenen Standorte sichtbar bleiben. Dieser Parameter kann auch mit vorhandenen Markierungen oder Pfaden kombiniert werden, um einen sichtbaren Bereich zu definieren. Wenn Sie so einen Darstellungsbereich definieren, muss keine genaue Zoomstufe angegeben werden.

Im nächsten Beispiel wird eine Karte angefordert, deren Mittelpunkt Boston, MA, ist und die sowohl das MIT als auch den Harvard Square in Cambridge, MA, 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

Implizite Positionierung 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, können Sie stattdessen die Maps Static API den korrekten Mittelpunkt und die korrekte Zoomstufe basierend auf der Auswertung der Position dieser Elemente implizit bestimmen lassen.

Wenn Sie zwei oder mehr Elemente angeben, ermittelt die Maps Static API den richtigen Mittelpunkt und die richtige Zoomstufe und bietet großzügige Ränder für die enthaltenen Elemente. In diesem Beispiel wird eine Karte von 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

Größere Bilder

Wenn Sie Bilder benötigen, die größer als 640 × 640 Pixel oder 1.280 × 1.280 Pixel mit einem Skalierungswert von 2 sind, wenden Sie sich an das Supportteam und geben Sie die folgenden Informationen an:

1. Ihr Anwendungsfall und warum Sie große Bilder benötigen.
2. Ob Sie andere Google Maps Platform APIs (Maps JavaScript API, Maps Embed API, Maps SDK for Android oder Maps SDK for iOS) verwenden möchten und warum sie nicht Ihren Anforderungen entsprechen.
3. Screenshots, Entwürfe oder Beispiele dafür, wie Sie große Bilder verwenden.
4. Ihre geschätzte monatliche Nutzung für große Bilder.

Wir prüfen Ihre Anfrage anhand der von Ihnen bereitgestellten Informationen und entscheiden, 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 möglicherweise einen Fehler oder eine Warnung aus, wenn ein Problem auftritt. Achten Sie vor allem auf Warnungen, wenn Sie feststellen, dass etwas auf der Karte fehlt. Es empfiehlt sich außerdem, vor dem Start einer neuen Anwendung auf Warnungen zu prüfen. Die Warnungen sind unter Umständen nicht sofort erkennbar, da sie im HTTP-Header erscheinen. Weitere Informationen finden Sie im Leitfaden zu Fehlern und Warnungen.