Wypróbuj

Wprowadzenie

Interfejs Statyczny interfejs API Map Google zwraca w odpowiedzi na żądanie HTTP obraz (w formacie GIF, PNG lub JPEG). W przypadku każdego żądania możesz określić lokalizację mapy, jej rozmiar, poziom powiększenia, typ mapy i położenie opcjonalnych znaczników w określonych lokalizacjach na mapie. Znaczniki możesz też oznaczać etykietami przy użyciu znaków alfanumerycznych.

Obraz statycznego interfejsu API Map Google jest umieszczony w atrybucie src tagu <img> lub jego odpowiedniku w innych językach programowania.

Ten dokument zawiera opis wymaganego formatu adresów URL statycznego interfejsu API Map Google oraz dostępne parametry. Znajdziesz w nim też praktyczne porady na temat określania adresów URL.

Zanim zaczniesz

Ten dokument jest przeznaczony dla programistów witryn i urządzeń mobilnych, którzy chcą umieszczać obrazy statycznego interfejsu API Map Google na stronach internetowych lub w aplikacjach mobilnych. Zawiera wprowadzenie do korzystania z interfejsu API i materiałów referencyjnych dotyczących dostępnych parametrów.

Zanim zaczniesz programować za pomocą statycznego interfejsu API Map Google, zapoznaj się z wymaganiami dotyczącymi uwierzytelniania (potrzebny klucz interfejsu API) oraz informacjami o użyciu i płatnościach interfejsu API (musisz włączyć płatności w projekcie).

Parametry adresu URL

Adres URL statycznego interfejsu API Map Google musi mieć następującą formę:

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

Jeśli dostęp do Twojej witryny jest uzyskiwany za pomocą protokołu HTTPS, musisz też załadować obrazy statycznego interfejsu API Map Google przez HTTPS. Pozwoli to uniknąć alertów przeglądarki dotyczących zabezpieczeń. Protokół HTTPS jest również zalecany, jeśli żądania zawierają poufne dane użytkownika, takie jak lokalizacja użytkownika:

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

Niezależnie od tego, czy używasz HTTP czy HTTPS, niektóre parametry adresu URL są wymagane, a niektóre są opcjonalne. Standardowo w adresach URL wszystkie parametry są rozdzielone znakiem „&”. W tym dokumencie opisujemy listę parametrów i ich możliwe wartości.

Interfejs Statyczny interfejs API Map Google definiuje obrazy na mapie za pomocą tych parametrów adresu URL:

Parametry lokalizacji

• center (wymagany, jeśli nie ma znaczników) określa środek mapy, czyli odległość od wszystkich krawędzi mapy. Ten parametr przyjmuje lokalizację w postaci pary rozdzielonych przecinkami (szerokość geograficzna,długość geograficzna) (np. „40.714728,-73.998672”) lub adresu ciągu znaków (np. ratusz, Nowy Jork, ny) określającyj unikalną lokalizację na powierzchni Ziemi. Więcej informacji znajdziesz w sekcji Lokalizacje.
• zoom (wymagany, jeśli nie ma znaczników) określa poziom powiększenia mapy, który określa poziom powiększenia mapy. Ten parametr przyjmuje wartość liczbową odpowiadającą poziomowi powiększenia odpowiedniego regionu. Więcej informacji znajdziesz w artykule Poziomy powiększenia.

Parametry mapy

• size (wymagany) określa prostokątne wymiary obrazu mapy. Ten parametr ma ciąg znaków {horizontal_value}x{vertical_value}. Na przykład 500x400 definiuje mapę o wymiarach 500 × 400 pikseli i wysokość. Mapy o szerokości mniejszej niż 180 pikseli będą wyświetlać logo Google o mniejszym rozmiarze. Na ten parametr wpływa parametr scale. Ostatecznym rozmiarem danych wyjściowych jest iloczyn rozmiaru i skali.
• scale (opcjonalny) wpływa na liczbę zwracanych pikseli. scale=2 zwraca 2 razy więcej pikseli niż scale=1, zachowując ten sam obszar pokrycia i ten sam poziom szczegółów (tj. zawartość mapy nie ulega zmianie). Przydaje się to podczas tworzenia ekranów o wysokiej rozdzielczości. Wartością domyślną jest 1. Akceptowane wartości to 1 i 2. Więcej informacji znajdziesz w artykule Wartości skali.
• format (opcjonalny) określa format tworzonego obrazu. Domyślnie interfejs Statyczny interfejs API Map Google tworzy obrazy PNG. Istnieje kilka możliwych formatów, w tym GIF, JPEG i PNG. Wybór formatu zależy od tego, jak chcesz zaprezentować obraz. Format JPEG zwykle zapewnia większą kompresję, podczas gdy GIF i PNG zapewniają więcej szczegółów. Więcej informacji znajdziesz w artykule Formaty obrazu.
• maptype (opcjonalny) określa typ mapy do utworzenia. Istnieje kilka możliwych wartości typu mapy, np. roadmap, satellite, hybrid i terrain. Więcej informacji znajdziesz w artykule na temat typów map statycznych interfejsu API Map Google.
• language (opcjonalny) określa język wyświetlania etykiet na kafelkach mapy. Ten parametr jest obsługiwany tylko w przypadku niektórych kafelków krajów. Jeśli określony kafelek nie obsługuje konkretnego języka, zostanie użyty domyślny język tego zestawu.
• region (opcjonalny) określa odpowiednie granice do wyświetlenia na podstawie wrażliwości geograficznej i politycznej. Akceptuje kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Listę obsługiwanych regionów znajdziesz w artykule dotyczącym pokrycia zasięgu Google Maps Platform.

