Google Static Maps – Entwickler-Leitfaden

Mit Google Static Maps API können Sie ein Google Maps-Bild in Ihre Webseite einbetten, ohne dass dafür JavaScript oder ein dynamischer Seitenladevorgang erforderlich ist. Mit dem Google Static Maps API-Dienst wird Ihre Karte auf Basis von URL-Parametern erstellt, die über eine Standard-HTTP-Anforderung gesendet werden. Die Karte wird vom Dienst als Bild zurückgegeben, das Sie auf der Webseite anzeigen können.

Hinweis: Die Nutzungsbeschränkungen für Google Static Maps API wurden geändert. Sie können einen API-Schlüssel erstellen und diesen in Ihre Anforderung einbinden, um die Nutzung in Google API Console zu verfolgen und ggf. zusätzliche Kontingente zu erwerben.

In diesem Dokument wird Google Static Maps API v2 ausführlich beschrieben. Informationen zum Update der URLs für v1 finden Sie im Leitfaden zum Upgrade.

Kurzbeispiel

Das folgende Beispiel enthält die URL eines Google Static Maps API-Bilds von Downtown New York City, das unten angezeigt wird:

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

Damit dieses Bild auf der Seite angezeigt wird, sind keine „speziellen“ Schritte erforderlich. JavaScript wird nicht benötigt. Nur die URL muss erstellt und zwischen Tags des Typs <img> platziert werden. Sie können Google Google Static Maps API überall dort auf Ihrer Webseite positionieren, wo Sie ein Bild platzieren können.

Zielgruppe

Dieses Dokument richtet sich an Entwickler von Websites und mobilen Anwendungen, die Google Static Maps API-Bilder in eine Webseite oder mobile Anwendung einbinden möchten. Es enthält eine Einführung zur Verwendung der API und Informationen zu den verfügbaren Parametern.

Übersicht

Als Antwort auf eine HTTP-Anforderung per URL gibt Google Static Maps API ein Bild zurück (im Format GIF, PNG oder JPEG). Für jede Anforderung können der Standort der Karte, die Bildgröße, die Vergrößerungsstufe, der Kartentyp und die Platzierung optionaler Marker an Positionen auf der Karte angegeben werden. Zudem lässt sich für die Marker eine Beschreibung mit alphanumerischen Zeichen eingeben.

Ein Google Static Maps API-Bild ist in das Attribut src des Tags <img> (oder dessen Entsprechung in anderen Programmiersprachen) eingebettet. Soll ein Google Static Maps API-Bild außerhalb einer webbasierten Anwendung (z. B. einem Browser) verwendet werden, muss ein Link eingebunden werden, der auf den angezeigten Standort in einem Webbrowser oder in einer nativen Google Maps-Anwendung verweist. (Google Maps APIs Premium Plan-Nutzer sind von dieser Vorgabe ausgenommen.) Den vollständigen und aktuellen Text dieser Vorgabe finden Sie in den Nutzungsbedingungen von Google Maps/Google Earth im Abschnitt 10.1.1(h).

In diesem Dokument werden das benötigte Format der URLs für Google Static Maps API und die verfügbaren Parameter beschrieben. Zudem finden Sie einige Tipps und Tricks für die Angabe der URLs.

URL-Parameter

Eine URL für Google Static Maps API muss das folgende Format aufweisen:

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

Wenn Ihre Website über HTTPS aufgerufen wird, müssen auch die Google Static Maps API-Bilder über HTTPS geladen werden. Ansonsten gibt der Browser Sicherheitswarnungen aus. HTTPS wird auch empfohlen, wenn Ihre Anforderungen vertrauliche Nutzerdaten enthalten (wie z. B. den Standort des Nutzers):

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

Sowohl bei HTTP als auch bei HTTPS sind bestimmte URL-Parameter erforderlich, andere hingegen sind optional. Standardmäßig werden alle Parameter in URLs durch ein kaufmännisches Und (&) getrennt. Die Liste der Parameter und deren mögliche Werte sind unten aufgeführt.

Wichtig: In der nachstehenden Erläuterung der URL-Parameter werden in den Beispielen keine Escape-Zeichen verwendet, um eine bessere Übersichtlichkeit zu gewährleisten. Bevor eine Anforderung an die API gesendet wird, sollte eine ordnungsgemäße URL-Kodierung der Parameter erfolgen. Beispielsweise wird bei vielen Parametern der senkrechte Strich (|) als Trennzeichen verwendet. Dieser wird in der endgültigen URL als %7C kodiert, wie im Kurzbeispiel weiter oben in diesem Dokument angegeben. Weitere Informationen finden Sie unter Gültige URL erstellen.

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

Standortparameter

• center (erforderlich, falls keine Marker vorhanden sind) definiert den Mittelpunkt der Karte, abstandsgetreu zu allen Kartenrändern. In diesem Parameter wird der Standort als durch Komma getrennte Längengrad- und Breitengradangaben {latitude,longitude} (z. B. „40.714728,-73.998672“) oder als Adresse in Form einer Zeichenfolge verwendet, die einen eindeutigen Standort auf der Erde angibt (z. B. „city hall, new york, ny“). Weitere Informationen finden Sie weiter unten unter Standorte.
• zoom (erforderlich, falls keine Marker vorhanden sind) definiert die Vergrößerungsstufe einer Karte. In diesem Parameter wird ein numerischer Wert verwendet, der der Vergrößerungsstufe der gewünschten Region entspricht. Weitere Informationen finden Sie weiter unten unter Vergrößerungsstufen.

