Umieszczanie mapy

Z tego przewodnika dowiesz się, jak umieścić interaktywną mapę na stronie internetowej.

Tworzenie adresu URL interfejsu Maps Embed API

Oto przykładowy adres URL, który wczytuje interfejs Maps Embed API:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

Zastąp:

Dodaj adres URL do elementu iframe.

Aby używać Maps Embed API na swojej stronie internetowej, ustaw utworzony adres URL jako wartość atrybutu src elementu iframe. Rozmiar mapy możesz kontrolować za pomocą atrybutów height i width elementu iframe, na przykład:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

Powyższy przykład elementu iframe używa dodatkowych właściwości:

  • Właściwość allowfullscreen, która umożliwia wyświetlanie niektórych części mapy na pełnym ekranie.
  • Właściwości frameborder="0" i style="border:0", które usuwają standardowe obramowanie elementu iframe wokół mapy.
  • Właściwość referrerpolicy="strict-origin-when-cross-origin" sprawia, że przeglądarka wysyła do Google domenę Twojej witryny jako nagłówek Referer. Dzięki temu ograniczenia klucza interfejsu API mogą zweryfikować żądanie, a konkretne ścieżki do stron pozostają prywatne.

Możesz zmienić rozmiar elementu iframe, aby dopasować go do struktury i wyglądu swojej witryny, ale uważamy, że użytkownikom łatwiej jest korzystać z większych map. Pamiętaj, że mapy umieszczone na stronie nie są obsługiwane, jeśli ich rozmiar jest mniejszy niż 200 pikseli w dowolnym wymiarze.

Informacje o stronie odsyłającej i ograniczenia klucza interfejsu API

