Jetzt starten

Entwickler im Europäischen Wirtschaftsraum (EWR)

Einführung

Die Maps Static API gibt als Antwort auf eine HTTP-Anfrage über eine URL ein Bild (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 Standorten auf der Karte angeben. Sie können Ihre Markierungen zusätzlich mit alphanumerischen Zeichen beschriften.

Ein Maps Static API-Bild wird in das src-Attribut eines <img>-Tags oder in 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 werden einige Tipps und Tricks zur Angabe von URLs vorgestellt.

Hinweis

Dieses Dokument richtet sich an Website- und Mobilentwickler, die Maps Static API-Bilder in eine Webseite oder mobile Anwendung 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, sollten 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) ansehen.

URL-Parameter

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

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 Sicherheitswarnungen im Browser zu vermeiden. HTTPS wird auch empfohlen, wenn Ihre Anfragen vertrauliche Nutzerinformationen 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 in URLs üblich, werden alle Parameter mit dem Und-Zeichen (&) getrennt. Die Liste der Parameter und ihrer möglichen Werte ist 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 akzeptiert einen Standort entweder als kommagetrenntes Paar aus Breiten- und Längengrad (z.B. „40.714728,-73.998672“) oder als Stringadresse (z.B. „Rathaus, New York, NY“), die einen eindeutigen Standort 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ößerungsstufe der Karte bestimmt. Dieser Parameter akzeptiert 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. Für diesen Parameter wird ein String im Format {horizontal_value}x{vertical_value} verwendet. 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 durch den 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 der Abdeckungsbereich und der Detailgrad gleich bleiben (d.h. der Inhalt der Karte ändert sich nicht). Dies ist nützlich, wenn Sie für Displays mit hoher Auflösung entwickeln. Der Standardwert ist 1. Zulässige Werte sind 1 und 2. Weitere Informationen finden Sie unter Skalierungswerte.
  • format (optional) definiert das Format des resultierenden Bildes. Standardmäßig werden mit der Maps Static API PNG-Bilder erstellt. 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 bieten. 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.
  • colorscheme (optional) definiert das Farbschema für die Karte. Zulässige Werte sind light (Standard) und dark. Das dunkle Farbschema gilt für die Kartentypen roadmap und terrain. Weitere Informationen finden Sie unter Modi und Kartentypen.
  • language (optional) definiert die Sprache, die für die Anzeige von Labels auf Karten-Tiles verwendet werden soll. Dieser Parameter wird nur für einige Länder-Tiles unterstützt. Wenn die angeforderte Sprache für das Tile-Set nicht unterstützt wird, wird die Standardsprache für dieses Tile-Set verwendet.
  • region (optional) definiert die anzuzeigenden Grenzen basierend auf geopolitischen Gegebenheiten. Akzeptiert einen Regionscode, der als zweistelliger ccTLD-Wert („Top-Level-Domain“) angegeben ist. 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, der zum Initialisieren der Karte verwendet wird. Weitere Informationen finden Sie unter Karten-IDs verwenden.
  • markers (optional) definiert eine oder mehrere Markierungen, die an bestimmten Positionen im Bild eingefügt werden sollen. Dieser Parameter verwendet eine einzelne Markierungsdefinition mit Parametern, die durch das Pipe-Zeichen (|) getrennt sind. Im selben markers-Parameter können mehrere Markierungen platziert werden, solange 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 Maps Static API – Markierungen.
  • path (optional) definiert einen einzelnen Pfad aus zwei oder mehr verbundenen Punkten, der an bestimmten Stellen über das Bild gelegt wird. Dieser Parameter akzeptiert einen String mit Punktdefinitionen, die durch das Pipe-Zeichen (|) 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 weitere 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 zu Maps Static API-Pfaden
  • visible (optional) gibt einen oder mehrere Orte an, die auf der Karte sichtbar bleiben sollen, auch wenn keine Markierungen oder anderen Indikatoren angezeigt werden. Mit diesem Parameter können Sie dafür sorgen, dass bestimmte Elemente oder Kartenorte in der Maps Static API angezeigt werden.
  • style (optional) definiert einen benutzerdefinierten Stil, um die Darstellung eines bestimmten Elements (Straßen, Parks und andere Elemente) der Karte zu ändern. Dieser Parameter verwendet die Argumente feature und element, um die zu gestaltenden Elemente zu identifizieren, und eine Reihe von Stilvorgängen, 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 Karten mit benutzerdefinierten Stilen.