Parametry cech

• map_id (opcjonalny) określa identyfikator konkretnej mapy. Identyfikator mapy wiąże mapę z określonym stylem lub obiektem i musi należeć do tego samego projektu co klucz interfejsu API, który służy do inicjowania mapy. Więcej informacji znajdziesz w artykule Korzystanie z identyfikatorów map.
• markers (opcjonalny) definiuje co najmniej 1 znacznik, który chcesz dołączyć do obrazu w określonych lokalizacjach. Ten parametr przyjmuje pojedynczą definicję z parametrami rozdzielonymi pionową kreską (|). Wiele znaczników może być umieszczonych w tym samym parametrze markers, pod warunkiem że mają ten sam styl. Możesz dodać kolejne znaczniki o różnych stylach, dodając kolejne parametry markers. Jeśli podajesz znaczniki mapy, nie musisz określać (zwykle wymaganych) parametrów center i zoom. Więcej informacji znajdziesz w artykule Znaczniki statycznego interfejsu API Map Google.
• path (opcjonalny) określa pojedynczą ścieżkę obejmującą co najmniej 2 połączone punkty, które nakłada się na obraz w określonych lokalizacjach. Ten parametr przyjmuje ciąg definicji punktów rozdzielonych pionową kreską (|) lub zakodowaną łamaną łamaną za pomocą prefiksu enc: w deklaracji lokalizacji na ścieżce. Możesz podać dodatkowe ścieżki, dodając kolejne parametry path. Pamiętaj, że jeśli podasz ścieżkę do mapy, nie musisz określać (zwykle wymaganych) parametrów center i zoom. Więcej informacji znajdziesz w artykule na temat statycznych ścieżek interfejsu API Map Google.
• visible (opcjonalny) określa co najmniej jedną lokalizację, która powinna pozostać widoczna na mapie, przy czym nie będą wyświetlane żadne znaczniki ani inne wskaźniki. Użyj tego parametru, by mieć pewność, że niektóre funkcje lub lokalizacje na mapie będą widoczne w interfejsie statycznego interfejsu API Map Google.
• style (opcjonalny) określa niestandardowy styl służący do zmiany sposobu wyświetlania określonych obiektów (drog, parków i innych) mapy. Ten parametr przyjmuje argumenty feature i element identyfikujące cechy stylu oraz zestaw operacji stylu do zastosowania do wybranych cech. Możesz podać wiele stylów, dodając dodatkowe parametry style. Więcej informacji znajdziesz w przewodniku po mapach stylów.

Parametry klucza i podpisu

• key (wymagane) umożliwia monitorowanie korzystania z interfejsu API przez aplikację w Google Cloud Console. W razie potrzeby Google może skontaktować się z Tobą w sprawie aplikacji. Więcej informacji znajdziesz w artykule Używanie kluczy interfejsu API z interfejsem Maps Static API.
• signature (zalecany) to podpis cyfrowy używany do sprawdzania, czy żądania witryny generowane przy użyciu klucza interfejsu API są do tego autoryzowane. Żądania bez podpisu cyfrowego mogą się nie powieść. Więcej informacji znajdziesz w artykule Używanie podpisu cyfrowego.

Ograniczenie rozmiaru adresu URL

Adresy URL statycznego interfejsu API Map Google mają długość do 8192 znaków. W praktyce prawdopodobnie nie będziesz potrzebować więcej adresów URL, chyba że utworzysz skomplikowane mapy z dużą liczbą znaczników i ścieżek.