Kartenparameter

• size (erforderlich) definiert die rechteckigen Abmessungen des Kartenbilds. In diesem Parameter wird eine Zeichenfolge im Format {horizontal_value}x{vertical_value} verwendet. Beispielsweise definiert die Angabe 500x400 eine Karte mit 500 Pixel Breite und 400 Pixel Höhe. Auf Karten mit einer Breite von weniger als 180 Pixel wird ein kleineres Google-Logo abgebildet. Dieser Parameter hängt eng mit dem unten beschriebenen Parameter scale zusammen. Die endgültige Ausgabegröße ist das Ergebnis der Größen- und Skalierungswerte.
• scale (optional) bezieht sich auf die Anzahl der zurückgegebenen Pixel. Bei scale=2 werden doppelt so viele Pixel zurückgegeben wie bei scale=1, dabei bleiben der Abdeckungsbereich und die Detailstufe erhalten (das heißt, der Inhalt der Karte bleibt unverändert). Das ist sinnvoll bei der Entwicklung für hochauflösende Displays oder bei der Erzeugung von Karten zum Drucken. Der Standardwert ist 1. Zulässige Werte sind 2 und 4 (4 steht nur für Google Maps APIs Premium Plan-Kunden zur Verfügung.) Weitere Informationen finden Sie unter Skalierungswerte.
• format (optional) definiert das Format des ausgegebenen Bilds. Standardmäßig werden von Google Static Maps API Bilder im PNG-Format erzeugt. Es sind jedoch unterschiedliche Formate möglich, 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 höhere 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 weiter unten unter Kartentypen für Google Static Maps API.
• language (optional) definiert die Sprache, in der Bezeichnungen auf Kacheln mit Karten angezeigt werden sollen. Beachten Sie, dass dieser Parameter nur für einige Länderkacheln unterstützt wird. Falls keine Unterstützung der angegebenen Sprache für diesen Kachelsatz vorhanden ist, wird die Standardsprache für diesen Kachelsatz verwendet.
• region (optional) definiert auf Basis von geopolitischen Aspekten die jeweils anzuzeigenden Grenzen. Für den Parameter ist ein Regionscode aus zwei Zeichen [ccTLD] (Top-Level-Domain) zulässig.

Merkmalsparameter

• markers (optional) definiert einen oder mehrere Marker, die auf dem Bild an bestimmten Standorten hinzugefügt werden. In diesem Parameter wird eine einzelne Marker-Definition verwendet, wobei die Parameter durch einen senkrechten Strich (|) getrennt werden. Mehrere Marker können innerhalb desselben Parameters vom Typ markers platziert werden, sofern sie dasselbe Format verwenden. Sie können zusätzliche Marker mit anderem Format angeben, indem Sie weitere Parameter des Typs markers hinzufügen. Wenn Sie Marker für eine Karte angeben, ist es in diesem Fall nicht nötig, die (normalerweise erforderlichen) Parameter center und zoom zu spezifizieren. Weitere Informationen finden Sie weiter unten unter Marker für Google Static Maps API.
• path (optional) definiert einen einzelnen Pfad zwischen zwei oder mehr verbundenen Punkten und wird auf dem Bild an bestimmten Standorten als Overlay angezeigt. In diesem Parameter wird eine Zeichenfolge aus Punktdefinitionen verwendet, die durch einen senkrechten Strich (|) getrennt werden. Sie können zusätzliche Pfade bereitstellen, indem Sie weitere Parameter des Typs path hinzufügen. Wenn Sie einen Pfad für eine Karte angeben, ist es in diesem Fall nicht nötig, die (normalerweise erforderlichen) Parameter center und zoom zu spezifizieren. Weitere Informationen finden Sie weiter unten unter Pfade für Google Static Maps API.
• visible (optional) gibt einen oder mehrere Standorte an, die auf der Karte sichtbar bleiben sollen, obwohl weder Marker noch andere Kennzeichen angezeigt werden. Mit diesem Parameter können Sie sicherstellen, dass bestimmte Merkmale oder Kartenstandorte in Google Static Maps API abgebildet werden.
• style (optional) definiert ein benutzerdefiniertes Format für eine alternative Darstellung eines bestimmten Merkmals (Straßen, Parks und weitere Merkmale) auf der Karte. In diesem Parameter werden die Argumente feature und element verwendet, um die zu formatierenden Merkmale zu ermitteln und die Aktionen festzulegen, die für die gewählten Merkmale möglich sind. Sie können mehrere Formate angeben, indem Sie weitere Parameter des Typs style hinzufügen. Weitere Informationen finden Sie unter Formatierte Karten.

Schlüssel- und Signaturparameter

