Wstęp
Maps Static API zwraca obraz (GIF, PNG lub JPEG) w odpowiedzi na żądanie HTTP wysłane z adresu URL. W przypadku każdego żądania możesz określić lokalizację mapy, rozmiar obrazu, poziom powiększenia, typ mapy i rozmieszczenie opcjonalnych znaczników w określonych miejscach na mapie. Znaczniki możesz też oznaczać 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.
W tym dokumencie opisujemy wymagany format adresów URL statycznego interfejsu Maps Static API i dostępne parametry. Znajdziesz w nim też porady i wskazówki dotyczące określania adresów URL.
Zanim zaczniesz
Ten dokument jest przeznaczony dla programistów witryn i aplikacji mobilnych, którzy chcą umieścić obrazy ze Static API na stronie internetowej lub w aplikacji mobilnej. Zawiera wprowadzenie do korzystania z interfejsu API oraz materiały referencyjne na temat dostępnych parametrów.
Zanim zaczniesz tworzyć interfejs Maps Static API, zapoznaj się z wymaganiami dotyczącymi uwierzytelniania (musisz mieć klucz interfejsu API) oraz informacjami o użyciu interfejsu API i rozliczeniach (musisz włączyć płatności w projekcie).
Parametry adresu URL
Adres URL statycznego interfejsu API Map Google musi mieć taką formę:
https://maps.googleapis.com/maps/api/staticmap?parameters
Jeśli dostęp do witryny jest uzyskiwany przez HTTPS, musisz wczytywać obrazy z interfejsu Maps Static API również przez HTTPS, aby uniknąć alertów bezpieczeństwa przeglądarki. Protokół HTTPS jest też zalecany, jeśli Twoje żądania zawierają poufne dane użytkownika, takie jak lokalizacja użytkownika:
https://maps.googleapis.com/maps/api/staticmap?parameters
Niezależnie od tego, czy korzystasz z protokołu HTTP, czy HTTPS, niektóre parametry adresu URL są wymagane, a niektóre opcjonalne. Zgodnie ze standardem w adresach URL wszystkie parametry są rozdzielone znakiem „&”. W tym dokumencie wymieniono listę parametrów i ich możliwe wartości.
Interfejs Maps Static API definiuje obrazy map za pomocą tych parametrów adresu URL:
Parametry lokalizacji
center(wymagany, jeśli nie ma znaczników) określa środek mapy w odległości od wszystkich jego krawędzi. Ten parametr przyjmuje lokalizację w postaci oddzielonej przecinkami pary {szerokość,długość geograficzna} (np. „40.714728,-73.998672”) lub adres w postaci ciągu znaków (np. „ratusz, wrocław, warszawa”) identyfikującą unikalną lokalizację na powierzchni Ziemi. Więcej informacji znajdziesz w artykule 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 żądanego regionu. Więcej informacji znajdziesz w artykule Poziomy powiększenia.
Parametry mapy
size(wymagany) określa prostokątne wymiary obrazu mapy. Ten parametr przyjmuje ciąg znaków w postaci{horizontal_value}x{vertical_value}. Na przykład500x400określa mapę o szerokości 500 pikseli i wysokości 400 pikseli. Na mapach mniejszych niż 180 pikseli będzie wyświetlane logo Google w zmniejszonym rozmiarze. Na ten parametr wpływa parametrscale. Ostateczny rozmiar wyjściowy jest iloczynem wartości rozmiaru i skali.scale(opcjonalny) określa liczbę zwracanych pikseli.scale=2zwraca 2 razy więcej pikseli niżscale=1przy zachowaniu tego samego obszaru zasięgu i poziomu szczegółów (tj. zawartość mapy nie ulega zmianie). Jest to przydatne podczas tworzenia aplikacji z myślą o wyświetlaczach o wysokiej rozdzielczości. Wartością domyślną jest1. Akceptowane wartości to1i2. Więcej informacji znajdziesz w sekcji Wartości skali.format(opcjonalny) określa format wynikowego obrazu. Domyślnie interfejs Maps Static API tworzy obrazy w formacie PNG. Dostępnych jest kilka formatów, w tym GIF, JPEG i PNG. Wybór formatu zależy od tego, w jaki sposób zamierzasz prezentować obraz. Format JPEG zwykle zapewnia większą kompresję, a GIF i PNG udostępniają więcej szczegółów. Więcej informacji znajdziesz w artykule o formatach obrazów.maptype(opcjonalny) określa typ mapy do utworzenia. Istnieje kilka możliwych wartości maptype, np.roadmap,satellite,hybriditerrain. Więcej informacji znajdziesz w artykule Mapowanie statycznego interfejsu API Map Google.language(opcjonalny) określa język, który ma być używany do wyświetlania etykiet na kafelkach mapy. Pamiętaj, że ten parametr jest obsługiwany tylko w przypadku niektórych kafelków krajów. Jeśli żądany język nie jest obsługiwany przez zestaw kafelków, będzie używany domyślny język tego zbioru.region(opcjonalny) określa odpowiednie granice do wyświetlania na podstawie wrażliwości geopolitycznej. Akceptuje kod regionu określony w postaci dwuznakowej wartości domeny ccTLD („domena najwyższego poziomu”). Sprawdź szczegóły zasięgu Google Maps Platform, aby poznać obsługiwane regiony.
Parametry funkcji
map_id(opcjonalny) określa identyfikator konkretnej mapy. Identyfikator mapy wiąże mapę z określonym stylem lub cechą i musi należeć do tego samego projektu co klucz interfejsu API użyty do jej zainicjowania. Więcej informacji znajdziesz w artykule o korzystaniu z identyfikatorów map.markers(opcjonalny) – określ co najmniej 1 znacznik, który chcesz dołączyć do zdjęcia w określonych lokalizacjach. Ten parametr przyjmuje pojedynczą definicję znacznika z parametrami rozdzielonymi pionową kreską (|). W jednym parametrzemarkersmożna umieścić wiele znaczników, o ile mają ten sam styl. Możesz dodać kolejne znaczniki różnych stylów, dodając kolejne parametrymarkers. Pamiętaj, że jeśli dostarczasz znaczniki na mapie, nie musisz określać (zwykle wymaganych) parametrówcenterizoom. Więcej informacji znajdziesz w artykule Mapowanie statycznego interfejsu API Map Google.path(opcjonalny) określa jedną ścieżkę z dwoma lub większą liczbą połączonych punktów, które są nakładane na obraz w określonych lokalizacjach. Ten parametr przyjmuje ciąg definicji punktów rozdzielonych pionową kreską (|) lub zakodowaną linię łamaną za pomocą prefiksuenc:w deklaracji lokalizacji ścieżki. Możesz podać dodatkowe ścieżki, dodając kolejne parametrypath. Pamiętaj, że jeśli podasz ścieżkę dla mapy, nie musisz określać (zwykle wymaganych) parametrówcenteranizoom. Więcej informacji znajdziesz w artykule Mapy statycznych ścieżek interfejsu API.visible(opcjonalny) określa co najmniej jedną lokalizację, która powinna pozostać widoczna na mapie, choć nie będą wyświetlane żadne znaczniki ani inne wskaźniki. Używaj tego parametru, aby mieć pewność, że określone obiekty lub lokalizacje na mapach są wyświetlane w Maps Static API.style(opcjonalny) określa styl niestandardowy, który określa wygląd danego obiektu (drogi, parki i inne obiekty) na mapie. Ten parametr przyjmuje argumentyfeatureielementokreślające cechy, których styl chcesz określić, oraz zestaw operacji dotyczących stylu, które mają zostać zastosowane do wybranych cech. Możesz podać wiele stylów, dodając dodatkowe parametrystyle. Więcej informacji znajdziesz w przewodniku po mapach ze stylami.
Klucz i parametry podpisu
key(wymagany) umożliwia monitorowanie korzystania z interfejsu API przez aplikację w konsoli Google Cloud i zapewnia, że w razie potrzeby możemy się z Tobą skontaktować w sprawie Twojej aplikacji. Więcej informacji znajdziesz w artykule Używanie kluczy interfejsu API z Maps Static API.signature(zalecane) to podpis cyfrowy używany do weryfikacji, czy wszystkie witryny generujące żądania przy użyciu Twojego klucza interfejsu API mają do tego upoważnienie. Żądania bez podpisu cyfrowego mogą zakończyć się niepowodzeniem. Więcej informacji znajdziesz w artykule na temat korzystania z podpisu cyfrowego.
Ograniczenie rozmiaru adresu URL
Adresy URL statycznego interfejsu API Map Google mogą mieć maksymalnie 16 384 znaki. W praktyce nie musisz zwykle tworzyć dłuższych adresów URL, chyba że tworzysz złożone mapy z dużą liczbą znaczników i ścieżek.
Wykorzystanie parametru
Interfejs Maps Static API jest stosunkowo łatwy w użyciu, ponieważ składa się wyłącznie z adresu URL o określonych parametrach. Ta sekcja wyjaśnia, jak używać tych parametrów do tworzenia adresów URL.
Określanie lokalizacji
Interfejs Maps Static API musi być w stanie dokładnie wskazywać lokalizacje na mapie, aby skupić się na właściwej lokalizacji (za pomocą parametru center) i/lub umieszczać wszelkie opcjonalne oznaczenia miejsc (za pomocą parametru markers) w odpowiednich lokalizacjach na mapie. Do określania tych lokalizacji w interfejsie Maps Static API używane są liczby (wartości szerokości i długości geograficznej) lub ciągi znaków (adresy). Te wartości określają lokalizację kodowaną geograficznie.
Kilka parametrów (np. markers i path) znajduje się w różnych lokalizacjach. W takich przypadkach lokalizacje są rozdzielone pionową kreską (|).
Długości i szerokości geograficzne
Długości i szerokości geograficzne definiuje się za pomocą cyfr w rozdzielanym przecinkami ciągu tekstowym z dokładnością do 6 miejsc po przecinku. Na przykład „40.714728,-73.998672” to prawidłowa wartość geokodu. Dokładność powyżej 6 miejsc po przecinku jest ignorowana.
Długość geograficzna jest określana na podstawie odległości od Greenwich (Anglii), gdzie znajduje się południk zerowy. Ponieważ Greenwich znajduje się na szerokości geograficznej 51,477222, możemy wpisać wartość center o wartości 51.477222,0, aby wyśrodkować mapę w Greenwich:
Długość i szerokość geograficzna muszą odpowiadać prawidłowej lokalizacji na powierzchni Ziemi. Szerokość geograficzna może mieć dowolną wartość z zakresu -90–90, a długość geograficzna – dowolną wartość z zakresu -180–180. Jeśli podasz nieprawidłową wartość szerokości lub długości geograficznej, Twoje żądanie zostanie odrzucone jako nieprawidłowe.
Adresy
Większość użytkowników nie mówi według szerokości i długości geograficznej – miejsca są oznaczane za pomocą adresów. Proces przekształcania adresu w punkt geograficzny jest nazywany geokodowaniem. Usługa Maps Static API może przeprowadzić geokodowanie za Ciebie, jeśli podasz prawidłowe adresy.
W każdym parametrze, w którym podajesz szerokość i długość geograficzną, możesz zamiast tego podać ciąg znaków wskazujący adres. Google przetworzy geokod z adresem i dostarczy usłudze Maps Static API wartość szerokości i długości geograficznej, którą można wykorzystać do umieszczania znaczników lub określania lokalizacji. Ciąg znaków powinien być zakodowany za pomocą adresu URL, więc adresy takie jak „Ratusz, Warszawa, Polska” powinny zostać przekonwertowane na np. „City+Hall,Nowy+Jork,NY”.
Adresy mogą odzwierciedlać dokładne lokalizacje, takie jak adresy, linie łamane (np. nazwane trasy) lub obszary wielokątne, takie jak miasta, kraje czy parki narodowe. W przypadku wyników w formacie wieloliniowym i wielokątnym serwer Maps Static API będzie używać punktu środkowego linii/obszaru jako centrum adresu. Jeśli masz wątpliwości dotyczące przetwarzania danych geograficznych adresu, możesz przetestować go za pomocą narzędzia do geokodowania.
Poniższy przykład umożliwia wygenerowanie statycznego obrazu mapy dla Berkeley, CA:
https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Poziomy powiększenia
Poziom powiększenia w Mapach Google jest liczbą całkowitą, która określa rozdzielczość bieżącego widoku. Poziom powiększenia od 0 (najniższy poziom powiększenia, dzięki któremu cały świat jest na jednej mapie widoczny na jednej mapie) oraz 21+ (od poziomu do ulic i poszczególnych budynków) jest możliwe w domyślnym widoku roadmap. Tam, gdzie dostępne są kontury budynków, 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ę ewoluowania danych.
Mapy Google ustawiają powiększenie na 0, aby objąć całą Ziemię.
Każdy kolejny poziom powiększenia podwaja precyzję w wymiarach zarówno w poziomie, jak i w pionie. Więcej informacji na ten temat znajdziesz w dokumentacji interfejsu Google Maps JavaScript API.
Uwaga: nie wszystkie poziomy powiększenia są widoczne we wszystkich lokalizacjach na Ziemi. Poziomy powiększenia mogą się różnić w zależności od lokalizacji, ponieważ dane w niektórych częściach kuli ziemskiej są bardziej szczegółowe niż w innych.
Jeśli wyślesz żądanie poziomu powiększenia, na którym nie ma żadnych fragmentów mapy, interfejs Maps Static API 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 wymagane są 2 mapy Manhattanu o tej samej wartości center, ale przy powiększeniu 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 center określa obszar zasięgu mapy. Określa też rozmiar wyjściowy mapy w pikselach po pomnożeniu przez wartość scale (domyślnie jest to 1).
Ta tabela zawiera maksymalne dopuszczalne wartości parametru size dla każdej wartości scale.
scale=1 |
scale=2 |
|---|---|
640x640 |
640x640 (zwraca 1280 x 1280 pikseli) |
W tym przykładzie żądanie „wycinka” Ziemi na równiku przy powiększeniu 1:
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 wymagana jest mała mapa o wymiarach 100 x 100 pikseli środkowana 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
Wartości skali
Parametr size interfejsu Maps Static API określa rozmiar mapy w pikselach, więc mapa z size=200x200 zostanie zwrócona jako 200 na 200 pikseli. Na monitorze komputerowym LCD, który zwykle wyświetla około 100 pikseli na cal (ppi), mapa 200 x 200 będzie miała około 2 cali w każdym wymiarze.
Jednak urządzenia mobilne coraz częściej mają ekrany o wysokiej rozdzielczości i gęstości pikseli przekraczającej 300 ppi, co oznacza, że:
- Zmniejsz rozmiar obrazu o wymiarach 200 × 200 pikseli do zaledwie 0,7 cala, tak aby etykiety i ikony były zbyt małe, aby można je było odczytać.
- Przeskaluj (powiększ) obraz, aby zwiększyć jego czytelność, co spowoduje, że obraz będzie rozmyty lub pikselowy.
| Za mały | Za zamazanie |
|---|---|
 |
 |
