Rozpocznij

Deweloperzy z Europejskiego Obszaru Gospodarczego

Wprowadzenie

Maps Static API zwraca obraz (GIF, PNG lub JPEG) w odpowiedzi na żądanie HTTP wysłane za pomocą adresu URL. W każdym żądaniu możesz określić lokalizację mapy, rozmiar obrazu, poziom powiększenia, typ mapy i umiejscowienie opcjonalnych znaczników w lokalizacjach na mapie. Możesz też oznaczyć znaczniki znakami alfanumerycznymi.

Obraz Maps Static API jest umieszczony w atrybucie src tagu <img> lub jego odpowiedniku w innych językach programowania.

W tym dokumencie opisujemy wymagany format adresów URL interfejsu Maps Static API i dostępne parametry. Przedstawiamy też kilka porad i wskazówek dotyczących określania adresów URL.

Zanim zaczniesz

Ten dokument jest przeznaczony dla deweloperów stron internetowych i aplikacji mobilnych, którzy chcą umieszczać obrazy z Maps Static API na stronie internetowej lub w aplikacji mobilnej. Zawiera wprowadzenie do korzystania z interfejsu API i materiały referencyjne dotyczące dostępnych parametrów.

Zanim zaczniesz tworzyć aplikacje za pomocą Maps Static API, zapoznaj się z wymaganiami dotyczącymi uwierzytelniania (potrzebujesz klucza interfejsu API) oraz informacjami o  korzystaniu z interfejsu API i płatnościach (musisz włączyć płatności w projekcie).

Parametry w URL-ach

Adres URL interfejsu Maps Static API musi mieć następującą postać:

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

Jeśli Twoja witryna jest dostępna przez HTTPS, musisz też wczytywać obrazy Maps Static API przez HTTPS, aby uniknąć alertów bezpieczeństwa przeglądarki. Protokół HTTPS jest też zalecany, jeśli żądania zawierają informacje poufne, takie jak lokalizacja użytkownika:

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

Niezależnie od tego, czy używasz protokołu HTTP czy HTTPS, niektóre parametry adresu URL są wymagane, a inne opcjonalne. Zgodnie ze standardem adresów URL wszystkie parametry są rozdzielone znakiem ampersand (&). Lista parametrów i ich możliwych wartości znajduje się w tym dokumencie.

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, który jest równo oddalony od wszystkich jej krawędzi. Ten parametr przyjmuje lokalizację jako parę {szerokość,długość geograficzna} rozdzieloną przecinkami (np. „40.714728,-73.998672”) lub ciąg znaków adresu (np. „ratusz, nowy jork, ny”) identyfikujący unikalną lokalizację na kuli ziemskiej. Więcej informacji znajdziesz w artykule Lokalizacje.
  • zoom (wymagany, jeśli nie ma znaczników) określa poziom powiększenia mapy. Ten parametr przyjmuje wartość liczbową odpowiadającą poziomowi powiększenia wybranego regionu. Więcej informacji znajdziesz w sekcji Poziomy powiększenia.