• key (erforderlich) ermöglicht Ihnen die Überwachung der Nutzung der API Ihrer Anwendung in der Google API Console und den Zugriff auf ein großzügiges kostenloses Tageskontingent. Weiterhin kann Google Sie ggf. bezüglich Ihrer Anwendung kontaktieren. Weitere Informationen finden Sie unter Schlüssel und Signatur anfordern.
• signature (empfohlen) ist eine digitale Signatur, mit der sichergestellt wird, dass jede Website, die Anforderungen mithilfe Ihres API-Schlüssels generiert, dazu auch autorisiert ist. Hinweis: Wenn Sie die Abrechnung aktivieren, ist die digitale Signatur erforderlich. Beim Überschreiten der Obergrenze der kostenlos pro Tag herunterladbaren Karten werden weitere bis zum Tagesende heruntergeladene Karten berechnet. Zu berechnende Kartenladevorgänge ohne digitale Signatur schlagen fehl. Weitere Informationen finden Sie unter Schlüssel und Signatur anfordern.

Hinweis: Google Maps APIs Premium Plan-Kunden können entweder einen API-Schlüssel und eine digitale Signatur oder eine gültige Client-ID und eine digitale Signatur in Ihren Static Maps-Anforderungen verwenden. Lesen Sie weitere Informationen zu Authentifizierungsparametern für Premium Plan-Kunden.

Kunden mit einer früheren Google Maps APIs for Work-Lizenz müssen Ihren Anforderungen anstelle eines key gültige Parameter client und signature hinzufügen. Weitere Informationen finden Sie im Abschnitt zu Client-IDs und Signaturen der Seite „Schlüssel und Signatur anfordern“.

URL-Größeneinschränkung

URLs der Google Static Maps API dürfen maximal 8192 Zeichen umfassen. In der Praxis besteht vermutlich kein Bedarf an längeren URLs, außer ggf. bei der Erstellung von komplexen Karten mit einer hohen Anzahl an Markern und Pfaden. Beachten Sie jedoch, dass für bestimmte Zeichen eine URL-Kodierung durch den Browser und/oder den Dienst erforderlich ist, bevor die URL an die API gesendet werden kann. Dafür werden weitere Zeichen benötigt. Weitere Informationen finden Sie unter Gültige URL erstellen.

Parameterverwendung

Die Verwendung von Google Static Maps API ist recht einfach, da hier nur eine parametrisierte URL vorliegt. Im folgenden Abschnitt wird erläutert, wie Sie anhand dieser Parameter Ihre URLs erstellen.

Standorte angeben

Standorte auf der Karte müssen von Google Static Maps API präzise lokalisiert werden können, damit die Karte auf den korrekten Standort fokussiert werden kann (mithilfe des Parameters center) und/oder damit optionale Ortsmarken (mithilfe des Parameters markers) an Orten auf der Karte platziert werden können. Zur Angabe dieser Standorte werden von Google Static Maps API Zahlen (Längengrad- und Breitengradangaben) oder Zeichenfolgen (Adressen) verwendet. Anhand dieser Werte wird ein geocodierter Standort identifiziert.

Einige Parameter (wie die Parameter markers und path) können mehrere Standorte angeben. In diesen Fällen werden die Standorte durch einen senkrechten Strich (|) getrennt.

Längengrad- und Breitengradangaben

Längengrad- und Breitengradangaben werden anhand von Zahlen mit bis zu sechs Nachkommastellen in einer durch Komma getrennten Zeichenfolge definiert. Beispielsweise ist „40.714728,-73.998672“ ein zulässiger Geocode-Wert. Weitere, über sechs hinausgehende Nachkommastellen werden ignoriert.

Die Werte für den Längengrad basieren auf der Entfernung zu Greenwich, England, Zentrum des Nullmeridians. Da Greenwich den Breitengradwert 51.477222 aufweist, kann für den Parameter center der Wert 51.477222,0 eingegeben werden, um die Karte auf Greenwich zu zentrieren:

Die Längengrad- und Breitengradangaben müssen einem vorhandenen Standort auf der Erde entsprechen. Für den Breitengrad sind Werte zwischen -90 und 90 zulässig, für den Längengrad können Werte zwischen -180 und 180 angegeben werden. Falls Sie einen unzulässigen Wert für den Längengrad oder den Breitengrad eingeben, wird Ihre Anforderung als fehlerhaft zurückgewiesen.

Adressen

Die meisten Menschen sprechen nicht von Längengrad- und Breitengradangaben, sondern geben Standorte anhand von Adressen an. Der Prozess, mit dem eine Adresse in einen geografischen Punkt konvertiert wird, wird als Geocoding bezeichnet. Wenn Sie gültige Adressen angeben, kann der Google Static Maps API-Dienst das Geocoding für Sie ausführen.

Für jeden Parameter, bei dem Sie Längengrad und Breitengrad angeben, können Sie stattdessen auch eine Zeichenfolge als Adresse bereitstellen. Mit Google wird das Geocoding für die Adresse ausgeführt, dann werden Längengrad- und Breitengradangaben zur Marker-Platzierung oder Standortbestimmung an den Google Static Maps API-Dienst übergeben. Die Zeichenfolge sollte mit einem URL-Escape-Zeichen versehen werden, damit eine Adresse wie „City Hall, New York, NY“ in „City+Hall,New+York,NY“ konvertiert wird.

