Rozpocznij

Wprowadzenie

Interfejs Maps Static API zwraca obraz (w formacie 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 oraz położenie 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 API Map Google 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 statycznego interfejsu API Map Google na stronie internetowej lub w aplikacji mobilnej. Zawiera on wprowadzenie do korzystania z interfejsu API oraz materiały na temat dostępnych parametrów.

Zanim zaczniesz programować z użyciem Maps Static API, zapoznaj się z wymaganiami dotyczącymi uwierzytelniania (potrzebny jest klucz interfejsu API) oraz informacjami o korzystaniu z interfejsu API i rozliczeniach (musisz włączyć płatności w projekcie).

Parametry adresu URL

Adres URL statycznego interfejsu API Map Google musi mieć format:

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

Jeśli dostęp do Twojej witryny uzyskuje się przez protokół HTTPS, musisz też wczytywać obrazy interfejsu Maps Static API przez HTTPS, aby uniknąć alertów dotyczących bezpieczeństwa przeglądarki. Protokół HTTPS jest też zalecany, jeśli żądania zawierają poufne dane użytkownika, takie jak lokalizacja:

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. Tak jak w przypadku adresów URL, wszystkie parametry są rozdzielone znakiem „&”. W tym dokumencie wymieniliśmy listę parametrów i ich możliwe wartości.

Interfejs Maps Static API definiuje obrazy map przy użyciu 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 krawędzi mapy. 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 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 żą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ład 500x400 określa mapę o szerokości 500 pikseli i wysokości 400 pikseli. W mapach mniejszych niż 180 pikseli będzie wyświetlane logo Google w zmniejszonym rozmiarze. Na ten parametr wpływa parametr scale. Ostateczny rozmiar wyjściowy jest iloczynem wartości rozmiaru i skali.
• scale (opcjonalny) określa liczbę zwracanych pikseli. scale=2 zwraca 2 razy więcej pikseli niż scale=1 przy zachowaniu tego samego obszaru zasięgu i poziomu szczegółów (tzn. zawartości mapy się nie zmienia). Jest to przydatne podczas programowania na potrzeby wyświetlaczy o wysokiej rozdzielczości. Wartością domyślną jest 1. Akceptowane wartości to 1 i 2. Więcej informacji znajdziesz w sekcji Wartości skalowania.
• 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, jak zamierzasz zaprezentować obraz. JPEG zwykle zapewnia większą kompresję, natomiast GIF i PNG oferują 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 typu mapy, w tym roadmap, satellite, hybrid i terrain. Więcej informacji znajdziesz na stronie Mapy statycznego interfejsu API Map Google.
• language (opcjonalny) określa język, który będzie 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 w przypadku danego zestawu, zostanie użyty 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 jako dwuznakową wartość domeny ccTLD („domena najwyższego poziomu”). Informacje o obsługiwanych regionach znajdziesz na stronie Szczegóły zasięgu Google Maps Platform.

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 zainicjowania mapy. Więcej informacji znajdziesz w artykule Korzystanie z identyfikatorów map.
• markers (opcjonalny) – określ co najmniej 1 znacznik, który będzie dołączany do obrazu w określonych lokalizacjach. Ten parametr przyjmuje jedną definicję znacznika z parametrami rozdzielonymi pionową kreską (|). W jednym parametrze markers można umieścić wiele znaczników, o ile będą mieć ten sam styl. Możesz dodać kolejne znaczniki o różnych stylach, dodając kolejne parametry markers. Pamiętaj, że jeśli podajesz znaczniki na mapie, nie musisz określać (zwykle wymaganych) parametrów center i zoom. Więcej informacji znajdziesz w artykule Automatyczne znaczniki interfejsu API Map Google.
• path (opcjonalny) określa 1 ścieżkę złożoną z 2 lub większej liczby połączonych punktów, które są nałożone na obraz w określonych lokalizacjach. Ten parametr to ciąg definicji punktów rozdzielonych pionową kreską (|) lub zakodowana linia łamana z prefiksem enc: w deklaracji lokalizacji ścieżki. Możesz podać dodatkowe ścieżki, dodając kolejne parametry path. Pamiętaj, że jeśli podasz ścieżkę na potrzeby mapy, nie musisz określać (normalnie wymaganych) parametrów center i zoom. Więcej informacji znajdziesz w artykule Statyczne ścieżki interfejsu API Map Google.
• visible (opcjonalny) określa co najmniej jedną lokalizację, która powinna pozostać widoczna na mapie, ale nie będą wyświetlane żadne znaczniki ani inne wskaźniki. Użyj 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 zmienia wygląd danego obiektu (drogi, parki i inne obiekty) na mapie. Ten parametr przyjmuje argumenty feature i element okreś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 kolejne parametry style. Więcej informacji znajdziesz w przewodniku po mapach z stylami.

Klucz i parametry podpisu

• key (wymagany) umożliwia monitorowanie wykorzystania interfejsu API aplikacji w konsoli Google Cloud i zapewnia, że w razie potrzeby Google może się z Tobą kontaktować w sprawie Twojej aplikacji. Więcej informacji znajdziesz w artykule na temat używania kluczy interfejsu API w interfejsie Maps Static API.
• signature (zalecany) to podpis cyfrowy używany do sprawdzania, czy wszystkie witryny generujące żądania korzystające z Twojego klucza interfejsu API są do tego uprawnione. Żądania bez podpisu cyfrowego mogą zakończyć się niepowodzeniem. Więcej informacji znajdziesz w artykule Korzystanie z podpisu cyfrowego.

Ograniczenie rozmiaru adresu URL

Adresy URL statycznego interfejsu API Map Google mogą mieć maksymalnie 16 384 znaki. W praktyce dłuższe adresy URL prawdopodobnie nie będą potrzebne, chyba że tworzysz złożone mapy z dużą liczbą znaczników i ścieżek.

Wykorzystanie parametrów

Interfejs Maps Static API jest stosunkowo łatwy w użyciu, ponieważ składa się wyłącznie z adresu URL o określonych parametrach. W tej sekcji dowiesz się, jak używać tych parametrów do tworzenia adresów URL.

Określanie lokalizacji

Interfejs Maps Static API musi być w stanie dokładnie rozpoznawać lokalizacje na mapie, tak aby była ona we właściwym miejscu (za pomocą parametru center) i/lub umieszczane na niej opcjonalne oznaczenia miejsc (za pomocą parametru markers). Do określania tych lokalizacji interfejs Maps Static API wykorzystuje liczby (wartości szerokości i długości geograficznej) lub ciągi znaków (adresy). Te wartości identyfikują lokalizację kodowaną geograficznie.

Kilka parametrów (np. markers i path) znajduje się w wielu lokalizacjach. W takich przypadkach lokalizacje są oddzielone pionową kreską (|).

Długość i szerokość geograficzna

Długości i szerokości geograficznej definiuje się za pomocą cyfr 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ść geokodu. Dokładność powyżej 6 miejsc po przecinku jest ignorowana.

Długość geograficzna zależy od odległości od Greenwich w Anglii, gdzie znajduje się południk zerowy. Ponieważ Greenwich leży na szerokości geograficznej 51,477222, możemy wpisać wartość 51.477222,0 w polu center, aby wyśrodkować mapę na Greenwich:

Długość i szerokość geograficzna 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 – z zakresu od -180 do 180. Jeśli podasz nieprawidłową wartość szerokości lub długości geograficznej, Twoje żądanie zostanie odrzucone jako nieprawidłowe.

Adresy

Większość osób nie używa szerokości i długości geograficznej – lokalizacje są określane za pomocą adresów. Proces przekształcania adresu w punkt geograficzny nazywany jest geokodowaniem, a 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 przekoduje adres i udostępni usłudze Maps Static API wartość długości/szerokości geograficznej, którą można wykorzystać do umieszczania znaczników lub określania lokalizacji. Ciąg powinien być zakodowany za pomocą adresu URL, więc adresy takie jak „City Hall, New York, NY” powinny zostać przekonwertowane na np. „City+Hall,New+York,NY”.

Adresy mogą odzwierciedlać dokładne lokalizacje, takie jak adresy, linie łamane (np. oznaczone trasy) lub obszary wielokątne, takie jak miasta, kraje czy parki narodowe. W przypadku wyników wieloliniowych i wielokątnych serwer Maps Static API wykorzysta punkt środkowy linii/obszaru jako centrum adresu. Jeśli masz wątpliwości dotyczące geokodowania adresu, możesz przetestować go za pomocą tego narzędzia do geokodowania.

Ten przykład generuje statyczny obraz 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 mapy w Mapach Google to liczba całkowita, która określa rozdzielczość bieżącego widoku. W domyślnym widoku roadmap dostępne są poziomy powiększenia od 0 (najniższy poziom powiększenia, na którym cały świat widać na jednej mapie) i 21+ (aż do ulic i poszczególnych budynków). Kontury budynków (jeśli są dostępne) pojawią się na mapie w obszarze powiększenia 17. Wartość ta różni się w zależności od obszaru i może się zmieniać w miarę ewoluowania danych.

Mapy Google ustawiają poziom powiększenia 0 tak, aby objąć całą Ziemię. Każdy kolejny poziom powiększenia zwiększa precyzję zarówno w wymiarach poziomych, jak i pionowych. Więcej informacji o tym, jak to zrobić, znajdziesz w dokumentacji interfejsu Google Maps JavaScript API.

Uwaga: nie wszystkie poziomy powiększenia są widoczne we wszystkich lokalizacjach na Ziemi. Poziomy powiększenia różnią się w zależności od lokalizacji, ponieważ w niektórych częściach kuli ziemskiej dane 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 żądamy 2 map Manhattanu o tej samej wartości center, ale przy powiększeniu odpowiednio 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 wynosi ona 1).