Parametry mapy

  • size (wymagany) określa prostokątne wymiary obrazu mapy. Ten parametr przyjmuje ciąg znaków w formacie {horizontal_value}x{vertical_value}. Na przykład 500x400 definiuje mapę o szerokości 500 pikseli i wysokości 400 pikseli. Na mapach o szerokości mniejszej niż 180 pikseli wyświetlane jest logo Google o zmniejszonym rozmiarze. Na ten parametr wpływa parametr scale. Ostateczny rozmiar wyjściowy jest iloczynem wartości rozmiaru i skali.
  • scale (opcjonalny) wpływa na liczbę zwracanych pikseli. scale=2 zwraca 2 razy więcej pikseli niż scale=1, zachowując ten sam obsługiwany obszar i poziom szczegółowości (czyli zawartość mapy się nie zmienia). Jest to przydatne podczas tworzenia aplikacji na wyświetlacze 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 PNG. Dostępnych jest kilka formatów, w tym GIF, JPEG i PNG. Użyty format zależy od tego, jak chcesz zaprezentować obraz. JPEG zwykle zapewnia większą kompresję, a GIF i PNG – większą szczegółowość. Więcej informacji znajdziesz w artykule Formaty plików graficznych.
  • maptype (opcjonalny) określa typ mapy do utworzenia. Istnieje kilka możliwych wartości maptype, w tym roadmap, satellite, hybrid i terrain. Więcej informacji znajdziesz w artykule Typy map w Maps Static API.
  • colorscheme (opcjonalny) określa schemat kolorów mapy. Akceptowane wartości to light (domyślna) i dark. Ciemny schemat kolorów dotyczy typów map roadmap i terrain. Więcej informacji znajdziesz w artykule Tryby i typy map.
  • language (opcjonalny) określa język, w którym mają być wyświetlane etykiety na kafelkach mapy. Pamiętaj, że ten parametr jest obsługiwany tylko w przypadku niektórych kafelków kraju. Jeśli dany język nie jest obsługiwany w przypadku zestawu kafelków, zostanie użyty domyślny język tego zestawu.
  • region (opcjonalny) określa odpowiednie granice do wyświetlenia na podstawie uwarunkowań geopolitycznych. Akceptuje kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Obsługiwane regiony znajdziesz w szczegółach 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 funkcją i musi należeć do tego samego projektu co klucz interfejsu API używany do inicjowania mapy. Więcej informacji znajdziesz w artykule Używanie identyfikatorów map.
  • markers (opcjonalnie) definiuje co najmniej 1 znacznik, który ma zostać dołączony do obrazu w określonych lokalizacjach. Ten parametr przyjmuje pojedynczą definicję znacznika z parametrami oddzielonymi znakiem kreski pionowej (|). W ramach tego samego parametru markers można umieścić wiele znaczników, o ile mają ten sam styl. Możesz dodać kolejne znaczniki o różnych stylach, dodając kolejne parametry markers. Pamiętaj, że jeśli podasz znaczniki mapy, nie musisz określać parametrów center i zoom (które zwykle są wymagane). Więcej informacji znajdziesz w artykule Znaczniki interfejsu Maps Static API.
  • path (opcjonalny) definiuje pojedynczą ścieżkę składającą się z co najmniej 2 połączonych punktów, która ma zostać nałożona na obraz w określonych lokalizacjach. Ten parametr przyjmuje ciąg definicji punktów rozdzielonych znakiem kreski pionowej (|) lub zakodowaną linię łamaną 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ę do mapy, nie musisz określać (zwykle wymaganych) parametrów center i zoom. Więcej informacji znajdziesz w artykule Ścieżki w Maps Static API.
  • visible (opcjonalny) określa co najmniej 1 lokalizację, która powinna pozostać widoczna na mapie, chociaż nie będą wyświetlane żadne znaczniki ani inne wskaźniki. Użyj tego parametru, aby mieć pewność, że określone funkcje lub lokalizacje na mapie są wyświetlane w Maps Static API.
  • style (opcjonalny) definiuje styl niestandardowy, który zmienia sposób prezentacji określonego elementu mapy (dróg, parków i innych obiektów). Ten parametr przyjmuje argumenty feature i element, które określają elementy do stylizacji, oraz zestaw operacji stylizacji, które mają zostać zastosowane do wybranych elementów. Możesz podać wiele stylów, dodając kolejne parametry style. Więcej informacji znajdziesz w przewodniku po mapach z własnym stylem.

Parametry klucza i podpisu

  • key (wymagany) umożliwia monitorowanie wykorzystania interfejsu API aplikacji w konsoli Google Cloud i zapewnia, że w razie potrzeby Google może skontaktować się z Tobą w sprawie aplikacji. Więcej informacji znajdziesz w artykule Używanie kluczy interfejsu API z Maps Static API.
  • signature (zalecany) to podpis cyfrowy używany do sprawdzania, czy każda witryna generująca żądania za pomocą Twojego klucza interfejsu API ma do tego uprawnienia. Żądania bez podpisu cyfrowego mogą się nie powieść. Więcej informacji znajdziesz w artykule Używanie podpisu cyfrowego.