Beachten Sie, dass Adressen entweder präzise Standorte (wie Straßenangaben), Polylinien (wie Routenbenennungen) oder polygonale Gebiete (wie Städte, Länder oder Nationalparks) umfassen können. Bei polylinearen und polygonalen Ergebnissen nutzt der Google Static Maps API-Server den Mittelpunkt der Linie/des Gebiets als Adressmittelpunkt. Wenn Sie unsicher sind, wie Sie das Geocoding einer Adresse erfolgt, können Sie die Adresse mit diesem Geocoding-Tool testen.

Im folgenden Beispiel wird Google Static Maps API für den Ort „Berkeley, CA“ generiert:

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

Vergrößerungsstufen

Karten von Google Maps verfügen über eine integrierte „Vergrößerungsstufe“, mit der die Auflösung der aktuellen Darstellung definiert wird. Vergrößerungsstufen zwischen 0 (niedrigste Vergrößerungsstufe, mit der die ganze Welt auf einer Karte angezeigt werden kann) und 21+ (bis zu Straßen und einzelnen Gebäuden) sind in der Standardansicht roadmap möglich. Gebäudekonturen werden (sofern vorhanden) bei einer Vergrößerungsstufe von etwa 17 auf der Karte dargestellt. Dieser Wert ist von Gebiet zu Gebiet unterschiedlich und kann sich im Verlauf der Zeit mit zunehmenden Daten ändern.

In Google Maps ist eine Vergrößerungsstufe von 0 festgelegt, um die ganze Welt zu umfassen. Mit jeder nachfolgenden Vergrößerungsstufe wird die Präzision auf sowohl horizontaler als auch auf vertikaler Ebene verdoppelt. Weitere Informationen darüber finden Sie in der Dokumentation für Google Maps JavaScript API.

Hinweis: Nicht alle Vergrößerungsstufen sind für alle Standorte weltweit verfügbar. Die Vergrößerungsstufen können sich je nach Standort unterscheiden, da für einige Teile der Welt die Daten granularer sind als für andere.

Wenn Sie eine Anforderung für eine Vergrößerungsstufe senden, für die keine Karten mit Kacheln verfügbar sind, wird von Google Static Maps API eine Karte mit der maximalen Vergrößerungsstufe dieses Standorts übermittelt.

Die folgende Liste enthält die ungefähre Detailebene, von der Sie erwarten können, dass sie auf der jeweiligen Vergrößerungsstufe angezeigt wird:

• 1: Welt
• 5: Landmasse/Kontinent
• 10: Stadt
• 15: Straßen
• 20: Gebäude

Im nachfolgenden Beispiel werden zwei Karten von Manhattan mit gleichem Wert für center, aber unterschiedlichen Vergrößerungsstufen von 12 bzw. 14 angefordert:

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

  

Bildgrößen

Mithilfe des Parameters size wird – zusammen mit dem Parameter center – der Abdeckungsbereich einer Karte definiert. Über ihn wird zudem durch Multiplikation mit dem Wert scale (der standardmäßig 1 ist) die Ausgabegröße der Karte in Pixel festgelegt.

In der nachfolgenden Tabelle werden die maximal zulässigen Werte des Parameters size für die jeweiligen Werte von scale angegeben.

API	scale=1	scale=2	scale=4
Kostenfrei	640x640	640x640 (gibt 1280x1280 Pixel zurück)	Nicht verfügbar.
Google Maps APIs Premium Plan	2048x2048	1024x1024 (gibt 2048x2048 Pixel zurück)	512x512 (gibt 2048x2048 Pixel zurück)

Im nachfolgenden Beispiel wird eine „Scheibe“ der Erde am Äquator mit der Vergrößerungsstufe 1 angefordert:

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

Im nachfolgenden Beispiel wird eine kleine Karte mit 100x100 Pixel von derselben Region angefordert. Beachten Sie das kleinere Google-Logo:

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

Skalierungswerte

Mit dem Parameter size von Google Static Maps API wird die Größe einer Karte in Pixel definiert. Das heißt, eine Karte mit size=200x200 wird mit 200 Pixel mal 200 Pixel zurückgegeben. Auf einem LCD-Computermonitor, auf dem normalerweise etwa 100 Pixel pro Zoll (ppi) angezeigt werden, hat eine Karte mit 200x200 eine Größe von schätzungsweise 2 Zoll pro Richtung.

Mobile Geräte verfügen jedoch zunehmend über Displays mit hoher Auflösung und einer Pixeldichte von über 300 ppi, was zu einem der beiden folgenden Ergebnisse führt:

• Die Größe eines Bilds mit 200x200 Pixel wird auf 0,7 Zoll verkleinert, die Bezeichnungen und Symbole sind zu klein und nicht mehr lesbar.
• Das Bild wird skaliert (vergrößert), um die Lesbarkeit zu verbessern. Dadurch wird das Bild unscharf oder verpixelt.

Zu klein	Zu unscharf