Wykorzystanie parametru

Interfejs Google Static API jest stosunkowo łatwy w użyciu, ponieważ zawiera wyłącznie parametry URL. W tej sekcji dowiesz się, jak używać tych parametrów do tworzenia adresów URL.

Określanie lokalizacji

Statyczny interfejs API Map Google musi umożliwiać dokładne wskazywanie lokalizacji na mapie, tak aby można było ustawić ją na właściwej lokalizacji (przy użyciu parametru center) lub umieścić dowolne opcjonalne oznaczenia miejsc (przy użyciu parametru markers) w lokalizacjach na mapie. Statyczny interfejs API Map Google określa lokalizacje za pomocą liczb (wartości szerokości i długości geograficznej) lub ciągów (adresów). Te wartości identyfikują lokalizację geograficzną.

Niektóre parametry (np. markers i path) mogą mieć wiele lokalizacji. W takich przypadkach lokalizacje są rozdzielone pionową kreską (|).

Długość i szerokość geograficzna

Długość i szerokość geograficzna są określane za pomocą liczb w ciągu tekstowym rozdzielanym przecinkami, z dokładnością do 6 miejsc po przecinku. Na przykład „40.714728,-73.998672” to prawidłowa wartość kodu geograficznego. Precyzja wykraczająca poza 6 miejsc po przecinku jest ignorowana.

Wartości długości geograficznej są określane na podstawie odległości od Greenwich w Anglii, w której znajduje się południk zielony. Ponieważ Greenwich znajduje się na szerokości 51,477222, możemy wpisać wartość center 51.477222,0 w celu wyśrodkowania mapy na Greenwich:

Wartości długości i szerokości geograficznej muszą odpowiadać prawidłowej lokalizacji na powierzchni ziemi. Szerokość geograficzna może mieć dowolną wartość z zakresu od -90 do 90, a długość geograficzna – dowolną wartość z zakresu od -180 do 180. Jeśli podasz nieprawidłową szerokość lub długość geograficzną, żądanie zostanie odrzucone jako nieprawidłowe.

Adresy

Większość osób nie mówi o długości ani szerokości geograficznej, tylko lokalizacje z adresami. Proces przekształcania adresu w punkt geograficzny jest nazywany geokodowaniem, a usługa statycznego interfejsu API Map Google może wykonać geokodowanie za Ciebie, jeśli podasz prawidłowe adresy.

W każdym parametrze, który pozwala podać szerokość lub długość geograficzną, możesz podać ciąg znaków wskazujący adres. Google wyśle dane geograficzne do geokodu adresu i udostępniy usłudze Maps Static API wartość szerokości i długości geograficznej, która będzie używana do umieszczania znaczników lub określania lokalizacji. Ciąg powinien być zakodowany na potrzeby adresu URL, więc adresy takie jak „City Hall, New York, NY” powinny zostać przekształcone na „City+Hall,New+York,NY”.

Pamiętaj, że adresy mogą odzwierciedlać dokładne lokalizacje, takie jak adresy, linie łamane (np. nazwane trasy) lub wielokąty, takie jak miasta, kraje czy parki narodowe. W przypadku wyników wielokątów i wielokątów serwer Statyczny interfejs API Map Google użyje punktu centralnego linii/obszaru jako centrum adresu. Jeśli nie masz pewności, jak adres może być interpretowany geograficznie, możesz sprawdzić adres za pomocą tego narzędzia do kodowania geograficznego.

Ten przykład generuje statyczny obraz mapy na potrzeby Berkeley w Kalifornii:

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

Poziomy powiększenia

Mapy Google mają liczbę całkowitą, która określa rozdzielczość bieżącego widoku. Powiększenie pomiędzy 0 (najniższy poziom, na którym na całej mapie widać cały świat) i 21+ (do uliczek i poszczególnych budynków) jest możliwe w domyślnym widoku roadmap. Zarysy budynków (jeśli są dostępne) pojawią się na mapie wokół poziomu powiększenia 17. Ta wartość różni się w zależności od obszaru i może się zmieniać w miarę rozwoju danych.

Mapy Google ustawiają poziom powiększenia 0 tak, by obejmował całą Ziemię. Każdy skuteczny poziom powiększenia podwaja precyzję zarówno w poziomie, jak i w orientacji pionowej. Więcej informacji na ten temat znajdziesz w dokumentacji interfejsu API JavaScript Map Google.