Ograniczenie rozmiaru adresu URL

Adresy URL interfejsu Maps Static API mogą mieć maksymalnie 16 384 znaki. W praktyce prawdopodobnie nie będziesz potrzebować adresów URL dłuższych niż ta wartość, chyba że tworzysz skomplikowane mapy z dużą liczbą znaczników i ścieżek.

Użycie parametrów

Interfejs Maps Static API jest stosunkowo łatwy w użyciu, ponieważ składa się wyłącznie ze sparametryzowanego adresu URL. W tej sekcji wyjaśniamy, jak używać tych parametrów do tworzenia adresów URL.

Określanie lokalizacji

Interfejs Maps Static API musi być w stanie precyzyjnie identyfikować lokalizacje na mapie, aby ustawić mapę na właściwą lokalizację (za pomocą parametru center) lub umieścić na mapie opcjonalne oznaczenia miejsc (za pomocą parametru markers). Maps Static API używa liczb (wartości szerokości i długości geograficznej) lub ciągów znaków (adresów) do określania tych lokalizacji. Te wartości identyfikują lokalizację z kodem geograficznym.

Kilka parametrów (takich jak markers i path) może przyjmować wiele lokalizacji. W takich przypadkach lokalizacje są rozdzielone znakiem kreski pionowej (|).

szerokości i długości geograficzne,

Szerokość i długość geograficzna są określane za pomocą liczb w ciągu tekstowym rozdzielonym przecinkami, z dokładnością do 6 miejsc po przecinku. Na przykład „40.714728,-73.998672” to prawidłowa wartość kodu geograficznego. Dokładność powyżej 6 miejsc po przecinku jest ignorowana.

Wartości długości geograficznej są oparte na odległości od Greenwich w Anglii, gdzie znajduje się południk zerowy. Ponieważ Greenwich znajduje się na szerokości geograficznej 51,477222, możemy wpisać wartość center równą 51.477222,0, aby wyśrodkować mapę na Greenwich:

Greenwich, Anglia

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

Adresy

Większość ludzi nie podaje szerokości i długości geograficznej, tylko określa lokalizacje za pomocą adresów. Proces przekształcania adresu w punkt geograficzny jest nazywany geokodowaniem. Usługa Maps Static API może wykonać geokodowanie, jeśli podasz prawidłowe adresy.

W każdym parametrze, w którym możesz podać szerokość i długość geograficzną, możesz zamiast tego podać ciąg znaków wskazujący adres. Google zakoduje geograficznie adres i udostępni usłudze Maps Static API wartość szerokości i długości geograficznej, która zostanie użyta do umieszczenia znaczników lub określenia lokalizacji. Ciąg znaków powinien być zakodowany w adresie URL, więc adresy takie jak „City Hall, New York, NY” powinny zostać przekonwertowane na przykład na „City+Hall,New+York,NY”.

Pamiętaj, że adresy mogą odzwierciedlać dokładne lokalizacje, takie jak adresy ulic, linie łamane, takie jak nazwane trasy, lub obszary wielokątne, takie jak miasta, kraje lub parki narodowe. W przypadku wyników w postaci linii łamanych i wielokątów serwer Maps Static API użyje środkowego punktu linii lub obszaru jako środka adresu. Jeśli masz wątpliwości, jak adres może zostać zakodowany geograficznie, możesz go przetestować za pomocą tego narzędzia do geokodowania.

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

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

Berkeley, CA

Poziomy powiększenia

Mapy w Mapach Google mają liczbę całkowitą „poziom powiększenia”, 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 jest widoczny na jednej mapie) do 21+ (widoczne są ulice i poszczególne budynki). Kontury budynków, jeśli są dostępne, pojawiają się na mapie przy poziomie powiększenia 17. Wartość ta różni się w zależności od obszaru i może się zmieniać w miarę rozwoju danych.