Schlüssel- und Signaturparameter

  • Mit key (erforderlich) können Sie die API-Nutzung Ihrer Anwendung in der Google Cloud Console überwachen. Außerdem kann Google Sie bei Bedarf bezüglich Ihrer Anwendung kontaktieren. Weitere Informationen finden Sie unter API-Schlüssel mit der Maps Static API verwenden.
  • signature (empfohlen) ist eine digitale Signatur, mit der überprüft wird, ob eine Website, die Anfragen mit Ihrem API-Schlüssel generiert, dazu berechtigt ist. Anfragen ohne digitale Signatur schlagen möglicherweise fehl. Weitere Informationen finden Sie unter Digitale Signatur verwenden.

Beschränkung der URL-Größe

Maps Static API-URLs sind auf 16.384 Zeichen beschränkt. In der Praxis werden Sie wahrscheinlich keine längeren URLs benötigen, 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 nur 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 auf den richtigen Ort zu fokussieren (mit dem Parameter center) und/oder optionale Ortsmarkierungen (mit dem Parameter markers) an Orten auf der Karte zu platzieren. In der Maps Static API werden diese Standorte durch Zahlen (Breiten- und Längengradwerte) oder Strings (Adressen) angegeben. Diese Werte identifizieren einen geocodierten Standort.

Mehrere Parameter (z. B. die Parameter markers und path) akzeptieren mehrere Standorte. In diesen Fällen werden die Standorte durch das Pipe-Zeichen (|) getrennt.

Breiten- und Längengrade

Breiten- und Längengrade werden mit Zahlen in einem kommagetrennten Textstring mit einer Genauigkeit von 6 Dezimalstellen definiert. „40.714728,-73.998672“ ist beispielsweise ein gültiger Geocode-Wert. Eine Genauigkeit über die 6 Dezimalstellen hinaus wird ignoriert.

Längengrade basieren auf der Entfernung zu Greenwich, England, wo sich der Nullmeridian befindet. Da Greenwich auf dem Breitengrad 51,477222 liegt, können wir einen center-Wert von 51.477222,0 eingeben, um die Karte auf Greenwich zu zentrieren:

Greenwich, England

Breiten- und Längengradwerte müssen einem gültigen Ort auf der Erde entsprechen. Breitengrade können einen beliebigen Wert zwischen -90 und 90 annehmen, während Längengrade einen beliebigen Wert zwischen -180 und 180 annehmen können. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als ungültige Anfrage abgelehnt.

Adressen

Die meisten Menschen verwenden keine Breiten- und Längengrade, sondern Adressen, um Orte zu bezeichnen. Der Prozess, bei dem eine Adresse in einen geografischen Punkt umgewandelt wird, wird als Geocodierung bezeichnet. Der Maps Static API-Dienst kann die Geocodierung für Sie übernehmen, wenn Sie gültige Adressen angeben.

In jedem Parameter, in dem 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- und Längengrad zur Verfügung, der zum Platzieren von Markierungen oder zum Angeben von Standorten verwendet werden kann. Der String sollte URL-codiert sein. Adressen wie „City Hall, New York, NY“ sollten also beispielsweise in „City+Hall,New+York,NY“ umgewandelt werden.

Adressen können genaue Standorte wie Straßenadressen, Polylinien wie benannte Routen oder polygonale Bereiche wie Städte, Länder oder Nationalparks sein. Bei polylinien- und polygonförmigen Ergebnissen verwendet der Maps Static API-Server den Mittelpunkt der Linie/Fläche als Adressmittelpunkt. Wenn Sie sich nicht sicher sind, wie eine Adresse geocodiert wird, können Sie sie mit diesem Geocoding-Dienstprogramm testen.

