Rozpocznij

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ład 500x400 okreś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 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 (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ą jest 1. Akceptowane wartości to 1 i 2. 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, hybrid i terrain. 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 parametrze markers można umieścić wiele znaczników, o ile mają ten sam styl. Możesz dodać kolejne znaczniki różnych stylów, dodając kolejne parametry markers. Pamiętaj, że jeśli dostarczasz znaczniki na mapie, nie musisz określać (zwykle wymaganych) parametrów center i zoom. 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ą prefiksu 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ę dla mapy, nie musisz określać (zwykle wymaganych) parametrów center ani zoom. 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 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 dodatkowe parametry style. 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:

Greenwich, Anglia

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

Berkeley, Kalifornia

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

Manhattan w odległości  Manhattan z bliska

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

Równik

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

Mała mapa równika

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 img o 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 tagu
img)
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:

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:

  • 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 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ści maptype, interfejs Maps Static API domyślnie wyświetla kafelki roadmap.
  • satellite określa zdjęcie satelitarne.
  • terrain określa fizyczny obraz mapy płaskiej przedstawiający ukształtowanie terenu i roślinność.
  • hybrid to 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

Normalna mapa Manhattanu  Mapa terenu Manhattanu

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

Mapa satelitarna Manhattanu  Mapa terenu Manhattanu

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 parametr size, 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 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 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

3 kody pocztowe z Brooklynu

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

Trzy miasteczka Alaski, różne znaczniki

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

Trzy australijskie miasta, różne niestandardowe ikony z kotwicami.

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

Trzy australijskie miasta, różne ikony niestandardowe z domyślnym pozycjonowaniem.

Ś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 parametru weight, ś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) do FF (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.

Ścieżka od Union Sq do Times Sq

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:

Ścieżka od Union Sq do Times Sq

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:

Ścieżka od Union Sq do Times Sq

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&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

Droga Alaska

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&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

Polyline zakodowane na Brooklynie z podpisem

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

Mapa Cambridge

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

Mapa drogowa

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:

  1. Twój przypadek użycia i powody, dla których potrzebujesz obrazów w dużych rozmiarach.
  2. 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ą.
  3. Zrzuty ekranu, makiety lub przykłady wykorzystania obrazów o dużym rozmiarze.
  4. 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ń.