W Mapach Google poziom powiększenia 0 obejmuje całą kulę ziemską. Każdy kolejny poziom powiększenia podwaja precyzję zarówno w wymiarze poziomym, jak i pionowym. Więcej informacji o tym, jak to zrobić, znajdziesz w dokumentacji interfejsu Google Maps JavaScript API.

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

Jeśli wyślesz żądanie dotyczące poziomu powiększenia, dla którego nie ma kafelków mapy, interfejs Maps Static API zwróci pusty obraz.

Poniższa lista zawiera przybliżony poziom szczegółowości, którego możesz się spodziewać na każdym poziomie powiększenia:

  • 1: Świat
  • 5. Ląd/kontynent
  • 10: miasto,
  • 15: Ulice
  • 20: Budynki

W tym przykładzie żądane są 2 mapy Manhattanu z tą samą wartością center, ale z poziomami powiększenia 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

Manhattan Faraway  Manhattan z bliska

Rozmiary obrazów

Parametr size w połączeniu z center określa obsługiwany obszar mapy. Określa też rozmiar wyjściowy mapy w pikselach po pomnożeniu przez wartość scale (która domyślnie wynosi 1).

Ta tabela zawiera maksymalne dozwolone 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 żądany jest „wycinek” Ziemi na równiku przy poziomie powiększenia 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 żądana jest mała mapa o rozmiarze 100 x 100 pikseli wyś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

Mała mapa równika

Wartości skali

Parametr size interfejsu Maps Static API określa rozmiar mapy w pikselach, więc mapa z parametrem size=200x200 będzie miała rozmiar 200 x 200 pikseli. Na monitorze LCD, który zwykle wyświetla około 100 pikseli na cal (ppi), mapa o wymiarach 200 x 200 będzie miała około 2 cale w każdym wymiarze.

Jednak urządzenia mobilne coraz częściej mają ekrany o wysokiej rozdzielczości i gęstości pikseli powyżej 300 ppi, które:

  • zmniejszyć rozmiar obrazu o wymiarach 200 × 200 pikseli do zaledwie 0,7 cala, przez co etykiety i ikony będą zbyt małe, aby można je było odczytać;
  • skalowanie (powiększanie) obrazu w celu poprawy czytelności, co powoduje, że obraz jest rozmyty lub rozpikselowany;
Za małe Zbyt niewyraźne

Podczas tworzenia aplikacji na urządzenia mobilne możesz użyć parametru scale interfejsu API, aby zwracać obrazy map o 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 obsługiwanego obszaru mapy. Domyślna wartość scale to 1. Akceptowane wartości to 1 i 2.

Na przykład wartość skali równa 2 zwróci ten sam obsługiwany obszar mapy co żądanie bez określonej skali, ale z dwukrotnie większą liczbą pikseli w każdym wymiarze. Obejmuje to drogi i etykiety, dzięki czemu są one czytelne na ekranach o wysokiej rozdzielczości i niewielkich rozmiarach, a także po przeskalowaniu przez przeglądarkę.

150 x 150 150x150&scale=2

Taki obraz będzie też dobrze wyglądać w przeglądarkach na komputerach, gdy zostanie wstawiony do tagu img lub div z wysokością i szerokością ustawionymi za pomocą CSS. Przeglądarka zmniejszy obraz do odpowiedniego rozmiaru bez utraty jakości.

Tabela przedstawia 3 różne żądania obrazu.

  • Pierwszy dotyczy obrazu o wymiarach 100 × 100 bez określonej wartości skali. Wyświetla się prawidłowo na komputerze, ale jest zbyt mała, aby można ją było odczytać na urządzeniu mobilnym.
  • Drugi podwaja rozmiar 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ę zbyt małe. Na urządzeniu mobilnym obraz ma odpowiedni rozmiar, ale drogi i etykiety są nieczytelne.
  • Trzecie żądanie dotyczy mapy o wymiarach 100 x 100 z scale=2. Obraz jest zwracany z rozdzielczością 200 pikseli. Na komputerze jest on idealnie przeskalowany, dzięki czemu nie można go odróżnić od oryginalnego żądania 100 x 100, a przeglądarka mobilna korzysta z dodatkowej rozdzielczości zwracanej przez interfejs API.