Jeśli tworzysz 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, aby określić rzeczywisty rozmiar wyjściowy obrazu w pikselach bez zmiany obszaru zasięgu mapy. Domyślna wartość scale wynosi 1, a dopuszczalne wartości to 1 i 2.
Na przykład wartość skali równa 2 zwróci ten sam obszar zasięgu mapy co żądanie bez określonej skali, ale z 2 razy większą liczbą pikseli w każdym wymiarze. Dotyczy to dróg i etykiet, dzięki którym są one czytelne na małych ekranach o wysokiej rozdzielczości, a także po skalowaniu przez przeglądarkę.
| 150 × 150 | 150x150&skala=2 |
|---|---|
 |
 |
Taki obraz będzie też skuteczny w przeglądarkach na komputerach, jeśli zostanie wstawiony do tagu img lub div z wysokością i szerokością ustawioną za pomocą CSS. Przeglądarka zmniejszy rozmiar obrazu do prawidłowego rozmiaru bez utraty jakości.
Tabela zawiera 3 różne żądania obrazu.
- Pierwszy to obraz o wymiarach 100 x 100 bez określonej wartości skali. Jest wyświetlany prawidłowo na komputerach, ale jest za mały do odczytania na urządzeniu mobilnym.
- Drugie podwaja rozmiar mapy. Na komputerze CSS dopasowuje go do określonego elementu
imgo wymiarach 100 x 100, ale przy zmniejszeniu obrazu drogi i etykiety stają się zbyt małe. Na urządzeniu mobilnym obraz ma właściwy rozmiar, ale drogi i etykiety są nieczytelne. - Trzecie żądanie dotyczy mapy 100 x 100 z elementem
scale=2. Obraz jest zwracany z 200 pikselami szczegółów. Komputer jest idealnie skalowany w dół, aby nie można go było odróżnić od pierwotnego żądania 100 x 100, a przeglądarka mobilna korzysta z dodatkowej rozdzielczości zwracanej przez interfejs API.
| Żądania obrazu | |||
|---|---|---|---|
| Urządzenie | 100x100 |
200x200 |
100x100&scale=2 |
| Komputer (z elementami height="100px" i width="100px" w taguimg) |
 |
 |
 |
