Wprowadzenie
Interfejs Statyczny interfejs API Map Google zwraca w odpowiedzi na żądanie HTTP obraz (w formacie GIF, PNG lub JPEG). W przypadku każdego żądania możesz określić lokalizację mapy, jej rozmiar, poziom powiększenia, typ mapy i położenie opcjonalnych znaczników w określonych lokalizacjach na mapie. Znaczniki możesz też oznaczać etykietami przy użyciu znaków alfanumerycznych.
Obraz statycznego interfejsu API Map Google jest umieszczony w atrybucie src
tagu <img>
lub jego odpowiedniku w innych językach programowania.
Ten dokument zawiera opis wymaganego formatu adresów URL statycznego interfejsu API Map Google oraz dostępne parametry. Znajdziesz w nim też praktyczne porady na temat określania adresów URL.
Zanim zaczniesz
Ten dokument jest przeznaczony dla programistów witryn i urządzeń mobilnych, którzy chcą umieszczać obrazy statycznego interfejsu API Map Google na stronach internetowych lub w aplikacjach mobilnych. Zawiera wprowadzenie do korzystania z interfejsu API i materiałów referencyjnych dotyczących dostępnych parametrów.
Zanim zaczniesz programować za pomocą statycznego interfejsu API Map Google, zapoznaj się z wymaganiami dotyczącymi uwierzytelniania (potrzebny klucz interfejsu API) oraz informacjami o użyciu i płatnościach interfejsu API (musisz włączyć płatności w projekcie).
Parametry adresu URL
Adres URL statycznego interfejsu API Map Google musi mieć następującą formę:
https://maps.googleapis.com/maps/api/staticmap?parameters
Jeśli dostęp do Twojej witryny jest uzyskiwany za pomocą protokołu HTTPS, musisz też załadować obrazy statycznego interfejsu API Map Google przez HTTPS. Pozwoli to uniknąć alertów przeglądarki dotyczących zabezpieczeń. Protokół HTTPS jest również zalecany, jeśli żądania zawierają poufne dane użytkownika, takie jak lokalizacja użytkownika:
https://maps.googleapis.com/maps/api/staticmap?parameters
Niezależnie od tego, czy używasz HTTP czy HTTPS, niektóre parametry adresu URL są wymagane, a niektóre są opcjonalne. Standardowo w adresach URL wszystkie parametry są rozdzielone znakiem „&
”. W tym dokumencie opisujemy listę parametrów i ich możliwe wartości.
Interfejs Statyczny interfejs API Map Google definiuje obrazy na mapie za pomocą tych parametrów adresu URL:
Parametry lokalizacji
center
(wymagany, jeśli nie ma znaczników) określa środek mapy, czyli odległość od wszystkich krawędzi mapy. Ten parametr przyjmuje lokalizację w postaci pary rozdzielonych przecinkami (szerokość geograficzna,długość geograficzna) (np. „40.714728,-73.998672”) lub adresu ciągu znaków (np. ratusz, Nowy Jork, ny) określającyj unikalną lokalizację na powierzchni Ziemi. Więcej informacji znajdziesz w sekcji Lokalizacje.zoom
(wymagany, jeśli nie ma znaczników) określa poziom powiększenia mapy, który określa poziom powiększenia mapy. Ten parametr przyjmuje wartość liczbową odpowiadającą poziomowi powiększenia odpowiedniego regionu. Więcej informacji znajdziesz w artykule Poziomy powiększenia.
Parametry mapy
size
(wymagany) określa prostokątne wymiary obrazu mapy. Ten parametr ma ciąg znaków{horizontal_value}x{vertical_value}
. Na przykład500x400
definiuje mapę o wymiarach 500 × 400 pikseli i wysokość. Mapy o szerokości mniejszej niż 180 pikseli będą wyświetlać logo Google o mniejszym rozmiarze. Na ten parametr wpływa parametrscale
. Ostatecznym rozmiarem danych wyjściowych jest iloczyn rozmiaru i skali.scale
(opcjonalny) wpływa na liczbę zwracanych pikseli.scale=2
zwraca 2 razy więcej pikseli niżscale=1
, zachowując ten sam obszar pokrycia i ten sam poziom szczegółów (tj. zawartość mapy nie ulega zmianie). Przydaje się to podczas tworzenia ekranów o wysokiej rozdzielczości. Wartością domyślną jest1
. Akceptowane wartości to1
i2
. Więcej informacji znajdziesz w artykule Wartości skali.format
(opcjonalny) określa format tworzonego obrazu. Domyślnie interfejs Statyczny interfejs API Map Google tworzy obrazy PNG. Istnieje kilka możliwych formatów, w tym GIF, JPEG i PNG. Wybór formatu zależy od tego, jak chcesz zaprezentować obraz. Format JPEG zwykle zapewnia większą kompresję, podczas gdy GIF i PNG zapewniają więcej szczegółów. Więcej informacji znajdziesz w artykule Formaty obrazu.maptype
(opcjonalny) określa typ mapy do utworzenia. Istnieje kilka możliwych wartości typu mapy, np.roadmap
,satellite
,hybrid
iterrain
. Więcej informacji znajdziesz w artykule na temat typów map statycznych interfejsu API Map Google.language
(opcjonalny) określa język wyświetlania etykiet na kafelkach mapy. Ten parametr jest obsługiwany tylko w przypadku niektórych kafelków krajów. Jeśli określony kafelek nie obsługuje konkretnego języka, zostanie użyty domyślny język tego zestawu.region
(opcjonalny) określa odpowiednie granice do wyświetlenia na podstawie wrażliwości geograficznej i politycznej. Akceptuje kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Listę obsługiwanych regionów znajdziesz w artykule dotyczącym pokrycia zasięgu Google Maps Platform.
Parametry cech
map_id
(opcjonalny) określa identyfikator konkretnej mapy. Identyfikator mapy wiąże mapę z określonym stylem lub obiektem i musi należeć do tego samego projektu co klucz interfejsu API, który służy do inicjowania mapy. Więcej informacji znajdziesz w artykule Korzystanie z identyfikatorów map.markers
(opcjonalny) definiuje co najmniej 1 znacznik, który chcesz dołączyć do obrazu w określonych lokalizacjach. Ten parametr przyjmuje pojedynczą definicję z parametrami rozdzielonymi pionową kreską (|
). Wiele znaczników może być umieszczonych w tym samym parametrzemarkers
, pod warunkiem że mają ten sam styl. Możesz dodać kolejne znaczniki o różnych stylach, dodając kolejne parametrymarkers
. Jeśli podajesz znaczniki mapy, nie musisz określać (zwykle wymaganych) parametrówcenter
izoom
. Więcej informacji znajdziesz w artykule Znaczniki statycznego interfejsu API Map Google.path
(opcjonalny) określa pojedynczą ścieżkę obejmującą co najmniej 2 połączone punkty, które nakłada się na obraz w określonych lokalizacjach. Ten parametr przyjmuje ciąg definicji punktów rozdzielonych pionową kreską (|
) lub zakodowaną łamaną łamaną za pomocą prefiksuenc:
w deklaracji lokalizacji na ścieżce. Możesz podać dodatkowe ścieżki, dodając kolejne parametrypath
. Pamiętaj, że jeśli podasz ścieżkę do mapy, nie musisz określać (zwykle wymaganych) parametrówcenter
izoom
. Więcej informacji znajdziesz w artykule na temat statycznych ścieżek interfejsu API Map Google.visible
(opcjonalny) określa co najmniej jedną lokalizację, która powinna pozostać widoczna na mapie, przy czym nie będą wyświetlane żadne znaczniki ani inne wskaźniki. Użyj tego parametru, by mieć pewność, że niektóre funkcje lub lokalizacje na mapie będą widoczne w interfejsie statycznego interfejsu API Map Google.style
(opcjonalny) określa niestandardowy styl służący do zmiany sposobu wyświetlania określonych obiektów (drog, parków i innych) mapy. Ten parametr przyjmuje argumentyfeature
ielement
identyfikujące cechy stylu oraz zestaw operacji stylu do zastosowania do wybranych cech. Możesz podać wiele stylów, dodając dodatkowe parametrystyle
. Więcej informacji znajdziesz w przewodniku po mapach stylów.
Parametry klucza i podpisu
key
(wymagane) umożliwia monitorowanie korzystania z interfejsu API przez aplikację w Google Cloud Console. W razie potrzeby Google może skontaktować się z Tobą w sprawie aplikacji. Więcej informacji znajdziesz w artykule Używanie kluczy interfejsu API z interfejsem Maps Static API.signature
(zalecany) to podpis cyfrowy używany do sprawdzania, czy żądania witryny generowane przy użyciu klucza interfejsu API są do tego autoryzowane. Żądania bez podpisu cyfrowego mogą się nie powieść. Więcej informacji znajdziesz w artykule Używanie podpisu cyfrowego.
Ograniczenie rozmiaru adresu URL
Adresy URL statycznego interfejsu API Map Google mają długość do 8192 znaków. W praktyce prawdopodobnie nie będziesz potrzebować więcej adresów URL, chyba że utworzysz skomplikowane mapy z dużą liczbą znaczników i ścieżek.
Wykorzystanie parametru
Interfejs Google Static API jest stosunkowo łatwy w użyciu, ponieważ zawiera wyłącznie parametry URL. W tej sekcji dowiesz się, jak używać tych parametrów do tworzenia adresów URL.
Określanie lokalizacji
Statyczny interfejs API Map Google musi umożliwiać dokładne wskazywanie lokalizacji na mapie, tak aby można było ustawić ją na właściwej lokalizacji (przy użyciu parametru center
) lub umieścić dowolne opcjonalne oznaczenia miejsc (przy użyciu parametru markers
) w lokalizacjach na mapie. Statyczny interfejs API Map Google określa lokalizacje za pomocą liczb (wartości szerokości i długości geograficznej) lub ciągów (adresów). Te wartości identyfikują lokalizację geograficzną.
Niektóre parametry (np. markers
i path
) mogą mieć wiele lokalizacji. W takich przypadkach lokalizacje są rozdzielone pionową kreską (|
).
Długość i szerokość geograficzna
Długość i szerokość geograficzna są określane za pomocą liczb w ciągu tekstowym rozdzielanym przecinkami, z dokładnością do 6 miejsc po przecinku. Na przykład „40.714728,-73.998672” to prawidłowa wartość kodu geograficznego. Precyzja wykraczająca poza 6 miejsc po przecinku jest ignorowana.
Wartości długości geograficznej są określane na podstawie odległości od Greenwich w Anglii, w której znajduje się południk zielony. Ponieważ Greenwich znajduje się na szerokości 51,477222, możemy wpisać wartość center
51.477222,0
w celu wyśrodkowania mapy na Greenwich:
Wartości długości i szerokości geograficznej muszą odpowiadać prawidłowej lokalizacji na powierzchni ziemi. Szerokość geograficzna może mieć dowolną wartość z zakresu od -90
do 90
, a długość geograficzna – dowolną wartość z zakresu od -180
do 180
. Jeśli podasz nieprawidłową szerokość lub długość geograficzną, żądanie zostanie odrzucone jako nieprawidłowe.
Adresy
Większość osób nie mówi o długości ani szerokości geograficznej, tylko lokalizacje z adresami. Proces przekształcania adresu w punkt geograficzny jest nazywany geokodowaniem, a usługa statycznego interfejsu API Map Google może wykonać geokodowanie za Ciebie, jeśli podasz prawidłowe adresy.
W każdym parametrze, który pozwala podać szerokość lub długość geograficzną, możesz podać ciąg znaków wskazujący adres. Google wyśle dane geograficzne do geokodu adresu i udostępniy usłudze Maps Static API wartość szerokości i długości geograficznej, która będzie używana do umieszczania znaczników lub określania lokalizacji. Ciąg powinien być zakodowany na potrzeby adresu URL, więc adresy takie jak „City Hall, New York, NY” powinny zostać przekształcone na „City+Hall,New+York,NY”.
Pamiętaj, że adresy mogą odzwierciedlać dokładne lokalizacje, takie jak adresy, linie łamane (np. nazwane trasy) lub wielokąty, takie jak miasta, kraje czy parki narodowe. W przypadku wyników wielokątów i wielokątów serwer Statyczny interfejs API Map Google użyje punktu centralnego linii/obszaru jako centrum adresu. Jeśli nie masz pewności, jak adres może być interpretowany geograficznie, możesz sprawdzić adres za pomocą tego narzędzia do kodowania geograficznego.
Ten przykład generuje statyczny obraz mapy na potrzeby Berkeley w Kalifornii:
https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Poziomy powiększenia
Mapy Google mają liczbę całkowitą, która określa rozdzielczość bieżącego widoku. Powiększenie pomiędzy 0
(najniższy poziom, na którym na całej mapie widać cały świat) i 21+
(do uliczek i poszczególnych budynków) jest możliwe w domyślnym widoku roadmap
. Zarysy budynków (jeśli są dostępne) pojawią się na mapie wokół poziomu powiększenia 17
. Ta wartość różni się w zależności od obszaru i może się zmieniać w miarę rozwoju danych.
Mapy Google ustawiają poziom powiększenia 0
tak, by obejmował całą Ziemię.
Każdy skuteczny poziom powiększenia podwaja precyzję zarówno w poziomie, jak i w orientacji pionowej. Więcej informacji na ten temat znajdziesz w dokumentacji interfejsu API JavaScript Map Google.
Uwaga: niektóre poziomy powiększenia nie są widoczne we wszystkich lokalizacjach na Ziemi. Poziomy powiększenia różnią się w zależności od lokalizacji, ponieważ dane w niektórych częściach kuli ziemskiej są bardziej szczegółowe niż w innych lokalizacjach.
Jeśli wyślesz żądanie poziomu powiększenia, który nie obejmuje żadnych kafelków mapy, interfejs API Map statycznych w Mapach Google zwróci pusty obraz.
Poniższa lista pokazuje przybliżony poziom szczegółowości na poszczególnych poziomach powiększenia:
- 1: Świat
- 5: ląd/kontynent
- 10: Miasto
- 15: ulice
- 20: Budynki
W tym przykładzie zażądano 2 map Manhattanu z tą samą wartością center
, ale przy poziomach powiększenia 12 i 14:
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Rozmiary obrazów
Parametr size
w połączeniu z wartością center
określa obszar zasięgu mapy. Określa też rozmiar wyjściowy mapy w pikselach pomnożony przez wartość scale
(domyślnie 1
).
W tej tabeli podano maksymalne dozwolone wartości parametru size
w każdej wartości scale
.
scale=1 |
scale=2 |
---|---|
640x640 |
640x640 (zwraca 1280 x 1280 pikseli) |
W tym przykładzie zażądano „fragmentu” Ziemi na równiku 1 poziomu powiększenia:
https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
W tym przykładzie żądamy przesłania niewielkiej mapy o wymiarach 100 x 100 pikseli wyśrodkowanych w tym samym regionie. Zwróć uwagę na mniejsze logo Google:
https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Skalowanie wartości
Parametr size
interfejsu Maps Static API określa rozmiar mapy w pikselach, dzięki czemu mapa z atrybutem size=200x200
będzie zwracana jako 200 x 200 pikseli. Na monitorze LCD, który zwykle
wyświetla się w około 100 pikseli na cal, 200 x 200 pikseli wynosi około 2 cale na każdy wymiar.
Coraz więcej urządzeń mobilnych ma też ekrany o wysokiej rozdzielczości z gęstością pikseli 300 ppi.
- zmniejsz rozmiar obrazu 200 x 200 pikseli do zaledwie 1,48 cm, przez co etykiety i ikony są zbyt małe;
- Skaluj (powiększaj) obraz, aby poprawić jego czytelność, dzięki czemu obraz będzie wyraźny i pikselowy.
Za mały | Jest zbyt nieostre |
---|---|
![]() |
![]() |
Opracowując aplikacje na urządzenia mobilne, możesz używać parametru scale
interfejsu API, aby zwracać obrazy map w wyższej rozdzielczości, które rozwiązują powyższe problemy. Wartość scale
jest mnożona przez size
, by określić rzeczywisty rozmiar obrazu w pikselach bez zmiany obszaru pokrycia mapy. Domyślna wartość scale
to 1, a dopuszczalne wartości to 1 i 2.
Na przykład wartość skali 2 zwróci ten sam obszar pokrycia mapy, co żądanie bez określonej skali, ale z 2 razy większą liczbą pikseli w każdym wymiarze. Obejmuje to drogi i etykiety, które są czytelne na ekranach o dużej rozdzielczości, małych ekranach oraz po przeskalowaniu przez przeglądarkę.
150x150 | 150 x 150&scale=2 |
---|---|
![]() |
![]() |
Taki obraz będzie też dobrze działał w przeglądarkach na komputerach stacjonarnych, jeśli wstawisz go do tagu img
lub div
o wysokości i szerokości ustawionej w CSS. Przeglądarka zmniejszy rozmiar obrazu do prawidłowego rozmiaru bez utraty jakości.
Ta tabela pokazuje trzy różne żądania obrazu.
- Pierwszy dotyczy obrazu 100 x 100 bez określonej wartości skali. Na komputerze wyświetla się prawidłowo, ale na urządzeniu mobilnym jest za mała do odczytu.
- Druga podwaja rozmiar mapy. Na komputerze usługa porównywania cen mieści się w określonym elemencie
img
o wymiarach 100 x 100, ale zmniejszając rozmiar obrazu, drogi i etykiety stają się zbyt małe. Na urządzeniu mobilnym obraz ma odpowiedni rozmiar, ale drogi i etykiety są nieczytelne. - Trzecia prośba dotyczy mapy 100 x 100 o wartości
scale=2
. Obraz jest zwracany z 200 pikselami szczegółów. Komputer na pełną skalę skaluje go w dół, tak aby nie odróżniał się od pierwotnego żądania 100 x 100, a w przeglądarce mobilnej występuje dodatkowa rozdzielczość zwrócona przez interfejs API.
Żądania obrazów | |||
---|---|---|---|
Urządzenie | 100x100 |
200x200 |
100x100&scale=2 |
Komputer (z height="100px" i width="100px"
taguimg ) |
![]() |
![]() |
![]() |
Wysoka rozdzielczość (symulowana) |
![]() |
![]() |
![]() |
Więcej informacji na temat tworzenia treści na urządzenia mobilne i wyświetlacze o wysokiej rozdzielczości znajdziesz w tych artykułach:
- Obsługa wielu ekranów w dokumentacji dla deweloperów aplikacji na Androida.
- Zalecenia Webkit.org dotyczące opracowywania witryn internetowych o wysokiej rozdzielczości DPI.
- Obsługa ekranów o wysokiej rozdzielczości w bibliotece dla deweloperów aplikacji na iOS.
Formaty graficzne
Obrazy mogą być zwracane w kilku popularnych formatach graficznych: GIF, JPEG i PNG. Parametr format
przyjmuje jedną z tych wartości:
png8
lubpng
(domyślny) określa 8-bitowy format PNG.png32
określa 32-bitowy format PNG.gif
określa format GIF.jpg
określa format kompresji JPEG.jpg-baseline
określa niekompresujący format kompresji JPEG.
Te żądania dotyczą map w formatach gif
i png
:
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=gif&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=png&&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Najmniejszy rozmiar obrazu to zazwyczaj jpg
i jpg-baseline
, ale dzieje się tak przez kompresję „stratną”, która może zmniejszyć jego rozdzielczość. gif
, png8
i png32
zapewniają
bezstratną kompresję.
Większość obrazów JPEG ma charakter progresywny, co oznacza, że wczytywały się wcześniej i zawężają rozdzielczość obrazu w miarę gromadzenia nowych danych. Umożliwia to szybkie wczytywanie obrazów na stronach internetowych i jest obecnie najpopularniejszym formatem plików JPEG. Jednak niektóre zastosowania formatu JPEG wymagają obrazów nieprogresywnych (elementów bazowych). W takich przypadkach możesz używać formatu jpg-baseline
, który nie jest postępowy.
Typy map
Interfejs Maps Static API tworzy mapy w kilku formatach wymienionych poniżej:
roadmap
(domyślna) określa standardowy obraz planu trasy w typowy sposób, który zwykle wyświetla się w witrynie Map Google. Jeśli nie określono wartościmaptype
, interfejs API statycznych Map Google domyślnie wyświetla kafelkiroadmap
.satellite
określa zdjęcie satelitarne.terrain
określa obraz mapy fizycznej, przedstawiający teren i roślinność.hybrid
określa hybrydowe połączenie zdjęcia satelitarnego i planu przejazdu, wyświetlając przezroczystą warstwę głównych ulic i nazw miejsc na obrazie satelitarnym.
Widać tu różnicę między typami map i typów terenu w tym przykładzie kodu.
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY&signature=YOUR_SIGNATURE https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
W celu utworzenia mapy mieszanej mapy hybrydowe wykorzystują zdjęcia satelitarne i dobrze widoczne funkcje drogowe. Te przykłady pokazują mapy satelitarne i hybrydowe:
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY&signature=YOUR_SIGNATURE https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Stylizowane mapy
Dostosuj wygląd standardowej mapy Google, stosując własne style. Zapoznaj się z przewodnikiem dotyczącym map stylu.
Znaczniki
Parametr markers
określa zestaw znaczników (1 kodu) mapy w zestawie lokalizacji. Każdy znacznik określony w pojedynczej deklaracji markers
musi zawierać ten sam styl wizualny. Jeśli chcesz wyświetlać znaczniki w różnych stylach, musisz podać kilka parametrów markers
z innymi informacjami o stylu.
Parametr markers
pobiera zestaw przypisań wartości (deskryptory znaczników) w następującym formacie:
markers=markerStyles|markerLocation1|
markerLocation2|...
itp.
Zestaw markerStyles jest zadeklarowany na początku deklaracji markers
i składa się z 0 deskryptorów stylu rozdzielonych pionową kreską (|
), po której następuje zbiór co najmniej 1 lokalizacji także rozdzielonych pionową kreską (|
).
Informacje o stylu i informacje o lokalizacji są rozdzielone pionową kreską, dlatego muszą być wyświetlane jako pierwsze w deskryptorach znacznika. Gdy serwer interfejsu statycznego interfejsu API napotka lokalizację w deskrypcie znacznika, przyjmuje się również, że wszystkie pozostałe parametry znaczników są lokalizacjami.
Style znaczników
Zestaw deskryptorów stylu znaczników to seria przypisań wartości rozdzielonych pionową kreską (|
). Ten deskryptor tego stylu definiuje atrybuty wizualne, których należy używać podczas wyświetlania znaczników w tym deskryptoru znacznika. Te deskryptory stylu zawierają te przypisania par klucz/wartość:
size:
(opcjonalnie) określa rozmiar znacznika z zestawu{tiny, mid, small}
. Jeśli nie ustawisz parametrusize
, znacznik wyświetli się w rozmiarze domyślnym (normalnym).color:
(opcjonalny) określa kolor 24-bitowy (np.color=0xFFFFCC
) lub wstępnie zdefiniowany kolor ze zbioru{black, brown, green, purple, yellow, blue, gray, orange, red, white}
.Znaczniki przezroczystości (określane za pomocą 32-bitowych wartości szesnastkowych kolorów) nie są obsługiwane przez znaczniki, ale są one obsługiwane w przypadku ścieżek.
label:
(opcjonalnie) określa pojedynczy znak alfanumeryczny wielkimi z zestawu {A–Z, 0–9}. (Wymagania dotyczące wielkich liter w nowej wersji interfejsu API są nowe). Znaczniki o rozmiarach domyślnych imid
są jedynymi znacznikami, które mogą wyświetlać parametralphanumeric-character
. Znacznikitiny
ismall
nie mogą wyświetlać znaku alfanumerycznego.
Skalowanie znaczników
Wartość scale
jest mnożona przez rozmiar znacznika, aby uzyskać rzeczywisty rozmiar znacznika w pikselach. Wartość domyślna to 1; akceptowane wartości to 1, 2 i 4.
Limit rozmiaru obrazu w obrazach obowiązuje po zastosowaniu skalowania. Jeśli na przykład znacznik ma wartość scale:2
, może być większy niż maksymalny rozmiar 4096 pikseli, o ile po jego skalowaniu zmniejszy się do mniej niż 4096 pikseli. Jeśli wyświetlasz mapy w wyższej rozdzielczości, używaj ich w połączeniu z skalowaniem mapy.
Lokalizacje znaczników
Każdy deskryptor znacznika musi zawierać zestaw miejsc określających, gdzie należy umieścić znacznik na mapie. Lokalizacje te można określić jako wartości szerokości i długości geograficznej lub jako adresy. Lokalizacje te są rozdzielone pionową kreską (|
).
Uwaga: jeśli określisz lokalizacje znaczników przy użyciu metody, która wymaga geokodowania, np. w postaci zrozumiałych dla człowieka ciągów znaków lub linii łamanych, żądanie może zawierać maksymalnie 15 znaczników. Ten limit dotyczy tylko lokalizacji znaczników, które wymagają geokodowania. Nie dotyczy lokalizacji znaczników wskazanych za pomocą współrzędnych geograficznych.
Parametry lokalizacji określają położenie znacznika na mapie. Jeśli lokalizacja jest poza mapą, ten znacznik nie pojawi się w skonstruowanym obrazie, o ile parametry center
i zoom
są podane. Jeśli jednak nie podasz tych parametrów, serwer Maps Static API automatycznie utworzy obraz zawierający przesłane znaczniki.
(Patrz sekcja Pozycjonowanie pośrednie).
Przykładowa deklaracja znacznika znajduje się tutaj. Zwróć uwagę, że definiujemy jeden zestaw stylów i trzy lokalizacje:
https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Aby zdefiniować znaczniki o różnych stylach, musimy podać kilka parametrów markers
. Ten zestaw parametrów markers
definiuje trzy znaczniki: jeden niebieski z etykietą „S” na stronie 62.107733, -145.5419,
1 mały zielony znacznik w miejscu „delta Junction, AK” i jeden średni żółty znacznik z etykietą „C” na „Tok, AK”. Te znaczniki są widoczne w tym przykładzie:
https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Ikony niestandardowe
Zamiast ikon Google możesz używać własnych ikon niestandardowych. Niestandardowe ikony są określane za pomocą deskryptora icon
w parametrze markers
. Przykład:
markers=icon:URLofIcon|markerLocation
Określ icon
za pomocą adresu URL (który powinien być zakodowany na potrzeby adresu URL). Możesz używać adresów URL utworzonych przez usługi skracające adresy URL, takie jak https://goo.gl
. Większość usług skracania adresów URL wykorzystuje automatyczne kodowanie adresów URL.
Możesz określić punkt zakotwiczenia ikony niestandardowej. Punkt zakotwiczenia określa sposób umieszczenia ikony w odniesieniu do wskazanych lokalizacji markers
. Punkt zakotwiczenia niestandardowej ikony jest domyślnie umieszczony na dole pośrodku obrazu. Możesz podać inny punkt zakotwiczenia za pomocą deskryptora anchor
w połączeniu z icon
. Ustaw anchor
jako punkt x,y ikony (np. 10,5
) lub jako wstępnie zdefiniowane wyrównanie przy użyciu jednej z tych wartości: top
, bottom
, left
, right
,
center
, topleft
, topright
, bottomleft
lub bottomright
. Przykład:
markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2
W każdym żądaniu możesz użyć maksymalnie 5 unikalnych ikon niestandardowych. To ograniczenie nie oznacza, że jesteś na mapie
ograniczone do 5 lokalizacji. Każda unikalna ikona może być używana z więcej niż jedną lokalizacją markers
na mapie.
Format ikony:
- Obrazy ikon mogą być w formacie PNG, JPEG lub GIF, zalecamy jednak format PNG.
- Maksymalny rozmiar ikon to 4096 pikseli (64 x 64 w przypadku obrazów kwadratowych).
Przykłady ikon niestandardowych
Przykład 1 tworzy niestandardowe ikony i pozycjonuje je za pomocą kotwic.
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 przykład 1, ale nie ustala pozycji ikon za pomocą kotwic, ponieważ opiera się na domyślnej zakotwiczeniu w dolnej części środkowej.
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 lokalizacji obejmujący jedną lub więcej ścieżek, które łączy się z nakładką na obrazie mapy. Parametr path
pobiera zestaw przypisań wartości (deskryptory ścieżki) tego formatu:
path=pathStyles|pathLocation1|pathLocation2|...
itp.
Zwróć uwagę, że punkty na ścieżce są rozdzielone pionową kreską (|
). Ponieważ informacje o stylu i dane punktu są rozdzielone pionową kreską, informacje o stylu muszą być widoczne jako pierwsze w każdym deskryptorze ścieżki. Gdy serwer interfejsu statycznego interfejsu API napotka lokalizację w deskryptorach ścieżki, przyjmuje się również, że wszystkie pozostałe parametry ścieżki są lokalizacjami.
Style ścieżek
Zestaw deskryptorów stylu ścieżki to seria przypisań wartości rozdzielonych pionową kreską (|
). Deskryptor tego stylu określa atrybuty wizualne, których należy używać podczas wyświetlania ścieżki. Deskryptory stylu zawierają te przypisania par klucz-wartość:
weight:
(opcjonalny) określa grubość ścieżki w pikselach. Jeśli nie ustawisz parametruweight
, ścieżka będzie miała domyślną grubość (5 pikseli).color:
(opcjonalny) określa kolor jako 24-bitowy (przykład:color=0xFFFFCC
) lub 32-bitowy szesnastkowy (przykład:color=0xFFFFCCFF
) albo z zestawu{black, brown, green, purple, yellow, blue, gray, orange, red, white}
.Jeśli określona jest 32-bitowa wartość szesnastkowa, ostatnie dwa znaki określają 8-bitową wartość przezroczystości alfa. Ta wartość różni się między
00
(całkowicie przezroczysta) aFF
(całkowicie nieprzezroczysta). Przezroczystość jest obsługiwana w ścieżkach, ale nie w przypadku znaczników.- Pole
fillcolor:
(opcjonalne) wskazuje, że ścieżka wskazuje wielokąt, a także określa kolor wypełnienia, który ma być użyty jako nakładka w tym obszarze. Zestaw lokalizacji nie musi być „pętlią”; serwer Static API Map Google automatycznie łączy się z pierwszym i ostatnim punktem. Pamiętaj jednak, że żadna kreska na zewnątrz wypełnionego obszaru nie zostanie zamknięta, chyba że wyraźnie podasz tę samą lokalizację początkową i końcową. geodesic:
(opcjonalnie) wskazuje, że żądana ścieżka powinna być interpretowana jako linia geodezyjna wzdłuż krzywizny Ziemi. Jeśli wartość to fałsz, ścieżka jest wyświetlana w formie prostej linii w obszarze ekranu. Wartość domyślna to fałsz.
Przykładowe definicje ścieżek:
- Cienka niebieska linia, 50% krycia:
path=color:0x0000ff80|weight:1
- Czerwona linia:
path=color:0xff0000ff|weight:5
- Gruba linia ciągła:
path=color:0xffffffff|weight:10
Te style ścieżki są opcjonalne. Jeśli chcesz korzystać z atrybutów domyślnych, możesz pominąć definiowanie atrybutów ścieżki. W takim przypadku pierwszy „argument” deskryptora będzie zawierał zamiast pierwszego zadeklarowanego punktu (lokalizacji).
Punkty na ścieżce
Aby można było narysować ścieżkę, parametr path
musi być przekazywany co najmniej 2 punkty. Maps Static API następnie połączy ścieżkę w tych punktach w określonej kolejności. Każdy element pathPoint jest oznaczony w parametrze pathDescriptor znakiem rozdzielacza |
(kreska pionowa).
Poniższy przykład pokazuje niebieską ścieżkę z przezroczystością domyślną 50% od Union Square (Nowy Jork) do Times Square (Nowy Jork).
Konkretne parametry parametru path
:
path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
Poniższy przykład definiuje tę samą ścieżkę, ale definiuje ciągłą czerwoną linię z przezroczystością 100%:
Parametry tego parametru (path
) są następujące:
path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
Następny przykład określa wielokąt obszaru Manhattanu, przekazując seria skrzyżowań jako lokalizacje:
Parametry tego parametru (path
) są następujące:
path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\ 8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\ Park+Ave+%26+34th+St,New+York,NY,NY
Wyznaczamy ścieżkę jako niewidoczną, a wielokąt – 15%.
Zakodowane linie łamane
Zamiast ciągu lokalizacji możesz zadeklarować ścieżkę jako linię łamaną, używając prefiksu enc:
w deklaracji lokalizacji elementu path
.
Poniższy przykład przedstawia przebieg autostrady Alaska z Dawson Creek, BC do delta Junction, AK z zakodowaną łamaną:
https://maps.googleapis.com/maps/api/staticmap
?size=400x400¢er=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Tak jak w przypadku standardowych ścieżek, zakodowane ścieżki łamane mogą także dekodować wielokąty, jeśli argument fillcolor
jest przekazywany do parametru path
.
W przykładzie poniżej opisano wielokąt charakterystyczny dla Brooklynu w stanie Nowy Jork:
https://maps.googleapis.com/maps/api/staticmap
?size=400x400¢er=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Widoczne obszary
Obrazy mogą określać widoczny obszar, podając widoczne lokalizacje za pomocą parametru visible
. Parametr visible
instruuje usługę Static API Map, aby stworzyła mapę, tak by istniejące lokalizacje pozostały widoczne. (Parametr może być połączony z istniejącymi znacznikami lub ścieżkami, by wskazać widoczny obszar). Dzięki takiemu zdefiniowaniu widoczny obszar uniknie konieczności określania dokładnego poziomu powiększenia.
Następny przykład dotyczy mapy skupionej wokół Bostonu w stanie Massachusetts, która zawiera zarówno MIT, jak i Harvard Square w Cambridge w stanie Massachusetts:
https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Domniemane położenie
Standardowo musisz określić parametry adresu URL center
i zoom
, aby określić lokalizację i poziom powiększenia wygenerowanej mapy.
Jeśli jednak podasz parametry markers
, path
lub visible
, możesz pozwolić, aby interfejs statyczny interfejs API Map Google bezpośrednio określał prawidłowy środek i poziom powiększenia na podstawie oceny pozycji tych elementów.
Jeśli dostarczysz co najmniej 2 elementy, Statyczny interfejs API Map Google określi odpowiedni poziom i powiększenie, zapewniając duże marginesy zawartych elementów. Ten przykład pokazuje mapę z San Francisco, Oakland i San Jose, Kalifornia:
https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Większe rozmiary obrazów
Jeśli potrzebujesz zdjęć o rozmiarze większym niż 640 x 640 pikseli (lub 1280 x 1280 pikseli o skali 2), skontaktuj się z zespołem pomocy i podaj te informacje:
- Przypadek użycia i powody, dla których potrzebujesz dużych obrazów.
- niezależnie od tego, czy korzystasz z innych interfejsów Google Maps Platform API (Maps JavaScript API, Maps embed API, Maps SDK na Androida czy Maps SDK na iOS), i dlaczego nie spełniają one Twoich potrzeb.
- zrzuty ekranu, przykłady lub przykłady wykorzystania dużych rozmiarów obrazów;
- Szacowane miesięczne wykorzystanie zdjęć w dużych rozmiarach.
Sprawdzimy Twoje zgłoszenie na podstawie podanych przez Ciebie informacji i ustalimy, czy Twój przypadek użycia spełnia Warunki korzystania z usługi Google Maps Platform.
Maksymalny rozmiar, jakie możemy podać, to 2048 x 2048 pikseli.
Rozwiązywanie problemów i pomoc
Więcej informacji o korzystaniu z Maps Static API znajdziesz na stronie pomocy.
Interfejs Maps Static API może wyświetlać błąd lub ostrzeżenie, gdy coś pójdzie nie tak. Szczególną uwagę należy zwracać na ostrzeżenia, jeśli zauważysz, że na mapie brakuje czegoś. Warto też sprawdzić ostrzeżenia przed uruchomieniem nowej aplikacji. Ostrzeżenia mogą nie być od razu widoczne, ponieważ pojawiają się w nagłówku HTTP. Więcej informacji znajdziesz w przewodniku o błędach i ostrzeżeniach.