Żądania obrazów
Urządzenie 100x100 200x200 100x100&scale=2
Komputer
(z height="100px" i 
width="100px" w tagu
img)
Wysoka rozdzielczość
(symulacja)

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

Formaty plików graficznych

Obrazy mogą być zwracane w kilku popularnych formatach grafiki internetowej: 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 format kompresji JPEG bez progresywnego kodowania.

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

Formaty jpg i jpg-baseline zwykle zapewniają najmniejszy rozmiar obrazu, ale robią to za pomocą kompresji stratnej, która może pogorszyć jakość obrazu. gif, png8 i png32 zapewniają kompresję bezstratną.

Większość obrazów JPEG jest progresywna, co oznacza, że najpierw wczytują obraz o niższej jakości, a następnie poprawiają jego rozdzielczość w miarę napływu kolejnych danych. Dzięki temu obrazy mogą być szybko wczytywane na stronach internetowych. Jest to obecnie najczęstsze zastosowanie formatu JPEG. Jednak niektóre zastosowania formatu JPEG wymagają obrazów nieprogresywnych (podstawowych). W takich przypadkach możesz użyć formatu jpg-baseline, który nie jest progresywny.

Typy map

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

  • roadmap (domyślna) – określa standardowy obraz mapy drogowej, taki jak zwykle wyświetlany w witrynie Map Google. Jeśli nie podasz wartości maptype, interfejs Maps Static API będzie domyślnie wyświetlać kafelki roadmap.
  • satellite określa zdjęcie satelitarne.
  • terrain określa obraz fizycznej mapy reliefowej, pokazującej ukształtowanie terenu i roślinność.
  • hybrid określa hybrydę zdjęcia satelitarnego i mapy drogowej, pokazując przezroczystą warstwę głównych ulic i nazw miejsc na zdjęciu satelitarnym.

Różnicę między typami mapy drogowej i terenu możesz zobaczyć w tym przykładowym kodzie.

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

Mapa normalna Manhattanu  Mapa terenu Manhattanu

Mapy hybrydowe wykorzystują zdjęcia satelitarne i najważniejsze elementy mapy drogowej, aby utworzyć mapę łączoną. Poniższe przykłady pokazują typy map satelitarnych i hybrydowych:

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 z własnym stylem

Dostosuj wygląd standardowej mapy Google, stosując własne style. Zapoznaj się z przewodnikiem po mapach z własnym stylem.

Znaczniki

Parametr markers definiuje zbiór co najmniej 1 znacznika (pinezek mapy) w zbiorze lokalizacji. Każdy znacznik zdefiniowany w ramach jednej deklaracji markers musi mieć ten sam styl wizualny. Jeśli chcesz wyświetlać znaczniki o różnych stylach, musisz podać wiele parametrów markers z osobnymi informacjami o stylu.

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

markers=markerStyles|markerLocation1| markerLocation2|... itd.

Zbiór markerStyles jest deklarowany na początku deklaracji markers i składa się z co najmniej 1 deskryptora stylu rozdzielonego znakiem kreski pionowej (|), po którym następuje zbiór co najmniej 1 lokalizacji, również rozdzielonych znakiem kreski pionowej (|).

Zarówno informacje o stylu, jak i informacje o lokalizacji są rozdzielane znakiem kreski pionowej, dlatego informacje o stylu muszą pojawiać się jako pierwsze w każdym deskryptorze znacznika. Gdy serwer Maps Static API napotka lokalizację w deskryptorze znacznika, wszystkie pozostałe parametry znacznika są również traktowane jako lokalizacje.

Style znaczników