Ta tabela przedstawia maksymalne dozwolone wartości parametru size przy 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 na 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 skalowania

Parametr size interfejsu Maps Static API określa rozmiar mapy w pikselach, więc mapa z size=200x200 zostanie zwrócona jako 200 x 200 pikseli. Na monitorze LCD, który zwykle wyświetla około 100 pikseli na cal (ppi), mapa 200 x 200 będzie mieć 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 za małe, aby można je było odczytać.
• Skaluj (powiększa) obraz, by poprawić jego czytelność, przez co obraz będzie rozmyty lub pikselowy.

Za mały	Zamazane

Jeśli tworzysz strony na urządzenia mobilne, możesz używać parametru scale interfejsu API, aby zwracać obrazy map w wyższej rozdzielczości, co rozwiązuje 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 spowoduje zwrócenie tego samego obszaru zasięgu 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 małych ekranach o wysokiej rozdzielczości, a także po skalowaniu przez przeglądarkę.

150x150	150x150&skala=2

Taki obraz będzie też skuteczny w przeglądarkach na komputery, jeśli zostanie wstawiony do tagu img lub div o wysokości i szerokości ustawionej za pomocą CSS. Przeglądarka zmniejszy rozmiar obrazu do właściwego rozmiaru bez utraty jakości.