Jeśli witryna hostująca ma metatag referrer ustawiony na no-referrer lub same-origin, przeglądarka nie wyśle nagłówka Referer do Google. Może to spowodować, że ograniczenie klucza interfejsu API odrzuci żądania. Aby ograniczenie działało prawidłowo, dodaj do elementu iframe właściwość referrerpolicy, jak w przykładzie powyżej, aby wyraźnie zezwolić na wysyłanie nagłówków Referer do Google.

  • strict-origin-when-cross-origin (zalecane): wysyła do Google tylko domenę podstawową (np. https://example.com/). Dzięki temu ścieżki do konkretnych stron pozostaną prywatne, a ograniczenia klucza interfejsu API będą nadal działać.
  • no-referrer-when-downgrade (starsza wersja): wysyła cały adres URL, w tym konkretne ścieżki do stron i parametry zapytania (np. https://example.com/contact?user=123).

Więcej informacji o nagłówku Referrer-Policy

Wybieranie trybów mapy

W adresie URL żądania możesz określić jeden z tych trybów mapy:

  • place: wyświetla pinezkę mapy w określonym miejscu lub pod określonym adresem, np. przy punkcie orientacyjnym, firmie, obiekcie geograficznym lub mieście.
  • view: zwraca mapę bez znaczników i wskazówek dojazdu.
  • directions: wyświetla ścieżkę między co najmniej 2 określonymi punktami na mapie, a także odległość i czas podróży.
  • streetview: pokazuje interaktywne widoki panoramiczne z wyznaczonych lokalizacji.
  • search: pokazuje wyniki wyszukiwania w widocznym regionie mapy.

Tryb place

Ten adres URL używa trybu mapy place, aby wyświetlić znacznik mapy przy wieży Eiffla:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

Możesz użyć tych parametrów:

Parametr Typ Opis Akceptowane wartości
q Wymagany Określa lokalizację znacznika na mapie. Nazwa miejsca, adres, plus code lub identyfikator miejsca z kodowaniem URL. Interfejs Maps Embed API obsługuje zarówno +, jak i %20 podczas zastępowania spacji. Na przykład przekonwertuj „City Hall, New York, NY” na City+Hall,New+York,NY lub kody Plus Code „849VCWC8+R9” na 849VCWC8%2BR9.
center Opcjonalny Określa środek widoku mapy. Akceptuje wartości szerokości i długości geograficznej rozdzielone przecinkami, na przykład: 37.4218,-122.0840.
zoom Opcjonalny Ustawia początkowy poziom powiększenia mapy. Wartości od 0 (cały świat) do 21 (poszczególne budynki). Górny limit może się różnić w zależności od danych mapy dostępnych w wybranej lokalizacji.
maptype Opcjonalny Określa typ kafelków mapy do wczytania. roadmap (domyślna) lub satellite
language Opcjonalny Określa język elementów interfejsu i etykiet na kafelkach mapy. Domyślnie odwiedzający zobaczą mapę w swoim języku. 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 i etykiety do wyświetlenia na podstawie uwarunkowań geopolitycznych. Akceptuje kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode, który jest mapowany na znane dwuznakowe wartości ccTLD („domena najwyższego poziomu”). Obsługiwane regiony znajdziesz w szczegółach dotyczących zasięgu Google Maps Platform.

Tryb view

W tym przykładzie użyto trybu view i opcjonalnego parametru maptype, aby wyświetlić widok satelitarny mapy:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

Możesz użyć tych parametrów:

Parametr Typ Opis Akceptowane wartości
center Wymagany Określa środek widoku mapy. Akceptuje wartości szerokości i długości geograficznej rozdzielone przecinkami, na przykład: 37.4218,-122.0840.
zoom Opcjonalny Ustawia początkowy poziom powiększenia mapy. Wartości od 0 (cały świat) do 21 (poszczególne budynki). Górny limit może się różnić w zależności od danych mapy dostępnych w wybranej lokalizacji.
maptype Opcjonalny Określa typ kafelków mapy do wczytania. roadmap (domyślna) lub satellite
language Opcjonalny Określa język elementów interfejsu i etykiet na kafelkach mapy. Domyślnie odwiedzający zobaczą mapę w swoim języku. 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 i etykiety do wyświetlenia na podstawie uwarunkowań geopolitycznych. Akceptuje kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode, który jest mapowany na znane dwuznakowe wartości ccTLD („domena najwyższego poziomu”). Obsługiwane regiony znajdziesz w szczegółach dotyczących zasięgu Google Maps Platform.

Tryb directions

W tym przykładzie użyto trybu directions, aby wyświetlić trasę między Oslo a Telemarkiem w Norwegii, odległość i czas podróży z ominięciem opłat i autostrad.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

Możesz użyć tych parametrów:

Parametr Typ Opis Akceptowane wartości
origin Wymagany Określa punkt początkowy, od którego mają być wyświetlane wskazówki dojazdu. Nazwa miejsca, adres, plus code, współrzędne geograficzne lub identyfikator miejsca w formacie URL-escaped. Interfejs Maps Embed API obsługuje zarówno +, jak i %20 podczas zastępowania spacji. Na przykład przekonwertuj „City Hall, New York, NY” na City+Hall,New+York,NY lub kody Plus Code „849VCWC8+R9” na 849VCWC8%2BR9.
destination Wymagany Określa punkt końcowy trasy. Nazwa miejsca, adres, plus code, współrzędne geograficzne lub identyfikator miejsca w formacie URL-escaped. Interfejs Maps Embed API obsługuje zarówno +, jak i %20 podczas zastępowania spacji. Na przykład przekonwertuj „City Hall, New York, NY” na City+Hall,New+York,NY lub kody Plus Code „849VCWC8+R9” na 849VCWC8%2BR9.
waypoints Opcjonalny Określa co najmniej 1 miejsce pośrednie, przez które ma przebiegać trasa między miejscem początkowym a docelowym. Nazwa miejsca, adres lub identyfikator miejsca. Możesz określić wiele punktów pośrednich, rozdzielając miejsca pionową kreską (|) (np. Berlin,Germany|Paris,France). Możesz określić maksymalnie 20 punktów pośrednich.
mode Opcjonalny Określa sposób podróżowania. Jeśli nie określisz środka transportu, interfejs Maps Embed API wyświetli co najmniej 1 najbardziej odpowiedni środek transportu dla danej trasy. driving, walking (który preferuje ścieżki dla pieszych i chodniki, jeśli są dostępne), bicycling (który preferuje trasy ze ścieżkami rowerowymi i preferowanymi ulicami, jeśli są dostępne), transit lub flying.
avoid Opcjonalny Określa elementy, których należy unikać we wskazówkach dojazdu. Pamiętaj, że nie wyklucza to tras, które zawierają ograniczone funkcje, ale wpływa na wynik, faworyzując bardziej korzystne trasy. tolls, ferries lub highways. Poszczególne wartości rozdzielaj znakiem kreski pionowej (np. avoid=tolls|highways).
units Opcjonalny Określa system miar (metryczny lub imperialny) używany do wyświetlania odległości w wynikach. Jeśli nie określono units, jednostki są określane na podstawie kraju zapytania (origin). metric lub imperial
center Opcjonalny Określa środek widoku mapy. Akceptuje wartości szerokości i długości geograficznej rozdzielone przecinkami, na przykład: 37.4218,-122.0840.
zoom Opcjonalny Ustawia początkowy poziom powiększenia mapy. Wartości od 0 (cały świat) do 21 (poszczególne budynki). Górny limit może się różnić w zależności od danych mapy dostępnych w wybranej lokalizacji.
maptype Opcjonalny Określa typ kafelków mapy do wczytania. roadmap (domyślna) lub satellite
language Opcjonalny Określa język elementów interfejsu i etykiet na kafelkach mapy. Domyślnie odwiedzający zobaczą mapę w swoim języku. 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 i etykiety do wyświetlenia na podstawie uwarunkowań geopolitycznych. Akceptuje kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode, który jest mapowany na znane dwuznakowe wartości ccTLD („domena najwyższego poziomu”). Obsługiwane regiony znajdziesz w szczegółach dotyczących zasięgu Google Maps Platform.

Tryb streetview

Interfejs Maps Embed API umożliwia wyświetlanie zdjęć Street View jako interaktywnych panoram z wyznaczonych lokalizacji na całym obsługiwanym obszarze. Dostępne są też zdjęcia sferyczne przesłane przez użytkowników i kolekcje specjalne Street View.

Każda panorama Street View zapewnia pełny widok 360 stopni z jednej lokalizacji. Zdjęcia obejmują 360 stopni w poziomie (pełny obrót) i 180 stopni w pionie (od góry do dołu). Tryb streetview udostępnia przeglądarkę, która renderuje wynikową panoramę jako sferę z kamerą w środku. Możesz manipulować kamerą, aby kontrolować powiększenie i orientację.

Oto przykład panoramy w trybie streetview:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

Wymagany jest jeden z tych parametrów adresu URL:

  • location akceptuje szerokość i długość geograficzną jako wartości rozdzielone przecinkami (46.414382,10.013988). Interfejs API wyświetla panoramę sfotografowaną najbliżej tej lokalizacji. Zdjęcia Street View są okresowo odświeżane i za każdym razem mogą być robione z nieco innych pozycji, dlatego po aktualizacji zdjęć Twoja lokalizacja może zostać przypisana do innej panoramy.

  • pano to identyfikator konkretnej panoramy. Jeśli określisz pano, możesz też określić location. Parametr location jest używany tylko wtedy, gdy interfejs API nie może znaleźć identyfikatora panoramy.

Te parametry adresu URL są opcjonalne:

Parametr Typ Opis Akceptowane wartości
heading Opcjonalny Wskazuje kierunek kompasu kamery w stopniach zgodnie z ruchem wskazówek zegara od północy. Wartość w stopniach od –180° do 360°
pitch Opcjonalny określa kąt nachylenia kamery w górę lub w dół. Wartości dodatnie powodują skierowanie kamery w górę, a ujemne – w dół. Domyślne nachylenie 0° jest ustawiane na podstawie pozycji kamery w momencie zrobienia zdjęcia. Z tego powodu nachylenie 0° często, ale nie zawsze, jest poziome. Na przykład zdjęcie zrobione na wzgórzu będzie prawdopodobnie miało domyślne nachylenie, które nie jest poziome. Wartość w stopniach od -90° do 90°
fov Opcjonalny określa poziome pole widzenia obrazu. Domyślna wartość to 90°. W przypadku widocznego obszaru o stałym rozmiarze pole widzenia można uznać za poziom powiększenia, przy czym mniejsze liczby oznaczają większe powiększenie. Wartość w stopniach, w zakresie 10°–100°
center Opcjonalny Określa środek widoku mapy. Akceptuje wartości szerokości i długości geograficznej rozdzielone przecinkami, na przykład: 37.4218,-122.0840.
zoom Opcjonalny Ustawia początkowy poziom powiększenia mapy. Wartości od 0 (cały świat) do 21 (poszczególne budynki). Górny limit może się różnić w zależności od danych mapy dostępnych w wybranej lokalizacji.
maptype Opcjonalny Określa typ kafelków mapy do wczytania. roadmap (domyślna) lub satellite
language Opcjonalny Określa język elementów interfejsu i etykiet na kafelkach mapy. Domyślnie odwiedzający zobaczą mapę w swoim języku. 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 i etykiety do wyświetlenia na podstawie uwarunkowań geopolitycznych. Akceptuje kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode, który jest mapowany na znane dwuznakowe wartości ccTLD („domena najwyższego poziomu”). Obsługiwane regiony znajdziesz w szczegółach dotyczących zasięgu Google Maps Platform.

Tryb search

Tryb Search wyświetla wyniki wyszukiwania w widocznym regionie mapy. Zalecamy określenie lokalizacji wyszukiwania przez dodanie lokalizacji do wyszukiwanego hasła (record+stores+in+Seattle) lub dodanie parametrów center i zoom, aby ograniczyć wyszukiwanie.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

Możesz użyć tych parametrów:

Parametr Typ Opis Akceptowane wartości
q Wymagany Definiuje wyszukiwane słowa. Może zawierać ograniczenie geograficzne, np. in+Seattle lub near+98033.
center Opcjonalny Określa środek widoku mapy. Akceptuje wartości szerokości i długości geograficznej rozdzielone przecinkami, na przykład: 37.4218,-122.0840.
zoom Opcjonalny Ustawia początkowy poziom powiększenia mapy. Wartości od 0 (cały świat) do 21 (poszczególne budynki). Górny limit może się różnić w zależności od danych mapy dostępnych w wybranej lokalizacji.
maptype Opcjonalny Określa typ kafelków mapy do wczytania. roadmap (domyślna) lub satellite
language Opcjonalny Określa język elementów interfejsu i etykiet na kafelkach mapy. Domyślnie odwiedzający zobaczą mapę w swoim języku. 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 i etykiety do wyświetlenia na podstawie uwarunkowań geopolitycznych. Akceptuje kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode, który jest mapowany na znane dwuznakowe wartości ccTLD („domena najwyższego poziomu”). Obsługiwane regiony znajdziesz w szczegółach dotyczących zasięgu Google Maps Platform.

Parametry identyfikatora miejsca

Interfejs Maps Embed API obsługuje używanie identyfikatorów miejsc zamiast podawania nazwy lub adresu miejsca. Identyfikatory miejsc to niezmienny sposób na jednoznaczne identyfikowanie miejsca. Więcej informacji znajdziesz w dokumentacji Places API (New).

Interfejs Maps Embed API akceptuje identyfikatory miejsc w tych parametrach adresu URL:

  • q
  • origin
  • destination
  • waypoints

Aby użyć identyfikatora miejsca, musisz najpierw dodać prefiks place_id:. Ten kod określa ratusz w Nowym Jorku jako miejsce początkowe w żądaniu wskazówek dojazdu: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius określa promień (w metrach), w którym ma być wyszukiwana panorama, ze środkiem w podanej szerokości i długości geograficznej. Prawidłowe wartości to nieujemne liczby całkowite. Wartość domyślna to 50.

  • source ogranicza wyszukiwanie w Street View do wybranych źródeł. Prawidłowe wartości to:

    • default używa domyślnych źródeł Street View. Wyszukiwanie nie jest ograniczone do konkretnych źródeł.
    • outdoor ogranicza wyszukiwanie do kolekcji zewnętrznych. Kolekcje zdjęć wnętrz nie są uwzględniane w wynikach wyszukiwania. Pamiętaj, że dla określonej lokalizacji mogą nie istnieć panoramy zewnętrzne. Pamiętaj też, że wyszukiwanie zwraca tylko panoramy, w przypadku których można określić, czy zostały zrobione w pomieszczeniu czy na zewnątrz. Na przykład zdjęcia sferyczne nie są zwracane, ponieważ nie wiadomo, czy zostały zrobione w pomieszczeniu czy na zewnątrz.