Zestaw deskryptorów stylu znacznika to seria przypisań wartości rozdzielonych pionową kreską (|). Ten deskryptor stylu definiuje atrybuty wizualne, które mają być używane podczas wyświetlania znaczników w tym deskryptorze znaczników. Te deskryptory stylu zawierają następujące przypisania kluczy i wartości:

  • size: (opcjonalny) określa rozmiar znacznika ze zbioru {tiny, mid, small}. Jeśli nie ustawisz parametru size, znacznik będzie miał domyślny (normalny) rozmiar.

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

    Pamiętaj, że przezroczystość (określana za pomocą 32-bitowych szesnastkowych kodów kolorów) nie jest obsługiwana w przypadku znaczników, ale jest obsługiwana w przypadku ścieżek.

  • label: (opcjonalnie) określa pojedynczy wielki znak alfanumeryczny ze zbioru {A–Z, 0–9}. (Wymóg dotyczący wielkich liter jest nowy w tej wersji interfejsu API). Pamiętaj, że tylko znaczniki o rozmiarze domyślnym i mid mogą wyświetlać parametr alphanumeric-character. Znaczniki tiny i small nie mogą wyświetlać znaków alfanumerycznych.

Skalowanie znaczników

Wartość scale jest mnożona przez rozmiar obrazu znacznika, aby uzyskać rzeczywisty rozmiar wyjściowy znacznika w pikselach. Domyślna wartość skali to 1. Akceptowane wartości to 1, 2 i 4.

Limit rozmiaru obrazów w pikselach obowiązuje po zastosowaniu skalowania. Jeśli na przykład znacznik jest ustawiony na scale:2, może być większy niż maksymalny rozmiar 4096 pikseli, o ile po przeskalowaniu zostanie zmniejszony do mniej niż 4096 pikseli. Podczas wyświetlania map o wyższej rozdzielczości używaj skalowania znaczników w połączeniu ze skalowaniem mapy.

Lokalizacje znaczników

Każdy deskryptor znacznika musi zawierać zestaw co najmniej 1 lokalizacji określającej, gdzie umieścić znacznik na mapie. Lokalizacje te można określić jako wartości szerokości i długości geograficznej lub jako adresy. Te lokalizacje są rozdzielone znakiem kreski pionowej (|).

Uwaga: jeśli zdecydujesz się określić lokalizacje znaczników za pomocą metody, która wymaga geokodowania, np. zrozumiałe dla człowieka ciągi adresowe lub linie łamane, żądanie jest ograniczone do 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ą położenie znacznika na mapie. Jeśli lokalizacja znajduje się poza mapą, znacznik nie pojawi się na utworzonym obrazie, pod warunkiem że podano parametry center i zoom. Jeśli jednak te parametry nie zostaną podane, serwer Maps Static API automatycznie utworzy obraz zawierający podane znaczniki. (patrz Pozycjonowanie niejawne).

Poniżej znajduje się przykładowa deklaracja znacznika. Zwróć uwagę, że definiujemy jeden zestaw stylów i 3 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 na Brooklynie

Aby zdefiniować znaczniki o różnych stylach, musimy podać kilka parametrów markers. Ten zestaw parametrów markers definiuje 3 znaczniki: niebieski oznaczony literą „S” o współrzędnych 62.107733, -145.5419, mały zielony oznaczony jako „Delta Junction, AK” i średni żółty oznaczony literą „C” i opisany jako „Tok, AK”. Te znaczniki są widoczne w tym przykładzie:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Trzy miasta na Alasce, różne znaczniki

Ikony niestandardowe

Zamiast ikon znaczników Google możesz używać własnych ikon niestandardowych. 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 (który powinien być zakodowany). Możesz używać adresów URL utworzonych przez usługi skracania adresów URL, takie jak https://goo.gl. Większość usług skracania adresów URL automatycznie koduje adresy URL.