Uwaga: niektóre poziomy powiększenia nie są widoczne we wszystkich lokalizacjach na Ziemi. Poziomy powiększenia różnią się w zależności od lokalizacji, ponieważ dane w niektórych częściach kuli ziemskiej są bardziej szczegółowe niż w innych lokalizacjach.

Jeśli wyślesz żądanie poziomu powiększenia, który nie obejmuje żadnych kafelków mapy, interfejs API Map statycznych w Mapach Google zwróci pusty obraz.

Poniższa lista pokazuje przybliżony poziom szczegółowości na poszczególnych poziomach powiększenia:

• 1: Świat
• 5: ląd/kontynent
• 10: Miasto
• 15: ulice
• 20: Budynki

W tym przykładzie zażądano 2 map Manhattanu z tą samą wartością center, ale przy poziomach powiększenia 12 i 14:

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

  

Rozmiary obrazów

Parametr size w połączeniu z wartością center określa obszar zasięgu mapy. Określa też rozmiar wyjściowy mapy w pikselach pomnożony przez wartość scale (domyślnie 1).

W tej tabeli podano maksymalne dozwolone wartości parametru size w każdej wartości scale.

scale=1	scale=2
640x640	640x640 (zwraca 1280 x 1280 pikseli)

W tym przykładzie zażądano „fragmentu” Ziemi na równiku 1 poziomu powiększenia:

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

W tym przykładzie żądamy przesłania niewielkiej mapy o wymiarach 100 x 100 pikseli wyśrodkowanych w tym samym regionie. Zwróć uwagę na mniejsze logo Google:

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

Skalowanie wartości

Parametr size interfejsu Maps Static API określa rozmiar mapy w pikselach, dzięki czemu mapa z atrybutem size=200x200 będzie zwracana jako 200 x 200 pikseli. Na monitorze LCD, który zwykle wyświetla się w około 100 pikseli na cal, 200 x 200 pikseli wynosi około 2 cale na każdy wymiar.

Coraz więcej urządzeń mobilnych ma też ekrany o wysokiej rozdzielczości z gęstością pikseli 300 ppi.

• zmniejsz rozmiar obrazu 200 x 200 pikseli do zaledwie 1,48 cm, przez co etykiety i ikony są zbyt małe;
• Skaluj (powiększaj) obraz, aby poprawić jego czytelność, dzięki czemu obraz będzie wyraźny i pikselowy.

Za mały	Jest zbyt nieostre

Opracowując aplikacje na urządzenia mobilne, możesz używać parametru scale interfejsu API, aby zwracać obrazy map w wyższej rozdzielczości, które rozwiązują powyższe problemy. Wartość scale jest mnożona przez size, by określić rzeczywisty rozmiar obrazu w pikselach bez zmiany obszaru pokrycia mapy. Domyślna wartość scale to 1, a dopuszczalne wartości to 1 i 2.

Na przykład wartość skali 2 zwróci ten sam obszar pokrycia mapy, co żądanie bez określonej skali, ale z 2 razy większą liczbą pikseli w każdym wymiarze. Obejmuje to drogi i etykiety, które są czytelne na ekranach o dużej rozdzielczości, małych ekranach oraz po przeskalowaniu przez przeglądarkę.

150x150	150 x 150&scale=2

Taki obraz będzie też dobrze działał w przeglądarkach na komputerach stacjonarnych, jeśli wstawisz go do tagu img lub div o wysokości i szerokości ustawionej w CSS. Przeglądarka zmniejszy rozmiar obrazu do prawidłowego rozmiaru bez utraty jakości.

Ta tabela pokazuje trzy różne żądania obrazu.

• Pierwszy dotyczy obrazu 100 x 100 bez określonej wartości skali. Na komputerze wyświetla się prawidłowo, ale na urządzeniu mobilnym jest za mała do odczytu.
• Druga podwaja rozmiar mapy. Na komputerze usługa porównywania cen mieści się w określonym elemencie img o wymiarach 100 x 100, ale zmniejszając rozmiar obrazu, drogi i etykiety stają się zbyt małe. Na urządzeniu mobilnym obraz ma odpowiedni rozmiar, ale drogi i etykiety są nieczytelne.
• Trzecia prośba dotyczy mapy 100 x 100 o wartości scale=2. Obraz jest zwracany z 200 pikselami szczegółów. Komputer na pełną skalę skaluje go w dół, tak aby nie odróżniał się od pierwotnego żądania 100 x 100, a w przeglądarce mobilnej występuje dodatkowa rozdzielczość zwrócona przez interfejs API.

Żądania obrazów
Urządzenie	100x100	200x200	100x100&scale=2
Komputer (z height="100px" i width="100px" tagu img)
Wysoka rozdzielczość (symulowana)