Ta tabela zawiera 3 różne żądania obrazu.

• Pierwszy dotyczy obrazu o wymiarach 100 x 100 bez określonej wartości skali. Wyświetla się prawidłowo na komputerze, ale jest za mały, aby odczytać go na urządzeniu mobilnym.
• Spowoduje to podwojenie rozmiaru mapy. Na komputerze CSS dopasowuje go do określonego elementu img o wymiarach 100 x 100, ale po zmniejszeniu obrazu drogi i etykiety stają się za 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 scale=2. Obraz jest zwracany z 200 pikselami szczegółów. Komputer skaluje go w dół idealnie, dzięki czemu nie można go odróżnić od pierwotnego żądania 100 × 100, a przeglądarka mobilna korzysta z dodatkowej rozdzielczości zwracanej przez interfejs API.

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

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 w bibliotece programistów 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ślnie) 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 nieprogresywny format kompresji JPEG.

Te przykłady żądają 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

Pliki jpg i jpg-baseline zwykle mają najmniejszy rozmiar, jednak dzięki skompresowaniu „stratnym”, który może pogorszyć jego jakość. gif, png8 i png32 zapewniają kompresję bezstratną.

Większość obrazów JPEG jest progresywna, co oznacza, że wczytują się wcześniej obraz o grubszym stopniu, a w miarę napływu danych ulepsza się ich rozdzielczość. Umożliwia to szybkie wczytywanie obrazów na stronach internetowych. Jest to najpopularniejsze rozwiązanie w przypadku formatu JPEG. Jednak niektóre zastosowania formatu JPEG wymagają obrazów nieprogresywnych (podstawowych). W takich przypadkach można użyć formatu jpg-baseline, który nie jest progresywny.