Możesz określić punkt zakotwiczenia ikony niestandardowej. Punkt zakotwiczenia określa, jak ikona jest umieszczana w stosunku do określonych lokalizacji markers. Domyślnie punktem zakotwiczenia ikony niestandardowej jest dolny środek obrazu ikony. Możesz określić 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 wstępnie zdefiniowane wyrównanie, używając 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 każdej prośbie możesz użyć maksymalnie 5 unikalnych ikon niestandardowych. To ograniczenie 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ż 1 lokalizacją markers na mapie.

Format ikony:

  • Obrazy ikon mogą być w formacie PNG, JPEG lub GIF, ale zalecany jest format PNG.
  • Ikony mogą mieć maksymalnie 4096 pikseli (64 x 64 w przypadku obrazów kwadratowych).
Przykłady ikon niestandardowych

Przykład 1 tworzy ikony niestandardowe i pozycjonuje je za pomocą punktów zakotwiczenia.

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

3 australijskie miasta, różne ikony niestandardowe umieszczone za pomocą kotwic.

Przykład 2 tworzy te same ikony niestandardowe co przykład 1, ale nie ustawia ich pozycji za pomocą kotwic, lecz korzysta z domyślnej kotwicy na dole pośrodku.

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

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

Ścieżki Maps Static API

Parametr path definiuje zbiór co najmniej 1 lokalizacji połączonych ścieżką, która ma zostać nałożona na obraz mapy. Parametr path przyjmuje zestaw przypisań wartości (deskryptorów ścieżki) w tym formacie:

path=pathStyles|pathLocation1|pathLocation2|... itd.

Zwróć uwagę, że oba punkty ścieżki są oddzielone od siebie znakiem kreski pionowej (|). Ponieważ zarówno informacje o stylu, jak i informacje o punktach są rozdzielane znakiem kreski pionowej, 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ż zostaną uznane za lokalizacje.

Style ścieżek