Bei der Entwicklung für mobile Geräte sollten Sie den Parameter scale der API nutzen, um Kartenbilder mit höherer Auflösung zurückzugeben und so die oben beschriebenen Probleme zu beheben. Der Wert scale wird mit size multipliziert, um die tatsächliche Ausgabegröße des Bilds in Pixel zu ermitteln, ohne den Abdeckungsbereich der Karte zu verändern. (Der Standardwert für scale ist 1; zulässige Werte sind 1, 2 und (nur für Google Maps APIs Premium Plan-Kunden) 4.)

Beispiel: Bei einem Skalierungswert von 2 wird derselbe Kartenabdeckungsbereich zurückgegeben wie bei einer Anforderung ohne angegebene Skalierung, aber mit einer doppelt so hohen Pixelanzahl pro Richtung. Das gilt auch für Straßen und Bezeichnungen, sodass diese bei hoher Auflösung, bei kleinen Displays und bei browserseitiger Skalierung gut lesbar sind.

150x150	150x150&scale=2

Ein solches Bild wird auch über Desktop-Browser gut dargestellt, sofern es zwischen Tags des Typs img oder div eingefügt ist und Höhe sowie Breite mithilfe von CSS festgelegt sind. Im Browser wird das Bild ohne Qualitätsverlust auf die richtige Größe verkleinert.

In der nachstehenden Tabelle werden drei unterschiedliche Bildanforderungen abgebildet.

• Die erste ist für ein Bild mit 100x100 ohne angegebenen Skalierungswert. Das Bild wird auf dem Desktop gut dargestellt, auf einem mobilen Gerät ist die Darstellung jedoch zu klein und nicht mehr lesbar.
• Bei der zweiten Bildanforderung wird die Kartengröße verdoppelt. Auf dem Desktop passt das CSS in das angegebene 100x100 img-Element, aber bei der Bildverkleinerung werden Straßen und Bezeichnungen zu klein. Auf dem mobilen Gerät hat das Bild die richtige Größer, aber auch hier sind Straßen und Bezeichnungen nicht mehr lesbar.
• Die dritte Bildanforderung ist für eine Karte mit 100 x 100 und scale=2. Das Bild wird mit 200 Pixel im Detail zurückgegeben und auf dem Desktop optimal herunterskaliert, sodass es von der ursprünglichen Anforderung mit 100 x 100 nicht mehr zu unterscheiden ist. Der mobile Browser nutzt dagegen die höhere Auflösung, die von der API zurückgegeben wird.

Gerät	100x100	200x200	100x100&scale=2
Desktop (mit height="100px" und width="100px" im Tag img)
Hohe Auflösung (simuliert)

Tipp: Auf mobilen Plattformen wie Android und iOS werden Displays mit hoher Auflösung von Apps unterstützt. Dazu wird für jede Auflösung ein eigenes Bild definiert. Mit dem Skalierungsparameter ist es einfach, ein Kartenbild für eine standardmäßige Bildschirmauflösung oder eine geeignete Karte für ein Display mit hoher Auflösung anzufordern: Legen Sie einfach scale=1 bzw. scale=2 fest.

Für weitere Informationen über das Entwickeln für mobile Geräte und Displays mit hoher Auflösung wird Folgendes empfohlen:

• Supporting Multiple Screens in der Android-Entwicklerdokumentation.
• Empfehlungen von Webkit.org zur Entwicklung von High DPI Web Sites.
• Supporting High-Resolution Screens in der iOS-Entwicklerbibliothek.

Bildformate

Bilder können in verschiedenen gängigen Web-Grafikformaten ausgegeben werden: GIF, JPEG und PNG. Im Parameter format wird einer der folgenden Werte verwendet:

• png8 oder png (Standard) gibt das PNG-Format mit 8 Bit an.
• png32 gibt das PNG-Format mit 32 Bit an.
• gif gibt das GIF-Format an.
• jpg gibt das JPEG-Komprimierungsformat an.
• jpg-baseline gibt ein nichtprogressives JPEG-Komprimierungsformat an.

In der Regel liefern jpg und jpg-baseline die kleinste Bildgröße; dies erfolgt über eine Komprimierung mit Verlusten, sodass die Qualität des Bilds gemindert wird. Mit gif, png8 und png32 ist eine Komprimierung ohne Qualitätsverlust möglich.

Die meisten JPEG-Bilder sind progressiv, das heißt, es wird ein grobkörniges Bild geladen, das mit zunehmender Datenmenge verfeinert und detaillierter dargestellt wird. Folglich wird das JPEG-Format derzeit am häufigsten verwendet, um Bilder schnell auf Webseiten zu laden. Für einige Verwendungsmöglichkeiten von JPEG (besonders das Drucken) sind nichtprogressive (Baseline-) Bilder erforderlich. In solchen Fällen kann das nichtprogressive Format jpg-baseline verwendet werden.

Kartentypen

Mit Google Static Maps API können Karten in den folgenden verschiedenen Formaten erstellt werden:

• roadmap (Standard) gibt ein Roadmap-Standardbild aus, wie es normalerweise auf der Google Maps-Website angezeigt wird. Falls kein Wert für maptype angegeben ist, stelltGoogle Static Maps API standardmäßig roadmap-Kacheln bereit.
• satellite gibt ein Satellitenbild an.
• terrain gibt ein Kartenbild mit Reliefstruktur an, es werden das Gelände und Vegetation abgebildet.
• hybrid gibt ein Hybridbild aus Satelliten- und Roadmap-Bild aus, dabei werden auf einer transparenten Ebene wichtige Straßen- und Ortsnamen auf dem Satellitenbild angezeigt.

Im folgenden Beispielcode wird der Unterschied zwischen den Typen „roadmap“ und „terrain“ veranschaulicht.

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

  

Bei hybriden Karten werden Satellitenbilder und markante Roadmap-Merkmale verwendet, um eine kombinierte Karte zu erstellen. Im folgenden Beispiel werden die Kartentypen „satellite“ und „hybrid“ veranschaulicht:

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

  

Formatierte Karten

Weitere Informationen finden Sie unter Formatierte Karten.

Marker

Mit dem Parameter markers wird ein Satz aus einem oder mehreren Markern für mehrere Standorte definiert. Jeder Marker, der in einer Deklaration markers definiert ist, muss dasselbe optische Format aufweisen. Wenn Sie Marker mit unterschiedlichen Formaten anzeigen möchten, stellen Sie mehrere Parameter des Typs markers mit unterschiedlichen Formatinformationen bereit.

Der Parameter markers verwendet einen Satz von Wertzuweisungen (Marker-Deskriptoren) in folgendem Format:

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

Der Satz des Typs markerStyles steht am Anfang der Deklaration markers und enthält keine oder mehrere Formatdeskriptoren, die durch einen senkrechten Strich (|) getrennt werden. Dann folgt der Satz aus einem oder mehreren Standorten, ebenfalls getrennt durch einen senkrechten Strich (|).

Da sowohl die Formatinformationen als auch die Standortinformationen durch einen senkrechten Strich getrennt werden, müssen die Formatinformationen in Marker-Deskriptoren stets zuerst angegeben werden. Sobald vom Google Static Maps API-Server im Marker-Deskriptor ein Standort erkannt wird, wird angenommen, dass es sich bei allen folgenden Marker-Parametern ebenfalls um Standorte handelt.

Marker-Formate

Bei dem Satz der Marker-Formatdeskriptoren handelt es sich um eine Reihe von Wertzuweisungen, die durch einen senkrechten Strich (|) getrennt werden. Über diesen Formatdeskriptor werden die optischen Eigenschaften definiert, die bei der Anzeige der Marker in diesem Marker-Deskriptor verwendet werden sollen. Diese Formatdeskriptoren enthalten die folgenden Schlüssel-/Wertzuweisungen:

• size: (optional) gibt die Marker-Größe aus dem Satz {tiny, mid, small} an. Falls der Parameter size nicht spezifiziert wird, wird der Marker in der Standardgröße (normal) dargestellt.

• 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.

  Beachten Sie, dass Transparenzen (mit 32-Bit-Hexadezimal-Farbwerten angegeben) in Markern nicht unterstützt werden (für Pfade werden sie unterstützt).

• label: (optional) gibt einen einzelnen Großbuchstaben aus dem Satz {A-Z, 0-9} an. (Die Vorgabe von Großbuchstaben wurde mit dieser API-Version neu eingeführt.) Beachten Sie, dass nur mit Markern der Standardgröße und der Größe mid ein Parameter des Typs alphanumeric-character angezeigt werden kann. Über die Marker tiny und small lässt sich kein alphanumerisches Zeichen darstellen.

Hinweis: Anstelle von Markern können Sie auch ein eigenes benutzerdefiniertes Icon verwenden. (Weitere Informationen finden Sie weiter unten unter Benutzerdefinierte Icons.)

Marker-Standorte

Jeder Marker-Deskriptor muss einen Satz aus einem oder mehreren Standorten enthalten, die angeben, wo auf der Karte der Marker platziert werden soll. Diese Standorte können entweder als Längengrad- und Breitengradangaben oder als Adressen angegeben werden. Die Standorte werden durch einen senkrechten Strich (|) getrennt.

Die Standortparameter legen den Standort des Markers auf der Karte fest. Befindet sich der Standort außerhalb der Karte, wird dieser Marker nicht im erzeugten Bild dargestellt (sofern die Parameter center und zoom bereitgestellt werden). Falls diese Parameter jedoch nicht angegeben werden, wird vom Google Static Maps API-Server automatisch ein Bild erstellt, in dem die bereitgestellten Marker vorhanden sind. (Siehe Implizite Positionierung weiter unten.)

Nachstehend finden Sie ein Beispiel für eine Marker-Deklaration. Beachten Sie, dass ein Satz mit Formaten und drei Standorte definiert wurden:

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