| Wysoka rozdzielczość (symulacja) |
 |
|
|
Więcej informacji na temat tworzenia aplikacji na urządzenia mobilne i ekrany 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 tworzenia witryn internetowych o wysokiej rozdzielczości.
- Obsługa ekranów o wysokiej rozdzielczości z biblioteki dla deweloperów aplikacji na iOS.
Formaty graficzne
Obrazy mogą być zwracane w kilku popularnych formatach grafiki internetowej: GIF,
JPEG i PNG. Parametr format może mieć jedną z tych wartości:
png8lubpng(domyślnie) określa 8-bitowy format PNG.png32określa 32-bitowy format PNG.gifokreśla format GIF.jpgokreśla format kompresji JPEG.jpg-baselineokreśla format kompresji JPEG nieprogresywny.
Te przykłady żądania 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
jpg i jpg-baseline zwykle zapewniają najmniejszy rozmiar obrazu, ale są to spowodowane kompresją „stratną”, która może pogorszyć obraz. gif, png8 i png32
zapewniają bezstratną kompresję.
Większość obrazów JPEG jest progresywna, co oznacza, że wczytują się wcześniej obraz, a ich rozdzielczość jest ulepszana w miarę napływania większej ilości danych. Umożliwia to szybkie ładowanie obrazów na stronach internetowych. Jest to obecnie najpopularniejsze rozwiązanie w formacie JPEG. Niektóre formaty JPEG wymagają jednak obrazów innych niż progresywne (podstawowe). W takich przypadkach można używać formatu jpg-baseline, który nie jest progresywny.
Typy map
Maps Static API tworzy mapy w kilku formatach wymienionych poniżej:
roadmap(domyślnie) określa standardowy obraz z planu, tak jak zwykle jest on wyświetlany na stronie Map Google. Jeśli nie określono wartościmaptype, interfejs Maps Static API domyślnie wyświetla kafelkiroadmap.satelliteokreśla zdjęcie satelitarne.terrainokreśla fizyczny obraz mapy płaskiej przedstawiający ukształtowanie terenu i roślinność.hybridto połączenie zdjęcia satelitarnego i zdjęcia z planu, na którym na zdjęciach satelitarnych widoczna jest przezroczysta warstwa głównych ulic i nazw miejsc.
W tym przykładzie kodu widać różnicę między planem rozwoju a typami terenu.
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
Mapy hybrydowe wykorzystują zdjęcia satelitarne i najważniejsze obiekty z planu w celu utworzenia mapy kombinacyjnej. Poniższe 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
Mapy ze stylem
Dostosuj prezentację standardowej mapy Google, stosując własne style. Zobacz przewodnik po mapach z stylami.
Znaczniki
Parametr markers określa zestaw znaczników (pinek na mapie) w zbiorze lokalizacji. Każdy znacznik zdefiniowany w pojedynczej deklaracji markers musi mieć ten sam styl wizualny. Jeśli chcesz wyświetlać znaczniki z różnymi stylami, musisz podać w wielu parametrach markers osobne informacje o stylu.
Parametr markers przyjmuje zestaw przypisań wartości (deskryptory znaczników) w tym formacie:
markers=markerStyles|markerLocation1|
markerLocation2|... itp.
Zbiór obiektów markerStyles jest deklarowany na początku deklaracji markers i składa się z 0 lub większej liczby deskryptorów stylów rozdzielonych pionową kreską (|), po których następuje zestaw zawierający co najmniej 1 lokalizację (|).
Jako że zarówno informacje o stylu, jak i informacje o lokalizacji są rozdzielane pionową kreską, informacje o stylu muszą występować jako pierwsze we wszystkich deskryptorach. Gdy serwer Maps Static API napotka lokalizację w deskryptorze znacznika, wszystkie pozostałe parametry znaczników również są uznawane za lokalizacje.
Style znaczników
Zestaw deskryptorów stylów znaczników to seria przypisań wartości oddzielonych znakiem pionowej kreski (|). Ten deskryptor stylu definiuje atrybuty wizualne, które mają być używane podczas wyświetlania znaczników w tym deskryptorze. Te deskryptory stylów zawierają te przypisania klucz-wartość:
size:(opcjonalny) określa rozmiar znacznika z zestawu{tiny, mid, small}. Jeśli nie zostanie ustawiony żaden parametrsize, znacznik pojawi się w domyślnym (normalnym) rozmiarze.color:(opcjonalny) określa kolor 24-bitowy (np.color=0xFFFFCC) lub kolor wstępnie zdefiniowany ze zbioru{black, brown, green, purple, yellow, blue, gray, orange, red, white}.Pamiętaj, że przezroczystości (określone za pomocą 32-bitowych szesnastkowych wartości kolorów) nie są obsługiwane w przypadku znaczników, ale są obsługiwane w przypadku ścieżek.
label:(opcjonalny) określa jeden znak alfanumeryczny uppercase ze zbioru {A–Z, 0–9}. (wielkie znaki są wymagane w tej wersji interfejsu API). Pamiętaj, że znaczniki domyślne i o rozmiarzemidto jedyne znaczniki, które mogą wyświetlać parametralphanumeric-character. Znacznikitinyismallnie mogą wyświetlać znaków alfanumerycznych.
Skalowanie znacznika
Wartość scale jest mnożona przez rozmiar obrazu znacznika, aby uzyskać rzeczywisty rozmiar wyjściowy znacznika w pikselach. Domyślna wartość skali to 1, a dopuszczalne wartości to 1, 2 i 4.
Limit rozmiaru w pikselach na obrazach jest stosowany po skalowaniu. Jeśli na przykład znacznik ma ustawienie scale:2, może on być większy niż maksymalny rozmiar 4096 pikseli, pod warunkiem że zmaleje do mniej niż 4096 pikseli po odskalowaniu. Przy wyświetlaniu map w wyższej rozdzielczości możesz używać skalowania znaczników w połączeniu ze skalowaniem mapy.
Lokalizacje znaczników
Każdy deskryptor znacznika musi zawierać zestaw co najmniej jednej lokalizacji, która określa, gdzie należy umieścić znacznik na mapie. Lokalizacje można określić jako szerokość/długość geograficzną lub jako adresy. Lokalizacje są rozdzielone pionową kreską (|).
Uwaga: jeśli zdecydujesz się określić lokalizacje znaczników za pomocą metody, która wymaga geokodowania, takiej jak czytelne dla człowieka ciągi adresów lub linie łamane, w żądaniu można podać maksymalnie 15 znaczników. Ten limit dotyczy tylko lokalizacji znaczników, które wymagają geokodowania. Nie dotyczy lokalizacji znacznika podanych przy użyciu współrzędnych szerokości i długości geograficznej.
Parametry lokalizacji określają lokalizację znacznika na mapie. Jeśli lokalizacja znajduje się poza mapą, ten znacznik nie pojawi się na utworzonym obrazie, o ile podano parametry center i zoom. Jeśli jednak te parametry nie zostaną podane, serwer Maps Static API automatycznie utworzy obraz zawierający dostarczone znaczniki.
(zobacz Pozycjonowanie niejawne).
Tutaj znajdziesz przykładową deklarację znacznika. 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ć wiele parametrów markers. Ten zestaw parametrów markers definiuje 3 znaczniki: jeden niebieski znacznik oznaczony jako „S” w numerach 62.107733, -145,5419, jeden niewielki zielony znacznik w „Delta Junction, AK” i średnio żółty znacznik „C” w miejscu „Tok, AK”. Znaczniki przedstawione 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 korzystać z ikon znaczników Google, możesz użyć własnych niestandardowych ikon. Ikony niestandardowe są określane za pomocą deskryptora icon w parametrze markers. Na przykład:
markers=icon:URLofIcon|markerLocation
Określ icon za pomocą adresu URL (powinien być zakodowany). Możesz używać adresów URL utworzonych za pomocą usług skracających adresy URL, takich jak https://goo.gl. Większość usług skracania adresów URL ma zaletę polegającą na automatycznym kodowaniu adresów URL.
Możesz określić punkt zakotwiczenia ikony niestandardowej. Punkt zakotwiczenia określa sposób umieszczania ikony w odniesieniu do określonych lokalizacji markers. Domyślnie punkt zakotwiczenia ikony niestandardowej znajduje się na dole obrazu ikony. Inny punkt zakotwiczenia możesz podać za pomocą deskryptora anchor w połączeniu z elementem icon. Ustaw anchor jako punkt X lub Y ikony (np. 10,5) lub jako wstępnie zdefiniowane wyrównanie za pomocą jednej z tych wartości: top, bottom, left, right, center, topleft, topright, bottomleft lub bottomright. Na przykład:
markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2
W jednym żądaniu możesz użyć maksymalnie 5 niepowtarzalnych ikon niestandardowych. Ograniczenie to nie oznacza, że na mapie
możesz mieć tylko 5 oznaczonych lokalizacji. Każda unikalna ikona może być używana z więcej niż jedną lokalizacją markers na mapie.
Format ikony:
- Obrazy ikon mogą mieć format PNG, JPEG lub GIF, ale zalecamy użycie formatu PNG.
- Ikony mogą mieć maksymalny rozmiar 4096 pikseli (64 x 64 w przypadku obrazów kwadratowych).
Przykłady ikon niestandardowych
Przykład 1 tworzy ikony niestandardowe i umieszcza je za pomocą kotwic.
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
Przykład 2 tworzy te same ikony niestandardowe co w przykładzie 1, ale nie ustawia pozycji ikon za pomocą kotwic, bazując na domyślnej kotwicze wyśrodkowej u dołu.
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
Ścieżki interfejsu Maps Static API
Parametr path określa zbiór co najmniej 1 lokalizacji połączonej ścieżką do nakładki na obrazie mapy. Parametr path przyjmuje zestaw przypisań wartości (deskryptory ścieżki) w tym formacie:
path=pathStyles|pathLocation1|pathLocation2|... itp.
Pamiętaj, że oba punkty ścieżki są rozdzielone pionową kreską (|). Zarówno informacje o stylu, jak i informacje o punkcie są rozdzielane pionową kreską, więc informacje o stylu muszą pojawiać się jako pierwsze w każdym deskryptorze ścieżki. Gdy serwer Maps Static API napotka lokalizację w deskryptorze ścieżki, wszystkie pozostałe parametry ścieżki też są uznawane za lokalizacje.
Style ścieżki
Zbiór deskryptorów stylów ścieżki to seria przypisań wartości oddzielonych znakiem pionowej kreski (|). Ten deskryptor stylu definiuje atrybuty wizualne, które mają być używane podczas wyświetlania ścieżki. Te deskryptory stylów mają następujące przypisania klucz/wartość:
weight:(opcjonalny) określa grubość ścieżki w pikselach. Jeśli nie ustawisz żadnego parametruweight, ścieżka wyświetli się z domyślną grubością (5 pikseli).color:(opcjonalny) określa kolor w postaci 24-bitowej (np.color=0xFFFFCC) lub 32-bitowej wartości szesnastkowej (np.color=0xFFFFCCFF) albo z zestawu{black, brown, green, purple, yellow, blue, gray, orange, red, white}.Jeśli podasz 32-bitową wartość szesnastkową, ostatnie 2 znaki określają wartość 8-bitowej przezroczystości alfa. Ta wartość różni się od
00(całkowicie przezroczysta) doFF(całkowicie nieprzezroczysta). Pamiętaj, że przezroczystość ścieżek jest obsługiwana w ścieżkach, ale nie w przypadku znaczników.fillcolor:(opcjonalny) wskazuje, że ścieżka oznacza obszar wielokątny, a także określa kolor wypełnienia, który ma być używany jako nakładka w tym obszarze. Zbiór lokalizacji wymienionych poniżej nie musi stanowić „zamkniętej” pętli. Serwer Maps Static API automatycznie dołączy pierwszy i ostatni punkt. Pamiętaj jednak, że żadne linie na zewnątrz wypełnionego obszaru nie zostaną zamknięte, jeśli nie podasz tej samej lokalizacji początkowej i końcowej.- Wartość
geodesic:(opcjonalna) oznacza, że żądaną ścieżkę należy interpretować jako linię geodezyjną, która przebiega nad krzywą powierzchni Ziemi. Jeśli zasada ma wartość Fałsz, w przestrzeni ekranu ścieżka jest renderowana jako linia prosta. Wartość domyślna to fałsz.
Kilka przykładowych definicji ścieżek:
- Cienka niebieska linia, nieprzezroczystość 50%:
path=color:0x0000ff80|weight:1 - Czerwona linia ciągła:
path=color:0xff0000ff|weight:5 - Ciągła, gruba biała linia:
path=color:0xffffffff|weight:10
Te style ścieżki są opcjonalne. Jeśli chcesz użyć atrybutów domyślnych, możesz pominąć definiowanie atrybutów ścieżki. W takim przypadku pierwszy „argument” deskryptora ścieżki będzie się składał zamiast pierwszego zadeklarowanego punktu (lokalizacji).
Punkty ścieżki
Aby narysować ścieżkę, parametr path musi też zostać przekazany przez co najmniej 2 punkty. Maps Static API połączy ścieżkę wzdłuż tych punktów w określonej kolejności. Każdy element pathPoint jest opisany w elemencie pathDescriptor rozdzielony pionową kreską |.
Ten przykład pokazuje niebieską ścieżkę z domyślną nieprzezroczystością równą 50%, prowadzącą od placu Union Square w Nowym Jorku do Times Square w Nowym Jorku.
Parametr path ma te właściwości:
path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
W przykładzie poniżej zdefiniowano tę samą ścieżkę, zamiast definiować pełną czerwoną linię o 100% nieprzezroczystości:
Parametr path ma te właściwości:
path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
W kolejnym przykładzie definiujemy wielokątny obszar Manhattanu. Został on połączony z szeregiem skrzyżowań jako lokalizacjami:
Parametr path ma te właściwości:
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
Pamiętaj, że ścieżka jest niewidoczna, a obszar wielokąta ma przezroczystość 15%.
Kodowane linie łamane
Zamiast serii lokalizacji możesz zadeklarować ścieżkę jako zakodowaną linię łamaną, używając prefiksu enc: w deklaracji lokalizacji path.
Poniższy przykład przedstawia przebieg autostrady Alaska Autostrada biegnąca od Dawson Creek w Kolumbii do Delta Junction w stanie Alaska i zakodowaną linią łamaną:
https://maps.googleapis.com/maps/api/staticmap
?size=400x400¢er=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 ścieżek standardowych, zakodowane ścieżki linii łamanych mogą też wyznaczać obszary wielokątne, jeśli do parametru path zostanie przekazany argument fillcolor.
Poniższy przykład przedstawia obszar wielokątny dotyczący Brooklynu w stanie Nowy Jork:
https://maps.googleapis.com/maps/api/staticmap
?size=400x400¢er=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, określając widoczne lokalizacje za pomocą parametru visible. Parametr visible nakazuje usłudze Maps Static API utworzenie mapy tak, aby istniejące lokalizacje pozostały widoczne. (Ten parametr można też łączyć z istniejącymi znacznikami lub ścieżkami, aby zdefiniować widoczny region). Ten sposób definiowania widocznego obszaru eliminuje konieczność określania dokładnego poziomu powiększenia.
W następnym przykładzie prosimy o mapę wyśrodkowaną na Bostonie w stanie Massachusetts, na której znajdują się zarówno uczelnie 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
Bezpośrednie położenie mapy
Aby określić lokalizację i poziom powiększenia wygenerowanej mapy, musisz zwykle określić parametry adresu URL center i zoom.
Jeśli jednak podasz parametry markers, path lub visible, możesz zamiast tego pozwolić, by interfejs Maps Static API samodzielnie określił właściwe środek i poziom powiększenia na podstawie oceny pozycji tych elementów.
W przypadku dostarczenia co najmniej dwóch elementów interfejs Maps Static API określa odpowiedni środek i poziom powiększenia, zapewniając duże marginesy zawartych w nich elementów. Ten przykład wyświetla mapę obejmującą San Francisco, Oakland i San Jose, CA:
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 obrazów o rozmiarze większym niż 640 × 640 pikseli (lub 1280 × 1280 pikseli ze skalą 2), skontaktuj się z zespołem pomocy i podaj te informacje:
- Twój przypadek użycia i powody, dla których potrzebujesz obrazów w dużych rozmiarach.
- Sprawdź, czy rozważasz skorzystanie z innych interfejsów API Google Maps Platform (Map JavaScript API, Maps Embed API, Maps SDK na Androida lub Maps SDK na iOS) i dlaczego ich nie spełniają.
- Zrzuty ekranu, makiety lub przykłady wykorzystania obrazów o dużym rozmiarze.
- Szacunkowe miesięczne wykorzystanie w przypadku obrazów o dużym rozmiarze.
Rozpatrzymy Twoją prośbę na podstawie podanych przez Ciebie informacji i ustalimy, czy Twój przypadek użycia jest zgodny z Warunkami korzystania z usługi Google Maps Platform.
Maksymalny rozmiar to 2048 x 2048 pikseli.
Rozwiązywanie problemów i pomoc
Więcej informacji o korzystaniu z interfejsu Maps Static API znajdziesz na stronie pomocy.
Interfejs Maps Static API może wyświetlić błąd lub ostrzeżenie, gdy coś pójdzie nie tak. Szukaj ostrzeżeń, zwłaszcza jeśli zauważysz, że na mapie brakuje jakiegoś elementu. Warto też przed uruchomieniem nowej aplikacji sprawdzić, czy nie ma żadnych ostrzeżeń. Pamiętaj, że ostrzeżenia mogą nie być widoczne od razu, ponieważ pojawiają się w nagłówku HTTP. Więcej informacji znajdziesz w przewodniku dotyczącym błędów i ostrzeżeń.