Zestaw deskryptorów stylu ścieżki to seria przypisań wartości rozdzielonych pionową kreską (|). Ten deskryptor stylu definiuje atrybuty wizualne, które mają być używane podczas wyświetlania ścieżki. Te deskryptory stylu zawierają następujące przypisania kluczy i wartości:

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

  • color: (opcjonalny) określa kolor jako 24-bitową (np. color=0xFFFFCC) lub 32-bitową wartość szesnastkową (np. color=0xFFFFCCFF) albo ze zbioru {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    Jeśli podana jest 32-bitowa wartość szesnastkowa, ostatnie 2 znaki określają 8-bitową wartość przezroczystości alfa. Ta wartość może wynosić od 00 (pełna przezroczystość) do FF (pełna nieprzezroczystość). Pamiętaj, że przezroczystość jest obsługiwana w przypadku ścieżek, ale nie znaczników.

  • fillcolor: (opcjonalny) wskazuje, że ścieżka wyznacza obszar wielokąta, i określa kolor wypełnienia, który ma być używany jako nakładka w tym obszarze. Zbiór lokalizacji nie musi być „zamkniętą” pętlą. Serwer Maps Static API automatycznie połączy pierwszy i ostatni punkt. Pamiętaj jednak, że obrys na zewnątrz wypełnionego obszaru nie zostanie zamknięty, chyba że wyraźnie podasz tę samą lokalizację początkową i końcową.
  • geodesic: (opcjonalnie) wskazuje, że żądana ścieżka powinna być interpretowana jako linia geodezyjna, która podąża za krzywizną Ziemi. W przypadku wartości false (fałsz) ścieżka jest renderowana jako linia prosta w przestrzeni ekranu. Wartość domyślna to fałsz.

Przykładowe definicje ścieżek:

  • Cienka niebieska linia, 50% nieprzezroczystości: path=color:0x0000ff80|weight:1
  • Ciągła czerwona linia: path=color:0xff0000ff|weight:5
  • Gruba, ciągła biała linia: path=color:0xffffffff|weight:10

Te style ścieżek są opcjonalne. Jeśli chcesz użyć domyślnych atrybutów, możesz pominąć definiowanie atrybutów ścieżki. W takim przypadku pierwszym „argumentem” deskryptora ścieżki będzie pierwszy zadeklarowany punkt (lokalizacja).

Punkty ścieżki

Aby narysować ścieżkę, do parametru path należy przekazać co najmniej 2 punkty. Maps Static API połączy wtedy ścieżkę wzdłuż tych punktów w określonej kolejności. Każdy punkt pathPoint jest oznaczony w parametrze pathDescriptor i oddzielony znakiem | (pionowa kreska).

Poniższy przykład definiuje niebieską ścieżkę z domyślnym kryciem 50% od Union Square NY do Times Square, NY.

Ścieżka z Union Sq do Times Sq

Szczegóły parametru path:

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ę, ale jako ciągłą czerwoną linię o kryciu 100%:

Ścieżka z Union Sq do Times Sq

Szczegóły 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 zdefiniowano obszar wielokąta na Manhattanie, przekazując serię skrzyżowań jako lokalizacje:

Ścieżka z Union Sq do Times Sq

Szczegóły 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

Zwróć uwagę, że ścieżka jest niewidoczna, a obszar wielokąta ma przezroczystość 15%.

Zakodowane 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 Highway od Dawson Creek w Kolumbii Brytyjskiej do Delta Junction na Alasce za pomocą zakodowanej linii łamanej:

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%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Alaska Highway

Podobnie jak w przypadku ścieżek standardowych, zakodowane ścieżki linii łamanej mogą też wyznaczać obszary wielokątne, jeśli do parametru path zostanie przekazany argument fillcolor.

Poniższy przykład przedstawia obszar wielokąta dla Brooklynu w Nowym Jorku:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Zakodowana linia łamana w Brooklynie z podpisem

Widoczne obszary

Obrazy mogą określać widoczny obszar przez podanie widocznych lokalizacji za pomocą parametru visible. Parametr visible instruuje usługę Maps Static API, aby utworzyła mapę, na której istniejące lokalizacje pozostaną widoczne. (Ten parametr można połączyć z istniejącymi znacznikami lub ścieżkami, aby zdefiniować widoczny region). Zdefiniowanie widocznego obszaru w ten sposób eliminuje konieczność określania dokładnego poziomu powiększenia.

Kolejny przykład żąda mapy wyśrodkowanej na Bostonie (Massachusetts) i zawierającej zarówno MIT, jak i Harvard Square w Cambridge (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

Pozycjonowanie domyślne mapy

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

Jeśli podasz co najmniej 2 elementy, interfejs Maps Static API określi odpowiedni środek i poziom powiększenia, zapewniając duże marginesy dla zawartych elementów. Ten przykład pokazuje mapę obejmującą San Francisco, Oakland i San Jose w Kalifornii:

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 x 640 pikseli (lub 1280 x 1280 pikseli przy wartości skali 2), skontaktuj się z zespołem pomocy i podaj te informacje:

  1. przypadek użycia i powód, dla którego potrzebujesz obrazów o dużym rozmiarze;
  2. Czy rozważasz użycie innych interfejsów API Google Maps Platform (Maps JavaScript API, Maps Embed API, Maps SDK na Androida lub Maps SDK na iOS) i dlaczego nie spełniają one Twoich potrzeb.
  3. Zrzuty ekranu, makiety lub przykłady pokazujące, jak będziesz używać obrazów o dużym rozmiarze.
  4. Szacowane miesięczne wykorzystanie 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, jaki możemy udostępnić, to 2048 x 2048 pikseli.

Rozwiązywanie problemów i pomoc

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

Jeśli coś pójdzie nie tak, interfejs Maps Static API może wyświetlić błąd lub ostrzeżenie. Ostrzeżenia należy sprawdzać zwłaszcza wtedy, gdy zauważysz, że na mapie czegoś brakuje. Przed uruchomieniem nowej aplikacji warto też sprawdzić, czy nie ma ostrzeżeń. Pamiętaj, że ostrzeżenia mogą nie być od razu widoczne, ponieważ pojawiają się w nagłówku HTTP. Więcej informacji znajdziesz w przewodniku po błędach i ostrzeżeniach.