Damit Marker mit unterschiedlichen Formaten definiert werden können, müssen verschiedene Parameter des Typs markers im Code enthalten sein. In diesem Satz mit Parametern des Typs markers werden drei Marker definiert: ein blauen Marker mit der Bezeichnung „S“ bei 62.107733, -145.5419, ein kleiner grüner Marker bei „Delta Junction, AK“ und ein mittelgroßer gelber Marker mit der Bezeichnung „C“ bei „Tok, AK“. Diese Marker werden im folgenden Beispiel abgebildet:

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

Benutzerdefinierte Icons

Sie können anstelle der Marker-Icons von Google auch eigene benutzerdefinierte Icons nutzen. Die benutzerdefinierten Icons werden mithilfe des folgenden Deskriptors im Parameter markers definiert:

• icon gibt eine URL an, die als benutzerdefiniertes Icon für den Marker verwendet wird. Bilder können das Format PNG, JPEG oder GIF aufweisen, hier wird PNG empfohlen.

Der Parameter icon muss mithilfe einer URL angegeben werden (mit URL-Kodierung). Sie können die von den meisten Kurz-URL-Diensten wie https://goo.gl erstellten URLs verwenden. Bei den meisten Kurz-URL-Diensten erfolgt die URL-Kodierung automatisch. Icons sind auf eine maximale Größe von 4096 Pixel (64x64 bei rechteckigen Bildern) begrenzt, und der Google Static Maps API-Dienst ermöglicht die Verwendung von bis zu fünf eindeutigen benutzerdefinierten Icons pro Anforderung. Beachten Sie, dass jedes dieser eindeutigen Icons in Google Static Maps API mehrfach verwendet werden kann.

Der Ankerpunkt eines benutzerdefinierten Icons befindet sich unten in der Mitte des Bildes.

Im folgenden Beispiel werden mit Google Chart API benutzerdefinierte Marker erstellt, die auf verschiedene Coffee Shops in New York City hinweisen:

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

Hinweis: Die oben angegebenen verschiedenen Ebenen der Escape-Zeichen können verwirrend sein. In „Google Chart API“ wird der senkrechte Strich (|) als Trennzeichen für Zeichenfolgen in den URL-Parametern verwendet. Da dieses Zeichen in einer URL jedoch unzulässig ist (siehe Hinweis weiter oben), wird es beim Erstellen einer gültigen Diagramm-URL durch das Escape-Zeichen %7C ersetzt. Anschließend wird das Ergebnis als Zeichenfolge in die Spezifikation icon eingebettet. Diese Zeichenfolge enthält aber das Zeichen % (aufgrund des oben genannten Escape-Zeichens %7C), das nicht direkt als Daten in eine URL einfließen kann und daher durch das Escape-Zeichen %25 ersetzt wird. Im Ergebnis enthält die URL dann %257C, also zwei Ebenen der Kodierung. Ebenso enthält die Chart-URL das Zeichen &, das nicht direkt eingebunden werden kann, weil es fälschlicherweise als Parametertrennzeichen der Google Static Maps API-URL interpretiert werden könnte. Daher ist auch hier eine URL-Kodierung erforderlich.

Im Folgenden finden Sie die Schritte zum Erstellen der Google Static Maps API-URL:

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Pfade für Google Static Maps API

Mit dem Parameter path wird ein Satz aus einem oder mehreren Standorten definiert, die über einen Pfad verbunden sind, der als Overlay auf dem Kartenbild liegt. Im Parameter path wird ein Satz von Wertzuweisungen (Pfaddeskriptoren) in folgendem Format verwendet:

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

Beachten Sie, dass beide Pfadpunkte durch einen senkrechten Strich (|) getrennt werden. Da sowohl die Formatinformationen als auch die Pfadpunktinformationen durch einen senkrechten Strich getrennt werden, müssen die Formatinformationen in Pfaddeskriptoren stets zuerst angegeben werden. Sobald vom Google Static Maps API-Server im Pfaddeskriptor ein Standort erkannt wird, wird angenommen, dass es sich bei allen folgenden Pfadparametern ebenfalls um Standorte handelt.

Pfadformate

Bei dem Satz der Pfadformatdeskriptoren handelt es sich um eine Reihe von Wertzuweisungen, die durch einen senkrechten Strich (|) getrennt werden. Über diesen Formatdeskriptor werden die optischen Eigenschaften definiert, die bei der Anzeige des Pfads verwendet werden sollen. Diese Formatdeskriptoren enthalten die folgenden Schlüssel-/Wertzuweisungen:

• weight: (optional) gibt die Breite des Pfads in Pixel an. Falls der Parameter weight nicht spezifiziert wird, wird der Pfad in der Standardbreite (5 Pixel) dargestellt.

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

  Bei Verwendung eines 32-Bit-Hexadezimalwerts geben die letzten beiden Zeichen die alphanumerische Transparenz in einem 8-Bit-Wert an. Dieser Wert liegt zwischen 00 (vollständige Transparenz) und FF (vollständige Deckkraft). Beachten Sie, dass Transparenzen in Pfaden unterstützt werden (aber nicht für Marker).