Więcej informacji na temat tworzenia treści na urządzenia mobilne i wyświetlacze o wysokiej rozdzielczości znajdziesz w tych artykułach:

• Obsługa wielu ekranów w dokumentacji dla deweloperów aplikacji na Androida.
• Zalecenia Webkit.org dotyczące opracowywania witryn internetowych o wysokiej rozdzielczości DPI.
• Obsługa ekranów o wysokiej rozdzielczości w bibliotece dla deweloperów aplikacji na iOS.

Formaty graficzne

Obrazy mogą być zwracane w kilku popularnych formatach graficznych: GIF, JPEG i PNG. Parametr format przyjmuje jedną z tych wartości:

• png8 lub png (domyślny) określa 8-bitowy format PNG.
• png32 określa 32-bitowy format PNG.
• gif określa format GIF.
• jpg określa format kompresji JPEG.
• jpg-baseline określa niekompresujący format kompresji JPEG.

Te żądania dotyczą map w formatach gif i png:

  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

Najmniejszy rozmiar obrazu to zazwyczaj jpg i jpg-baseline, ale dzieje się tak przez kompresję „stratną”, która może zmniejszyć jego rozdzielczość. gif, png8 i png32 zapewniają bezstratną kompresję.

Większość obrazów JPEG ma charakter progresywny, co oznacza, że wczytywały się wcześniej i zawężają rozdzielczość obrazu w miarę gromadzenia nowych danych. Umożliwia to szybkie wczytywanie obrazów na stronach internetowych i jest obecnie najpopularniejszym formatem plików JPEG. Jednak niektóre zastosowania formatu JPEG wymagają obrazów nieprogresywnych (elementów bazowych). W takich przypadkach możesz używać formatu jpg-baseline, który nie jest postępowy.

Typy map

Interfejs Maps Static API tworzy mapy w kilku formatach wymienionych poniżej:

• roadmap (domyślna) określa standardowy obraz planu trasy w typowy sposób, który zwykle wyświetla się w witrynie Map Google. Jeśli nie określono wartości maptype, interfejs API statycznych Map Google domyślnie wyświetla kafelki roadmap.
• satellite określa zdjęcie satelitarne.
• terrain określa obraz mapy fizycznej, przedstawiający teren i roślinność.
• hybrid określa hybrydowe połączenie zdjęcia satelitarnego i planu przejazdu, wyświetlając przezroczystą warstwę głównych ulic i nazw miejsc na obrazie satelitarnym.

Widać tu różnicę między typami map i typów terenu w tym przykładzie kodu.

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

  

W celu utworzenia mapy mieszanej mapy hybrydowe wykorzystują zdjęcia satelitarne i dobrze widoczne funkcje drogowe. Te przykłady pokazują mapy satelitarne i hybrydowe:

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

  

Stylizowane mapy

Dostosuj wygląd standardowej mapy Google, stosując własne style. Zapoznaj się z przewodnikiem dotyczącym map stylu.

Znaczniki

Parametr markers określa zestaw znaczników (1 kodu) mapy w zestawie lokalizacji. Każdy znacznik określony w pojedynczej deklaracji markers musi zawierać ten sam styl wizualny. Jeśli chcesz wyświetlać znaczniki w różnych stylach, musisz podać kilka parametrów markers z innymi informacjami o stylu.

Parametr markers pobiera zestaw przypisań wartości (deskryptory znaczników) w następującym formacie:

markers=markerStyles|markerLocation1| markerLocation2|... itp.

Zestaw markerStyles jest zadeklarowany na początku deklaracji markers i składa się z 0 deskryptorów stylu rozdzielonych pionową kreską (|), po której następuje zbiór co najmniej 1 lokalizacji także rozdzielonych pionową kreską (|).

Informacje o stylu i informacje o lokalizacji są rozdzielone pionową kreską, dlatego muszą być wyświetlane jako pierwsze w deskryptorach znacznika. Gdy serwer interfejsu statycznego interfejsu API napotka lokalizację w deskrypcie znacznika, przyjmuje się również, że wszystkie pozostałe parametry znaczników są lokalizacjami.

Style znaczników

Zestaw deskryptorów stylu znaczników to seria przypisań wartości rozdzielonych pionową kreską (|). Ten deskryptor tego stylu definiuje atrybuty wizualne, których należy używać podczas wyświetlania znaczników w tym deskryptoru znacznika. Te deskryptory stylu zawierają te przypisania par klucz/wartość:

• size: (opcjonalnie) określa rozmiar znacznika z zestawu {tiny, mid, small}. Jeśli nie ustawisz parametru size, znacznik wyświetli się w rozmiarze domyślnym (normalnym).

• color: (opcjonalny) określa kolor 24-bitowy (np. color=0xFFFFCC) lub wstępnie zdefiniowany kolor ze zbioru {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Znaczniki przezroczystości (określane za pomocą 32-bitowych wartości szesnastkowych kolorów) nie są obsługiwane przez znaczniki, ale są one obsługiwane w przypadku ścieżek.

• label: (opcjonalnie) określa pojedynczy znak alfanumeryczny wielkimi z zestawu {A–Z, 0–9}. (Wymagania dotyczące wielkich liter w nowej wersji interfejsu API są nowe). Znaczniki o rozmiarach domyślnych i mid są jedynymi znacznikami, które mogą wyświetlać parametr alphanumeric-character. Znaczniki tiny i small nie mogą wyświetlać znaku alfanumerycznego.

Skalowanie znaczników

Wartość scale jest mnożona przez rozmiar znacznika, aby uzyskać rzeczywisty rozmiar znacznika w pikselach. Wartość domyślna to 1; akceptowane wartości to 1, 2 i 4.

Limit rozmiaru obrazu w obrazach obowiązuje po zastosowaniu skalowania. Jeśli na przykład znacznik ma wartość scale:2, może być większy niż maksymalny rozmiar 4096 pikseli, o ile po jego skalowaniu zmniejszy się do mniej niż 4096 pikseli. Jeśli wyświetlasz mapy w wyższej rozdzielczości, używaj ich w połączeniu z skalowaniem mapy.

Lokalizacje znaczników

Każdy deskryptor znacznika musi zawierać zestaw miejsc określających, gdzie należy umieścić znacznik na mapie. Lokalizacje te można określić jako wartości szerokości i długości geograficznej lub jako adresy. Lokalizacje te są rozdzielone pionową kreską (|).

Uwaga: jeśli określisz lokalizacje znaczników przy użyciu metody, która wymaga geokodowania, np. w postaci zrozumiałych dla człowieka ciągów znaków lub linii łamanych, żądanie może zawierać maksymalnie 15 znaczników. Ten limit dotyczy tylko lokalizacji znaczników, które wymagają geokodowania. Nie dotyczy lokalizacji znaczników wskazanych za pomocą współrzędnych geograficznych.

Parametry lokalizacji określają położenie znacznika na mapie. Jeśli lokalizacja jest poza mapą, ten znacznik nie pojawi się w skonstruowanym obrazie, o ile parametry center i zoom są podane. Jeśli jednak nie podasz tych parametrów, serwer Maps Static API automatycznie utworzy obraz zawierający przesłane znaczniki. (Patrz sekcja Pozycjonowanie pośrednie).

Przykładowa deklaracja znacznika znajduje się tutaj. Zwróć uwagę, że definiujemy jeden zestaw stylów i trzy lokalizacje:

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

Aby zdefiniować znaczniki o różnych stylach, musimy podać kilka parametrów markers. Ten zestaw parametrów markers definiuje trzy znaczniki: jeden niebieski z etykietą „S” na stronie 62.107733, -145.5419, 1 mały zielony znacznik w miejscu „delta Junction, AK” i jeden średni żółty znacznik z etykietą „C” na „Tok, AK”. Te znaczniki są widoczne w tym przykładzie:

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

Ikony niestandardowe

Zamiast ikon Google możesz używać własnych ikon niestandardowych. Niestandardowe ikony są określane za pomocą deskryptora icon w parametrze markers. Przykład:

markers=icon:URLofIcon|markerLocation

Określ icon za pomocą adresu URL (który powinien być zakodowany na potrzeby adresu URL). Możesz używać adresów URL utworzonych przez usługi skracające adresy URL, takie jak https://goo.gl. Większość usług skracania adresów URL wykorzystuje automatyczne kodowanie adresów URL.

Możesz określić punkt zakotwiczenia ikony niestandardowej. Punkt zakotwiczenia określa sposób umieszczenia ikony w odniesieniu do wskazanych lokalizacji markers. Punkt zakotwiczenia niestandardowej ikony jest domyślnie umieszczony na dole pośrodku obrazu. Możesz podać inny punkt zakotwiczenia za pomocą deskryptora anchor w połączeniu z icon. Ustaw anchor jako punkt x,y ikony (np. 10,5) lub jako wstępnie zdefiniowane wyrównanie przy użyciu jednej z tych wartości: top, bottom, left, right, center, topleft, topright, bottomleft lub bottomright. Przykład:

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

W każdym żądaniu możesz użyć maksymalnie 5 unikalnych ikon niestandardowych. To ograniczenie nie oznacza, że jesteś na mapie ograniczone do 5 lokalizacji. Każda unikalna ikona może być używana z więcej niż jedną lokalizacją markers na mapie.

Format ikony:

• Obrazy ikon mogą być w formacie PNG, JPEG lub GIF, zalecamy jednak format PNG.
• Maksymalny rozmiar ikon to 4096 pikseli (64 x 64 w przypadku obrazów kwadratowych).

Przykłady ikon niestandardowych

Przykład 1 tworzy niestandardowe ikony i pozycjonuje je za pomocą kotwic.

http://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

Przykład 2 tworzy te same ikony niestandardowe co przykład 1, ale nie ustala pozycji ikon za pomocą kotwic, ponieważ opiera się na domyślnej zakotwiczeniu w dolnej części środkowej.

http://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

Ścieżki statycznego interfejsu API Map Google

Parametr path określa zbiór lokalizacji obejmujący jedną lub więcej ścieżek, które łączy się z nakładką na obrazie mapy. Parametr path pobiera zestaw przypisań wartości (deskryptory ścieżki) tego formatu:

path=pathStyles|pathLocation1|pathLocation2|... itp.

Zwróć uwagę, że punkty na ścieżce są rozdzielone pionową kreską (|). Ponieważ informacje o stylu i dane punktu są rozdzielone pionową kreską, informacje o stylu muszą być widoczne jako pierwsze w każdym deskryptorze ścieżki. Gdy serwer interfejsu statycznego interfejsu API napotka lokalizację w deskryptorach ścieżki, przyjmuje się również, że wszystkie pozostałe parametry ścieżki są lokalizacjami.

Style ścieżek

Zestaw deskryptorów stylu ścieżki to seria przypisań wartości rozdzielonych pionową kreską (|). Deskryptor tego stylu określa atrybuty wizualne, których należy używać podczas wyświetlania ścieżki. Deskryptory stylu zawierają te przypisania par klucz-wartość:

• weight: (opcjonalny) określa grubość ścieżki w pikselach. Jeśli nie ustawisz parametru weight, ścieżka będzie miała domyślną grubość (5 pikseli).

• color: (opcjonalny) określa kolor jako 24-bitowy (przykład: color=0xFFFFCC) lub 32-bitowy szesnastkowy (przykład: color=0xFFFFCCFF) albo z zestawu {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Jeśli określona jest 32-bitowa wartość szesnastkowa, ostatnie dwa znaki określają 8-bitową wartość przezroczystości alfa. Ta wartość różni się między 00 (całkowicie przezroczysta) a FF (całkowicie nieprzezroczysta). Przezroczystość jest obsługiwana w ścieżkach, ale nie w przypadku znaczników.

• Pole fillcolor: (opcjonalne) wskazuje, że ścieżka wskazuje wielokąt, a także określa kolor wypełnienia, który ma być użyty jako nakładka w tym obszarze. Zestaw lokalizacji nie musi być „pętlią”; serwer Static API Map Google automatycznie łączy się z pierwszym i ostatnim punktem. Pamiętaj jednak, że żadna kreska na zewnątrz wypełnionego obszaru nie zostanie zamknięta, chyba że wyraźnie podasz tę samą lokalizację początkową i końcową.
• geodesic: (opcjonalnie) wskazuje, że żądana ścieżka powinna być interpretowana jako linia geodezyjna wzdłuż krzywizny Ziemi. Jeśli wartość to fałsz, ścieżka jest wyświetlana w formie prostej linii w obszarze ekranu. Wartość domyślna to fałsz.

Przykładowe definicje ścieżek:

• Cienka niebieska linia, 50% krycia: path=color:0x0000ff80|weight:1
• Czerwona linia: path=color:0xff0000ff|weight:5
• Gruba linia ciągła: path=color:0xffffffff|weight:10

Te style ścieżki są opcjonalne. Jeśli chcesz korzystać z atrybutów domyślnych, możesz pominąć definiowanie atrybutów ścieżki. W takim przypadku pierwszy „argument” deskryptora będzie zawierał zamiast pierwszego zadeklarowanego punktu (lokalizacji).

Punkty na ścieżce

Aby można było narysować ścieżkę, parametr path musi być przekazywany co najmniej 2 punkty. Maps Static API następnie połączy ścieżkę w tych punktach w określonej kolejności. Każdy element pathPoint jest oznaczony w parametrze pathDescriptor znakiem rozdzielacza | (kreska pionowa).

Poniższy przykład pokazuje niebieską ścieżkę z przezroczystością domyślną 50% od Union Square (Nowy Jork) do Times Square (Nowy Jork).

Konkretne parametry parametru path:

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

Poniższy przykład definiuje tę samą ścieżkę, ale definiuje ciągłą czerwoną linię z przezroczystością 100%:

Parametry tego parametru (path) są następujące:

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

Następny przykład określa wielokąt obszaru Manhattanu, przekazując seria skrzyżowań jako lokalizacje:

Parametry tego parametru (path) są następujące:

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

Wyznaczamy ścieżkę jako niewidoczną, a wielokąt – 15%.

Zakodowane linie łamane

Zamiast ciągu lokalizacji możesz zadeklarować ścieżkę jako linię łamaną, używając prefiksu enc: w deklaracji lokalizacji elementu path.

Poniższy przykład przedstawia przebieg autostrady Alaska z Dawson Creek, BC do delta Junction, AK z zakodowaną łamaną:

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

Tak jak w przypadku standardowych ścieżek, zakodowane ścieżki łamane mogą także dekodować wielokąty, jeśli argument fillcolor jest przekazywany do parametru path.

W przykładzie poniżej opisano wielokąt charakterystyczny dla Brooklynu w stanie Nowy Jork:

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

Widoczne obszary

Obrazy mogą określać widoczny obszar, podając widoczne lokalizacje za pomocą parametru visible. Parametr visible instruuje usługę Static API Map, aby stworzyła mapę, tak by istniejące lokalizacje pozostały widoczne. (Parametr może być połączony z istniejącymi znacznikami lub ścieżkami, by wskazać widoczny obszar). Dzięki takiemu zdefiniowaniu widoczny obszar uniknie konieczności określania dokładnego poziomu powiększenia.

Następny przykład dotyczy mapy skupionej wokół Bostonu w stanie Massachusetts, która zawiera zarówno MIT, jak i Harvard Square w Cambridge w stanie Massachusetts:

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

Domniemane położenie

Standardowo musisz określić parametry adresu URL center i zoom, aby określić lokalizację i poziom powiększenia wygenerowanej mapy. Jeśli jednak podasz parametry markers, path lub visible, możesz pozwolić, aby interfejs statyczny interfejs API Map Google bezpośrednio określał prawidłowy środek i poziom powiększenia na podstawie oceny pozycji tych elementów.

Jeśli dostarczysz co najmniej 2 elementy, Statyczny interfejs API Map Google określi odpowiedni poziom i powiększenie, zapewniając duże marginesy zawartych elementów. Ten przykład pokazuje mapę z San Francisco, Oakland i San Jose, Kalifornia:

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

Większe rozmiary obrazów

Jeśli potrzebujesz zdjęć o rozmiarze większym niż 640 x 640 pikseli (lub 1280 x 1280 pikseli o skali 2), skontaktuj się z zespołem pomocy i podaj te informacje:

1. Przypadek użycia i powody, dla których potrzebujesz dużych obrazów.
2. niezależnie od tego, czy korzystasz z innych interfejsów Google Maps Platform API (Maps JavaScript API, Maps embed API, Maps SDK na Androida czy Maps SDK na iOS), i dlaczego nie spełniają one Twoich potrzeb.
3. zrzuty ekranu, przykłady lub przykłady wykorzystania dużych rozmiarów obrazów;
4. Szacowane miesięczne wykorzystanie zdjęć w dużych rozmiarach.

Sprawdzimy Twoje zgłoszenie na podstawie podanych przez Ciebie informacji i ustalimy, czy Twój przypadek użycia spełnia Warunki korzystania z usługi Google Maps Platform.

Maksymalny rozmiar, jakie możemy podać, to 2048 x 2048 pikseli.

Rozwiązywanie problemów i pomoc

Więcej informacji o korzystaniu z Maps Static API znajdziesz na stronie pomocy.

Interfejs Maps Static API może wyświetlać błąd lub ostrzeżenie, gdy coś pójdzie nie tak. Szczególną uwagę należy zwracać na ostrzeżenia, jeśli zauważysz, że na mapie brakuje czegoś. Warto też sprawdzić ostrzeżenia przed uruchomieniem nowej aplikacji. Ostrzeżenia mogą nie być od razu widoczne, ponieważ pojawiają się w nagłówku HTTP. Więcej informacji znajdziesz w przewodniku o błędach i ostrzeżeniach.