Im folgenden Beispiel wird ein statisches Kartenbild für Berkeley, Kalifornien, USA, 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 ganzzahlige „Zoomstufe“, die die Auflösung der aktuellen Ansicht definiert. In der Standardansicht roadmap sind Zoomstufen zwischen 0 (die 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, ab Zoomstufe 17 auf der Karte angezeigt. Dieser Wert ist von Gebiet zu Gebiet unterschiedlich und kann sich im Laufe der Zeit ändern, wenn sich die Daten weiterentwickeln.

Von Google Maps wird die Zoomstufe 0 festgelegt, sodass die gesamte Erde in der Ansicht umfasst ist. Mit jeder weiteren 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 Zoomstufen variieren je nach Standort, da die Daten in einigen Teilen der Welt detaillierter sind als in anderen.

Wenn Sie eine Anfrage für eine Zoomstufe senden, für die keine Karten-Tiles 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 zusammen mit center den Abdeckungsbereich einer Karte. Außerdem wird 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 (gibt 1280 × 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

Äquator

In diesem Beispiel wird eine kleine Karte mit einer Größe von 100 × 100 Pixeln 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

Kleine Karte vom Äquator

Skalierungswerte

Mit dem Parameter size der Maps Static API wird die Größe einer Karte in Pixeln definiert. Eine Karte mit size=200x200 wird also mit 200 × 200 Pixeln zurückgegeben. Auf einem LCD-Computermonitor, der normalerweise etwa 100 Pixel pro Zoll (ppi) anzeigt, ist eine 200 × 200-Karte etwa 2 Zoll groß.

Mobilgeräte haben jedoch immer häufiger hochauflösende Bildschirme mit Pixeldichten von über 300 ppi, die entweder:

  • Die Größe eines Bildes mit 200 × 200 Pixeln wird auf nur 0,7 Zoll reduziert, sodass Labels und Symbole zu klein sind, um sie zu lesen.
  • Das Bild wird skaliert (gezoomt), um die Lesbarkeit zu verbessern, was zu einem unscharfen oder verpixelten Bild führt.
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 bestimmen, 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 Kartenbereich zurückgegeben wie bei einer Anfrage ohne Skalierung, aber mit doppelt so vielen Pixeln in jeder Dimension. Dazu gehören Straßen und Labels, damit sie auf kleinen Bildschirmen mit hoher Auflösung und bei der Skalierung durch den Browser lesbar sind.

150x150 150x150&scale=2

Ein solches Bild wird auch in Desktop-Browsern gut dargestellt, 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.

In dieser Tabelle sind drei verschiedene Bildanfragen aufgeführt.

  • Die erste ist für ein Bild mit der Größe 100 x 100 und ohne Angabe eines "scale"-Werts. Sie wird auf dem Computer richtig angezeigt, ist aber auf einem Mobilgerät zu klein, um sie zu lesen.
  • In der zweiten wird die Kartengröße verdoppelt. Auf dem Computer wird die Karte durch das CSS-Element in das angegebene 100 × 100-img-Element eingepasst. Durch die Verkleinerung des Bildes werden Straßen und Labels jedoch 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 100 × 100-Karte mit scale=2. Das Bild wird mit 200 Pixeln Detail zurückgegeben. Der Desktop skaliert es perfekt herunter, sodass es nicht von der ursprünglichen 100 × 100-Anfrage zu unterscheiden ist, während der mobile Browser von der zusätzlichen Auflösung profitiert, die von der API zurückgegeben wird.
Bildanfragen
Gerät 100x100 200x200 100x100&scale=2
Desktop
(mit height="100px" und
width="100px" im
img-Tag)
Hohe Auflösung
(simuliert)

Weitere Informationen zur Entwicklung für Mobilgeräte und hochauflösende Displays finden Sie in den folgenden Artikeln:

Bildformate

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

  • png8 oder png (Standard) 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, allerdings durch eine „verlustbehaftete“ Komprimierung, die die Bildqualität beeinträchtigen kann. gif, png8 und png32 bieten verlustfreie Komprimierung.

Die meisten JPEG-Bilder sind progressiv. Das bedeutet, dass sie zuerst ein gröberes Bild laden und die Bildauflösung verfeinern, wenn mehr Daten eintreffen. So können Bilder auf Webseiten schnell geladen werden. Dies ist derzeit die am weitesten verbreitete Verwendung von JPEG. Für einige Verwendungszwecke von JPEG sind jedoch nicht progressive (Baseline-)Bilder erforderlich. In solchen Fällen können Sie das nicht progressive jpg-baseline-Format verwenden.

Kartentypen

Die Maps Static API erstellt Karten in verschiedenen Formaten, die unten aufgeführt sind:

  • 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 physisches Reliefkartenbild an, das Gelände und Vegetation zeigt.
  • hybrid gibt eine Hybridansicht aus Satelliten- und Straßenbild an, bei der eine transparente Ebene mit wichtigen Straßen und Ortsnamen über dem Satellitenbild angezeigt wird.

In diesem Codebeispiel sehen Sie den Unterschied zwischen den Kartentypen „roadmap“ und „terrain“.

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)

Hybridkarten verwenden Satellitenbilder und wichtige Elemente von Straßenkarten, um eine kombinierte Karte zu erstellen. Die folgenden Beispiele zeigen die Kartentypen „Satellit“ und „Hybrid“:

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

Sie können die Darstellung der Standardkarte von Google anpassen, indem Sie eigene Stile anwenden. Weitere Informationen finden Sie im Leitfaden zu Karten mit benutzerdefinierten Stilen.

Markierungen

Mit dem Parameter markers wird eine Gruppe von einer oder mehreren Markierungen (Pins) für eine Gruppe von Orten definiert. Alle Markierungen, die in einer einzelnen markers-Deklaration definiert sind, müssen denselben visuellen Stil haben. Wenn Sie Markierungen mit unterschiedlichen Stilen anzeigen möchten, müssen Sie mehrere markers-Parameter mit separaten Stilinformationen angeben.

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

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

Die Gruppe von markerStyles wird am Anfang der markers-Deklaration deklariert und besteht aus null oder mehr Stildeskriptoren, die durch das Pipe-Zeichen (|) getrennt sind, gefolgt von einer Gruppe von einem oder mehreren Standorten, die ebenfalls durch das Pipe-Zeichen (|) getrennt sind.

Da sowohl Stil- als auch Standortinformationen durch das Pipe-Zeichen getrennt werden, müssen Stilinformationen in jedem Markierungsdeskriptor zuerst angegeben werden. Sobald der Maps Static API-Server einen Ort im Markierungsdeskriptor findet, wird davon ausgegangen, dass alle anderen Markierungsparameter ebenfalls Orte sind.

Markierungsstile

Die Markierungsstil-Deskriptoren sind eine Reihe von Wertzuweisungen, die durch das Pipe-Zeichen (|) getrennt sind. Dieser Stildeskriptor definiert die visuellen Attribute, die beim Anzeigen der Markierungen innerhalb dieses Markierungsdeskriptors verwendet werden sollen. Diese Stildeskriptoren 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 (Beispiel: 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-Hex-Farbwerten) werden in Markierungen nicht unterstützt, sind aber für Pfade zulässig.

  • label: (optional) gibt ein einzelnes alphanumerisches Großbuchstabenzeichen aus dem Satz {A-Z, 0-9} an. (Die Anforderung für Großbuchstaben ist neu in dieser Version der API.) Hinweis: Nur Markierungen mit der Standardgröße und der Größe mid können einen alphanumeric-character-Parameter anzeigen. Die Markierungen tiny und small können keine alphanumerischen Zeichen anzeigen.

Skalierung 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 der Skalierung auf weniger als 4.096 Pixel reduziert wird. Verwenden Sie die Markierungsskalierung in Verbindung mit der Kartenskalierung, wenn Sie Karten mit höherer Auflösung anzeigen.

Positionen der Markierungen

Jeder Markierungsdeskriptor muss einen Satz von einem oder mehreren Orten enthalten, die definieren, wo die Markierung auf der Karte platziert werden soll. Diese Orte können entweder als Breiten-/Längengrad oder als Adressen angegeben werden. Diese Orte werden durch einen senkrechten Strich (|) getrennt.

Hinweis: Wenn Sie die Markierungsstandorte mit einer Methode angeben, für die Geocodierung erforderlich ist, z. B. menschenlesbare Adressstrings oder Polylinien, ist die Anfrage auf maximal 15 Markierungen beschränkt. Dieses Limit gilt nur für Markierungsstandorte, die geocodiert werden müssen. Sie gilt nicht für Markierungsstandorte, die mit Breiten- und Längengradkoordinaten angegeben sind.

Die Positionsparameter definieren die Markierungsposition auf der Karte. Wenn sich der Standort außerhalb 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 sind, erstellt der Maps Static API-Server automatisch ein Bild, das die angegebenen Markierungen enthält. (siehe Implizite Positionierung)

Hier sehen Sie ein Beispiel für eine Markierungsdeklaration. Beachten Sie, dass wir einen Satz von Stilen und drei Standorte 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

Brooklyn, drei Postleitzahlenbereiche

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 der Bezeichnung „S“ bei 62.107733, -145.5419, eine kleine grüne Markierung bei „Delta Junction, AK“ und eine mittelgroße gelbe Markierung mit der Bezeichnung „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 auch eigene benutzerdefinierte Symbole verwenden. Benutzerdefinierte Symbole werden mit dem Deskriptor icon im Parameter markers angegeben. Beispiel:

markers=icon:URLofIcon|markerLocation

Geben Sie die icon mithilfe einer URL an, die URL-codiert sein sollte. Sie können URLs verwenden, die von URL-Kürzungsdiensten wie https://goo.gl erstellt wurden. Die meisten URL-Kürzungsdienste haben 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 im Verhältnis zu den angegebenen markers-Standorten platziert wird. Standardmäßig ist der Ankerpunkt eines benutzerdefinierten Symbols die untere Mitte des Symbolbilds. Sie können einen anderen Ankerpunkt angeben, indem Sie den Deskriptor anchor in Verbindung mit icon verwenden. Legen Sie den anchor als x,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 pro Anfrage bis zu fünf verschiedene benutzerdefinierte Symbole verwenden. Diese Einschränkung bedeutet nicht, dass Sie nur 5 markierte Orte auf Ihrer Karte haben können. Jedes eindeutige Symbol kann für mehr als einen markers-Standort auf Ihrer Karte verwendet werden.

Symbolformat:

  • Symbolbilder können im PNG-, JPEG- oder GIF-Format vorliegen, wobei PNG empfohlen wird.
  • 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 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, verschiedene benutzerdefinierte Symbole mit Ankern.

In Beispiel 2 werden dieselben benutzerdefinierten Symbole wie in Beispiel 1 erstellt. Die Symbolpositionen werden jedoch nicht mithilfe von Ankern festgelegt, sondern es wird der Standardanker „unten mittig“ verwendet.

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, verschiedene benutzerdefinierte Symbole mit Standardpositionierung.

Maps Static API-Pfade

Mit dem Parameter path wird eine Gruppe von einem oder mehreren Orten definiert, die durch einen Pfad verbunden sind, der auf dem Kartenbild eingeblendet wird. Der Parameter path akzeptiert eine Reihe von Wertzuweisungen (Pfaddeskriptoren) im folgenden Format:

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

Beachten Sie, dass die beiden Pfadpunkte durch das Pipe-Zeichen (|) voneinander getrennt sind. Da sowohl Stil- als auch Punktinformationen durch das Pipe-Zeichen getrennt werden, müssen Stilinformationen in jedem Pfaddeskriptor zuerst angegeben werden. Sobald der Maps Static API-Server einen Ort im Pfaddeskriptor findet, werden alle anderen Pfadparameter ebenfalls als Orte interpretiert.

Pfadstile

Die Gruppe von Pfaddeskriptoren ist eine Reihe von Wertzuweisungen, die durch das Pipe-Zeichen (|) getrennt sind. Dieser Stildeskriptor definiert die visuellen Attribute, die beim Anzeigen des Pfads verwendet werden sollen. Diese Stil-Deskriptoren 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 in der Standardstärke (5 Pixel) angezeigt.

  • color: (optional) gibt eine Farbe entweder als 24-Bit-Hexadezimalwert (Beispiel: color=0xFFFFCC) oder als 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-Hex-Wert angegeben wird, geben die letzten beiden Zeichen den 8-Bit-Alpha-Transparenzwert an. Dieser Wert variiert zwischen 00 (vollständig transparent) und FF (vollständig deckend). Transparenzen werden in Pfaden unterstützt, jedoch nicht für Markierungen.

  • fillcolor: (optional) gibt an, dass der Pfad einen polygonalen Bereich markiert, und legt die Füllfarbe fest, die als Overlay innerhalb dieses Bereichs verwendet werden soll. Die folgenden Orte müssen keine „geschlossene“ Schleife bilden. Der Maps Static API-Server verbindet den ersten und den letzten Punkt automatisch. Beachten Sie jedoch, dass ein Strich am Rand des gefüllten Bereichs nur dann geschlossen wird, wenn Sie ausdrücklich denselben Start- und Endpunkt angeben.
  • geodesic: (optional) gibt an, dass der angeforderte Pfad als geodätische Linie interpretiert werden soll, die der Erdkrümmung folgt. Wenn „false“, wird der Pfad als gerade Linie im Bildschirmbereich gerendert. Die Standardeinstellung ist "false".

Beispiele für Pfaddefinitionen:

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

Diese Pfadformate sind optional. Wenn Standardattribute gewünscht sind, können Sie die Definition der Pfadattribute überspringen. In diesem Fall besteht das erste „Argument“ des Pfaddeskriptors stattdessen aus dem ersten deklarierten Punkt (Ort).

Pfadpunkte

Damit ein Pfad gezeichnet werden kann, müssen dem Parameter path 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 durch das Zeichen | (senkrechter Strich) getrennt angegeben.

Im folgenden Beispiel wird ein blauer Pfad mit einer Standarddeckkraft von 50% vom Union Square, NY, zum Times Square, NY, definiert.

Pfad vom Union Square zum Times Square

Der Parameter path hat folgende Eigenschaften:

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 definiert, aber mit einer durchgehenden roten Linie mit 100% Deckkraft:

Pfad vom Union Square zum Times Square

Die Besonderheiten 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 polygonales Gebiet in Manhattan definiert, wobei eine Reihe von Kreuzungen als Standorte übergeben werden:

Pfad vom Union Square zum Times Square

Die Besonderheiten dieses path-Parameters sind:

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 der Pfad selbst unsichtbar ist und der polygonale Bereich eine Deckkraft von 15% hat.

Codierte Polylinien

Anstatt eine Reihe von Orten anzugeben, können Sie einen Pfad auch als codierte Polylinie deklarieren. Verwenden Sie dazu das Präfix enc: in der Ortsdeklaration von path.

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 ein fillcolor-Argument an den Parameter path ü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 für Brooklyn mit Signatur

Darstellungsbereiche

Für Bilder kann ein Darstellungsbereich angegeben werden. Dazu werden sichtbare Orte mit dem Parameter visible angegeben. Der Parameter visible weist den Maps Static API-Dienst an, eine Karte so zu erstellen, dass die vorhandenen Orte sichtbar bleiben. (Dieser Parameter kann auch mit vorhandenen Markierungen oder Pfaden kombiniert werden, um einen sichtbaren Bereich zu definieren.) Wenn Sie einen Darstellungsbereich auf diese Weise definieren, müssen Sie keine genaue Zoomstufe angeben.

Im nächsten Beispiel wird eine Karte mit dem Mittelpunkt Boston, Massachusetts, USA angefordert, die sowohl das MIT als auch den Harvard Square in Cambridge, Massachusetts, USA 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

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, kann die Maps Static API den richtigen Mittelpunkt und die richtige Zoomstufe implizit anhand der Position dieser Elemente bestimmen.

Wenn Sie zwei oder mehr Elemente angeben, ermittelt die Maps Static API einen geeigneten Mittelpunkt und eine geeignete Zoomstufe, wobei großzügige Abstände für die enthaltenen Elemente vorgesehen werden. In diesem Beispiel wird eine Karte mit San Francisco, Oakland und San Jose, Kalifornien, 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 Bilder

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 geben Sie die folgenden Informationen an:

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

Wir prüfen Ihre Anfrage anhand der von Ihnen angegebenen Informationen und stellen fest, ob Ihr Anwendungsfall den Nutzungsbedingungen der Google Maps Platform entspricht.

Die maximale Größe, die wir bereitstellen können, beträgt 2048 × 2048 Pixel.

Fehlerbehebung und Support

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

Die Maps Static API kann einen Fehler oder eine Warnung ausgeben, wenn ein Problem auftritt. Sie sollten insbesondere dann nach Warnungen suchen, wenn Sie feststellen, dass etwas auf der Karte 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.