• fillcolor: (optional) gibt an, dass der Pfad einen polygonalen Bereich abgrenzt, und spezifiziert die Füllfarbe, die als Overlay für dieses Gebiet verwendet werden soll. Für den nachfolgenden Satz mit Standorten ist kein „geschlossener“ Loop nötig, denn vom Google Static Maps API-Server werden die ersten und die letzten Punkte automatisch verbunden. Beachten Sie jedoch, dass jeder Strich außerhalb des gefüllten Bereichs erst geschlossen ist, wenn Sie die Start- und Endposition angeben.
• geodesic: (optional) gibt an, dass der angeforderte Pfad als eine der Erdkrümmung folgende geodätische Linie interpretiert werden soll. Bei „false“ wird der Pfad als direkte Linie auf dem Bildschirm dargestellt. Der Standardwert ist „false“.

Nachfolgend werden einige Beispiele für Pfaddefinitionen angezeigt:

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

Diese Pfadformate sind optional. Wenn Sie mit den Standardeigenschaften arbeiten möchten, können Sie die Definition der Pfadeigenschaften überspringen. In dem Fall enthält das erste „Argument“ des Pfaddeskriptors stattdessen den ersten deklarierten Punkt (Standort).

Pfadpunkte

Damit ein Pfad gezeichnet werden kann, müssen im Parameter path zwei oder mehr Punkte übergeben werden. Dann kann Google Static Maps API den Pfad entlang diesen Punkten in der angegebenen Reihenfolge verbinden. Jeder Wert für pathPoint wird in pathDescriptor angegeben, die Werte werden durch einen senkrechten Strich (|) getrennt.

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

Nachfolgend werden die Angaben für den Parameter path angegeben:

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 kräftigen roten Linie und einer Deckkraft von 100 % definiert:

Nachfolgend werden die Angaben für den Parameter path angegeben:

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

Im folgenden Beispiel wird ein polygonales Gebiet in Manhattan definiert, für die Standorte wird eine Reihe von Kreuzungen übergeben:

Nachfolgend werden die Angaben für den Parameter path angegeben:

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 nicht sichtbar ist; das polygonale Gebiet hat hier eine Deckkraft von 15 %.

Kodierte Polylinien

Anstatt eine Reihe von Standorten anzugeben, können Sie auch einen Pfad als kodierte Polylinie deklarieren. Dazu verwenden Sie das Präfix enc: in der Standortdeklaration von path. Wenn Sie eine kodierte Polylinie für eine Karte angeben, ist es in diesem Fall nicht nötig, die (normalerweise erforderlichen) Parameter center und zoom zu spezifizieren.

Im folgenden Beispiel wird die Strecke des Alaska Highway von Dawson Creek, BC, bis zu Delta Junction, AK, mit einer kodierten Polylinie dargestellt:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

Ebenso wie Standardpfade können auch kodierte Polylinien polygonale Gebiete abgrenzen, sofern das Argument fillcolor 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&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

Viewports

In Bildern kann durch das Angeben von sichtbaren Standorten mithilfe des Parameters visible ein Viewport definiert werden. Über den Parameter visible wird der Google Static Maps API-Dienst angewiesen, eine Karte so zu erstellen, dass die bestehenden Standorte sichtbar bleiben. (Dieser Parameter kann auch mit vorhandenen Markern oder Pfaden kombiniert werden, um eine sichtbare Region zu definieren.) Wenn ein Viewport auf diese Weise definiert wird, muss keine genaue Vergrößerungsstufe mehr angegeben werden.

Im folgenden Beispiel wird eine Karte angefordert, deren Mittelpunkt Boston, MA, ist, und die sowohl das MIT als auch den Harvard Square in Cambridge, MA, abbildet:

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

Implizite Positionierung auf der Karte

Normalerweise müssen Sie die URL-Parameter center und zoom angeben, um den Standort und die Vergrößerungsstufe der erzeugten Karte festzulegen. Wenn Sie jedoch die Parameter markers, path oder visible übergeben, können Sie stattdessen von Google Static Maps API die korrekten Werte für den Mittelpunkt und die Vergrößerungsstufe implizit ermitteln lassen. Dazu werden die Positionen dieser Elemente ausgewertet.

Werden zwei oder mehr Elemente bereitgestellt, können mit Google Static Maps API ein geeigneter Mittelpunkt und eine entsprechende Vergrößerungsstufe mit ausreichender Toleranz für die enthaltenen Elemente festgelegt werden. Im folgenden Beispiel wird eine Karte für 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

Fehlerbehebung und Support

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

Im Falle eines Fehlers kann von Google Static Maps API eine Fehlermeldung oder eine Warnung ausgegeben werden. Sie sollten insbesondere auf Warnungen achten, wenn Sie feststellen, dass auf der Karte Elemente fehlen. Auch vor der Einführung einer neuen Anwendung sollten Sie die Warnungen prüfen. Möglicherweise sind die Warnungen nicht sofort ersichtlich, da sie im HTTP-Header angezeigt werden. Weitere Informationen finden Sie im Leitfaden zu Fehlermeldungen und Warnungen.

Zuvor war in Google Static Maps API die Angabe des Parameters sensor erforderlich. Damit wurde festgelegt, ob seitens der Anwendung ein Sensor zur Ermittlung des Benutzerstandorts verwendet wurde. Dieser Parameter wird nicht mehr benötigt.