Typy map

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

• roadmap (domyślnie) określa standardowy obraz z planu rozwoju, który jest zwykle wyświetlany na stronie Map Google. Jeśli nie określono wartości maptype, interfejs Maps Static API domyślnie udostępnia kafelki roadmap.
• satellite określa zdjęcie satelitarne.
• terrain określa fizyczny obraz mapy płaskorzeźby przedstawiający ukształtowanie terenu i roślinność.
• hybrid to połączenie obrazu satelitarnego i zdjęcia z planu, czyli przezroczystej warstwy głównych ulic i nazw miejsc na zdjęciach satelitarnych.

W tym przykładzie kodu widać różnicę między planem rozwoju a typem 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 tworzą mapę kombinowaną na podstawie zdjęć satelitarnych i ważnych elementów planu. W przykładach poniżej widać 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 z własnym stylem

Dostosuj prezentację standardowej mapy Google, stosując własne style. Zobacz przewodnik po mapach z stylami.

Znaczniki

Parametr markers określa zestaw co najmniej 1 znacznika (pinka 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ć kilka parametrów markers z oddzielnymi informacjami o stylu.

Parametr markers przyjmuje zestaw przypisań wartości (deskryptory znaczników) w tym formacie:

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

Zbiór 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 czym następuje zestaw lokalizacji rozdzielonych pionową kreską (|).

Ponieważ zarówno informacje o stylu, jak i informacje o lokalizacji są rozdzielane pionową kreską, informacje o stylu muszą pojawić się na pierwszym miejscu we wszystkich deskryptorach znaczników. Gdy serwer Maps Static API napotka określoną lokalizację w deskryptorze znacznika, wszystkie pozostałe parametry znacznika również są uznawane za lokalizacje.

Style znaczników

Zbiór deskryptorów stylów znaczników to seria przypisań wartości rozdzielonych 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ą następujące przypisania klucz/wartość:

• size: (opcjonalny) określa rozmiar znacznika ze zbioru {tiny, mid, small}. Jeśli nie ustawiono żadnego parametru size, znacznik będzie wyświetlany w domyślnym (normalnym) rozmiarze.

• color: (opcjonalny) określa kolor 24-bitowy (przykład: 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 koloru) nie są obsługiwane w znacznikach, chociaż są obsługiwane w przypadku ścieżek.

• label: (opcjonalny) określa jeden znak alfanumeryczny wielkich liter ze zbioru {A–Z, 0–9}. (wielkie litery są wymagane w tej wersji interfejsu API). Pamiętaj, że znaczniki domyślne i o rozmiarze mid to jedyne znaczniki, które mogą wyświetlać parametr alphanumeric-character. Znaczniki tiny i small nie 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 akceptowane wartości to 1, 2 i 4.

Limit rozmiaru obrazów w pikselach zostanie zastosowany po zastosowaniu skalowania. Jeśli na przykład znacznik ma wartość scale:2, może on być większy niż maksymalny rozmiar 4096 pikseli, pod warunkiem że po przeskalowaniu zostanie zredukowany do mniej niż 4096 pikseli. Przy wyświetlaniu map w wyższej rozdzielczości używaj skalowania znaczników w połączeniu ze skalowaniem map.

Lokalizacje znaczników

Każdy deskryptor znacznika musi zawierać zestaw zawierający co najmniej jedną lokalizację określającą miejsce jego umieszczenia na mapie. Lokalizacje te można określić jako szerokość/długość geograficzną lub jako adresy. Lokalizacje są rozdzielane pionową kreską (|).

Uwaga: jeśli zdecydujesz się określić lokalizacje znaczników za pomocą metody, która wymaga geokodowania, np. w postaci czytelnych dla ludzi ciągów adresowych lub linii łamanych, w żądaniu można przesłać maksymalnie 15 znaczników. Ten limit dotyczy tylko lokalizacji znaczników, które wymagają geokodowania. Nie dotyczy to lokalizacji znaczników określonych za pomocą współrzędnych geograficznych.

Parametry lokalizacji określają lokalizację znacznika na mapie. Jeśli lokalizacja znajduje się poza mapą, znacznik nie pojawi się na skonstruowanym obrazie, o ile podano parametry center i zoom. Jeśli jednak nie podasz tych parametrów, serwer Maps Static API automatycznie utworzy obraz zawierający dostarczone znaczniki. (Patrz: Pozycjonowanie niejawne).

Tutaj znajdziesz przykładową deklarację dotyczącą znacznika. Pamiętaj, ż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, trzeba podać wiele parametrów markers. Ten zestaw parametrów markers definiuje trzy znaczniki: jeden niebieski znacznik oznaczony jako „S” na stronach 62,107733, -145,5419, jeden mały zielony znacznik w „Delta Junction, AK” i jeden średniej wielkości żółty znacznik „C” w miejscu „Tok, AK”. Znaczniki pokazane 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. 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 przez usługi skracające adresy, takie jak https://goo.gl. Większość usług do skracania adresów URL ma zaletę automatycznego kodowania 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 środku u dołu obrazu ikony. Możesz podać inny punkt zakotwiczenia, używając deskryptora anchor w połączeniu z icon. Ustaw anchor jako punkt X,y ikony (np. 10,5) lub jako wyrównanie wstępnie zdefiniowane 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 unikalnych ikon niestandardowych. To ograniczenie nie oznacza, że na mapie można mieć maksymalnie 5 oznaczonych lokalizacji. Każdej niepowtarzalnej ikony można używać z więcej niż jedną lokalizacją markers na mapie.

Format ikon:

• Obrazy ikon mogą być w formacie PNG, JPEG lub GIF, ale zalecamy ten format.
• 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 określa ich położenie 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 ich pozycji za pomocą kotwic, ponieważ korzysta z domyślnej kotwicy pośrodku dolnej.

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 statycznego interfejsu API Map Google

Parametr path określa zbiór jednej lub kilku lokalizacji połączonych ś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.

Zwróć uwagę, że oba punkty ścieżki są oddzielone od siebie znakiem pionowej kreski (|). Ponieważ zarówno informacje o stylu, jak i informacje o punkcie są rozdzielane pionową kreską, informacje o stylu muszą pojawić 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 również są uznawane za lokalizacje.

Style ścieżki

Zbiór deskryptorów stylu ścieżki to seria przypisań wartości rozdzielonych znakiem pionowej kreski (|). Ten deskryptor stylu definiuje atrybuty wizualne, które mają być używane przy wyświetlaniu ścieżki. Te deskryptory stylów obejmują te przypisania klucz/wartość:

• weight: (opcjonalny) określa grubość ścieżki w pikselach. Jeśli nie ustawiono parametru weight, ścieżka ma domyślną grubość (5 pikseli).

• color: (opcjonalny) określa kolor w postaci 24-bitowej (przykład: color=0xFFFFCC), 32-bitowej wartości szesnastkowej (przykład: color=0xFFFFCCFF) lub zestawu {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Jeśli podasz 32-bitową wartość szesnastkową, ostatnie 2 znaki określają 8-bitową wartość przezroczystości alfa. Ta wartość różni się od 00 (całkowicie przezroczysta) do FF (całkowicie nieprzezroczysta). Pamiętaj, że przezroczystość jest obsługiwana w ścieżkach, ale nie w przypadku znaczników.

• fillcolor: (opcjonalny) oznacza, że ścieżka oznacza obszar wielokątny, a także kolor wypełnienia, który ma być używany jako nakładka w tym obszarze. Zbiór lokalizacji wymienionych poniżej nie musi być „zamkniętą” pętlą. Serwer Maps Static API automatycznie połączy pierwszy i ostatni punkt. Pamiętaj jednak, że żadne kreski na zewnątrz wypełnionego obszaru nie zostaną zamknięte, jeśli nie podasz tego samego położenia początkowego i końcowego.
• geodesic: (opcjonalny) oznacza, że żądaną ścieżkę należy interpretować jako linię geodezyjną, która przebiega zgodnie z krzywizm Ziemi. Jeśli zasada ma wartość Fałsz, ścieżka jest renderowana jako linia prosta w obszarze ekranu. Wartość domyślna to fałsz.

Przykładowe definicje ścieżek:

• Cienka niebieska linia, nieprzezroczystość 50%: path=color:0x0000ff80|weight:1
• Ciągła czerwona linia: 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 wymagane są atrybuty domyślne, możesz pominąć ich definiowanie. W takim przypadku zamiast pierwszego zadeklarowanego punktu (lokalizacji) zostanie utworzony pierwszy „argument” deskryptora ścieżki.

Punkty ścieżki

Aby narysować ścieżkę, parametr path musi też przechodzić 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 oznaczony w pathDescriptor i oddzielony znakiem | (pionową kreską).

Poniższy przykład pokazuje niebieską ścieżkę z domyślnym przezroczystością ustawioną na 50% od placu Union Square w stanie Nowy Jork do Times Square w stanie Nowy Jork.

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 pokazuje tę samą ścieżkę, zamiast tego definiującą ciągłą czerwoną linię o 100% nieprzezroczystości:

Parametry tego parametru path:

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

W następnym przykładzie określono wielokątny obszar Manhattanu i przekazano serię skrzyżowań jako lokalizacje:

Parametry tego parametru path:

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ątny ma przezroczystość na 15%.

Zakodowane linie łamane

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

W tym przykładzie ukazano przebieg drogi krajowej nr 202: od Dawson Creek w Karolinie Południowej do Delta Junction w stanie Alaska, zakodowana linią ł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 ścieżek standardowych, zakodowane ścieżki linii łamanych mogą też oddzielić obszary wielokątne, jeśli do parametru path zostanie przekazany argument fillcolor.

Poniższy przykład przedstawia wielokątny obszar 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, określając widoczne lokalizacje za pomocą parametru visible. Parametr visible nakazuje usłudze Maps Static API utworzenie mapy w taki sposób, aby istniejące lokalizacje pozostały widoczne. (Ten parametr można też łączyć z dotychczasowymi znacznikami lub ścieżkami, aby zdefiniować widoczny region). Ten sposób definiowania widocznego obszaru eliminuje potrzebę określenia dokładnego poziomu powiększenia.

W następnym przykładzie prosimy o mapę skupioną na Bostonie w stanie Massachusetts obejmującym 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

pośrednie położenie mapy,

Normalnie, aby określić lokalizację i poziom powiększenia wygenerowanej mapy, musisz określić parametry adresu URL center i zoom. Jeśli jednak podasz parametry markers, path lub visible, możesz zamiast tego pozwolić interfejsowi Maps Static API na automatyczne określenie właściwego środka i poziomu powiększenia na podstawie oceny pozycji tych elementów.

Jeśli dostarczysz co najmniej 2 elementy, interfejs Maps Static API określi odpowiedni poziom wyśrodkowania i powiększenia, zapewniając duże marginesy dla zawartych w nich elementów. Ten przykład wyświetla mapę obejmującą 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 ze skalą 2), skontaktuj się z zespołem pomocy i podaj te informacje:

1. Twój przypadek użycia i powody, dla których potrzebujesz obrazów w dużym rozmiarze.
2. Rozważ użycie innych interfejsów API Google Maps Platform (Map JavaScript API, Maps Embed API, Maps SDK na Androida lub Maps SDK na iOS) i dlaczego nie odpowiadają one Twoim potrzebom.
3. Zrzuty ekranu, makiety lub przykłady tego, jak będziesz używać obrazów o dużym rozmiarze.
4. Szacunkowe miesięczne wykorzystanie w przypadku obrazów o dużym rozmiarze.

Na podstawie podanych przez Ciebie informacji rozpatrzymy Twoją prośbę 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. W szczególności należy sprawdzić ostrzeżenia, jeśli zauważysz, że na mapie brakuje jakichś elementów. Warto też sprawdzić ostrzeżenia przed uruchomieniem nowej aplikacji. Pamiętaj, że ostrzeżenia mogą nie być widoczne od razu, ponieważ pojawiają się w nagłówku HTTP. Więcej informacji znajdziesz w przewodniku po błędach i ostrzeżeniach.