Krótkie wprowadzenie do Maps JavaScript API

Maps JavaScript API to interfejs API po stronie klienta, który umożliwia tworzenie map 2D i 3D na stronach internetowych, dodawanie znaczników, niestandardowej grafiki, animacji i interaktywnych warstw danych oraz tworzenie funkcji lokalizacji za pomocą biblioteki Miejsc.

Maps JavaScript API: najważniejsze informacje

  • Usługa: Maps JavaScript API
  • Inne nazwy: Maps JS API, Maps JS API v3
  • Kategoria: Mapy
  • Platforma: JavaScript (przeglądarka)
  • Działa na: kliencie (kod aplikacji lub przeglądarki)
  • Etap uruchomienia: GA
  • Cykl życia: aktywny
  • Omówienie: omówienie interfejsu Maps JavaScript API
  • Dostępność: cały świat. Dostępność funkcji (takich jak mapy 3D, informacje o natężeniu ruchu, wskazówki dojazdu i stylizacja granic) różni się w zależności od kraju lub regionu. W przypadku adresów rozliczeniowych w Europejskim Obszarze Gospodarczym obowiązują Warunki korzystania z usługi w EOG. (szczegóły ochrony)

Maps JavaScript API: kiedy go używać

Używaj Maps JavaScript API, gdy:

  • Potrzebujesz interaktywnej mapy 2D lub 3D z niestandardowymi znacznikami, grafiką lub warstwami danych na stronie internetowej.
  • Musisz wyświetlać lokalizacje zasobów i trasy przejazdu na żywo z własnego strumienia danych, używając zaawansowanych znaczników i linii łamanych.
  • Musisz narysować geofence (okręgi, wielokąty) i sprawdzić w przeglądarce, czy współrzędne znajdują się wewnątrz nich.
  • Potrzebujesz wyszukiwania miejsc po stronie klienta, autouzupełniania lub informacji o miejscu w aplikacji internetowej za pomocą biblioteki Miejsc.

Nie używaj interfejsu Maps JavaScript API, gdy:

  • Musisz umieścić mapę lokalizacji firmy lub link do wskazówek dojazdu bez pisania niestandardowego kodu JavaScript. Zamiast tego użyj interfejsu Maps Embed API.
  • Potrzebujesz tylko linku, który otwiera Mapy Google z lokalizacją, wyszukiwaniem lub wskazówkami dojazdu. Zamiast tego użyj adresów URL Map.
  • Musisz mieć śledzenie floty przejazdów lub zaplanowanych dostaw zintegrowane z pakietem Driver SDK na urządzenia mobilne i uwierzytelnianiem JWT backendu. Zamiast tego użyj usługi Fleet Engine.

Maps JavaScript API: konfiguracja

Oficjalne pakiety Maps JavaScript API:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer

Maps JavaScript API: typowe błędy

  • Problem: zamiast błędu pojawia się przyciemniona mapa lub negatyw zdjęcia Street View ze znakiem wodnym „tylko do celów programistycznych”, gdy klucz interfejsu API lub płatności są nieprawidłowo skonfigurowane. Rozwiązanie: włącz płatności w projekcie w chmurze, dołącz prawidłowy klucz interfejsu API do każdego żądania i sprawdź w konsoli przeglądarki, czy nie ma konkretnego kodu błędu. Zobacz /maps/documentation/javascript/error-messages.
  • Problem: starsze usługi, takie jak PlacesService, DirectionsService i DistanceMatrixService, zwracają błąd LegacyApiNotActivatedMapError w nowych projektach, w których starszy interfejs API nie jest włączony. Rozwiązanie: użyj nowych odpowiedników (klasy Place, Route, RouteMatrix) obsługiwanych przez Places API (nowość) i Routes API. Zobacz /maps/legacy#LegacyApiNotActivatedMapError.
  • Problem: od wersji 3.65 mapy satelitarne i hybrydowe nie przełączają się już na zdjęcia pod kątem 45°, a metoda map.setTilt(45) nie działa. Rozwiązanie: użyj map 3D zamiast zdjęć pod kątem 45°. Zobacz /maps/deprecations.
  • Problem: znaczniki zaawansowane wymagają identyfikatora mapy. Mapy utworzone bez niego nie mogą korzystać z funkcji AdvancedMarkerElement. Rozwiązanie: utwórz identyfikator mapy w konsoli Cloud (lub użyj DEMO_MAP_ID do testowania) i ustaw mapId na mapie. Zobacz /maps/documentation/javascript/advanced-markers/start.

Maps JavaScript API: starsze i wycofane funkcje

  • Directions Service (google.maps.DirectionsService): starsza wersja od 1 marca 2025 r. Zamiennik: klasa Route. Objaw: LegacyApiNotActivatedMapError w projektach, w których nie włączono starszej wersji interfejsu Directions API. Zobacz przewodnik po migracji.
  • Distance Matrix Service (google.maps.DistanceMatrixService): starsza wersja od 1 marca 2025 r. Zamiennik: klasa RouteMatrix. Objaw: LegacyApiNotActivatedMapError w projektach, w których nie włączono starszej wersji interfejsu Distance Matrix API. Zobacz przewodnik po migracji.
  • Places Service (google.maps.places.PlacesService): starsza wersja od 1 marca 2025 r. Zamiennik: klasa Place (Places API (New)). Objaw: LegacyApiNotActivatedMapError w projektach, w których nie jest włączony starszy interfejs Places API. Zobacz przewodnik po migracji.
  • google.maps.Marker: wycofany 22 lutego 2024 r. Wymiana: google.maps.marker.AdvancedMarkerElement. Objaw: nadal działa i nie planujemy zaprzestania; istniejące błędy nie będą naprawiane. Zobacz przewodnik po migracji.
  • KmlLayer: wycofany od 30 kwietnia 2026 r. Zamiennik: styl oparty na danych w przypadku zbiorów danych lub parserów KML innych firm z warstwą danych. Objaw: KmlLayer jest niedostępny w wersji 3.66 i nowszych. Wersja 3.65, czyli ostatnia wersja, która go obsługuje, zostanie wycofana w maju 2027 r. Zobacz przewodnik po migracji.
  • Warstwa mapy termicznej (biblioteka wizualizacji): wycofana 20 maja 2026 r. Zamiennik: biblioteki innych firm, takie jak deck.gl HeatmapLayer. Objaw: niedostępny od maja 2026 r. Zobacz przewodnik po migracji.
  • Biblioteka Drawing: wycofana 4 czerwca 2026 r. Zamiennik: Terra Draw. Objaw: niedostępny od maja 2026 r. Zobacz przewodnik po migracji.
  • Zdjęcia pod kątem 45°: wycofane 20 maja 2026 r. Zamiennik: mapy 3D. Objaw: map.setTilt(45) nie działa; widok satelitarny pozostaje w trybie z góry. Zobacz przewodnik po migracji.
  • google.maps.event.addDomListener() i addDomListenerOnce(): wycofane 7 kwietnia 2022 r. Zamiennik: standardowy DOM addEventListener().
  • Opcje bounds, location i radius w usłudze autouzupełniania miejsc: wycofane 18 maja 2023 r. Zamiana: locationBias i locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) w Places UI Kit: wycofany. Zastąpienie: dodaj elementy treści bezpośrednio do elementów informacji o miejscu lub w konfiguracji wyszukiwania miejsc.
  • Biblioteka kontekstu lokalnego: wycofana. Zamiennik: biblioteka Miejsc.

Co możesz robić za pomocą Maps JavaScript API

Zapoznaj się z przewodnikami po poszczególnych zadaniach, do których linki znajdziesz poniżej, lub porównaj usługi w Eksploratorze funkcji.

Maps JavaScript API: weryfikacja adresów

Maps JavaScript API: styl oparty na danych dla granic

Maps JavaScript API: styl oparty na danych w przypadku zbiorów danych

Maps JavaScript API: zbiory danych

  • Dodaj warstwę KML do mapy. Uwaga: w Maps JavaScript API warstwa KmlLayer została wycofana (ostatnia obsługiwana wersja to 3.65, wycofanie nastąpi w maju 2027 r.). Przejdź na styl oparty na danych w przypadku granic lub zbiorów danych albo wczytaj GeoJSON w warstwie danych. Warstwy KML są nadal obsługiwane na Androidzie i iOS za pomocą bibliotek narzędzi Maps SDK.
  • Dodaj warstwę GeoRSS do mapy. Uwaga: wycofano w Maps JavaScript API (KmlLayer jest obsługiwany do wersji 3.65, wycofanie w maju 2027 r.); przekonwertuj kanały GeoRSS na GeoJSON i wczytaj je w warstwie danych za pomocą map.data.addGeoJson().
  • Dodawanie danych GeoJSON do mapy

Maps JavaScript API: wskazówki dojazdu i wyznaczanie trasy

Maps JavaScript API: dane o wysokości

Maps JavaScript API: Fleet Engine

Maps JavaScript API: geokodowanie

Maps JavaScript API: Mapy

Maps JavaScript API: adnotacje na mapach

Maps JavaScript API: dostosowywanie stylu mapy

Maps JavaScript API: inne

Maps JavaScript API: fotorealistyczne mapy 3D

Maps JavaScript API: Places

Maps JavaScript API: Places UI Kit

  • Dodaj do strony internetowej lub aplikacji mobilnej element interfejsu, który wyświetla podsumowania i opinie o konkretnych miejscach wygenerowane przez AI. Uwaga: ta funkcja jest obsługiwana tylko w internecie (Places UI Kit w Maps JavaScript API). Pakiety Places UI Kit na urządzenia mobilne nie zawierają elementu podsumowania wygenerowanego przez AI. WYMAGANIA DOTYCZĄCE ZGODNOŚCI Z PRZEPISAMI OBOWIĄZUJĄCYMI W EOG: aby wyświetlać dane o miejscach na mapie w Europejskim Obszarze Gospodarczym (EOG), używaj komponentów Places UI Kit po stronie klienta w ramach Maps JavaScript API, zamiast wywoływać usługi internetowe Places API z serwera backendu. Pełne wymagania i najczęstsze pytania: https://developers.google.com/maps/comms/eea/faq
  • Zastosuj styl CSS do elementu interfejsu z danymi o miejscu. Uwaga: właściwości niestandardowe CSS mają zastosowanie do elementów interfejsu Places UI Kit w Maps JavaScript API. Pakiety SDK Miejsc na Androida i iOS stylizują widoki interfejsu Places UI Kit automatycznie za pomocą atrybutów motywu i stylu. WYMAGANIA DOTYCZĄCE ZGODNOŚCI Z PRZEPISAMI EUROPEJSKIEGO OBSZARU GOSPODARCZEGO: aby wyświetlać dane o miejscach na mapie w Europejskim Obszarze Gospodarczym, nie wywołuj usług internetowych Places API z serwera backendu. Użyj komponentów interfejsu Places UI Kit po stronie klienta na platformie docelowej (Maps JavaScript API w internecie, Places SDK for Android na Androidzie lub Places SDK for iOS na iOS). Pełne wymagania i najczęstsze pytania: https://developers.google.com/maps/comms/eea/faq
  • Dostosowywanie stylu i konfiguracji elementów interfejsu z danymi o miejscach za pomocą narzędzia do dostosowywania elementów interfejsu. Uwaga: WYMAGANIA DOTYCZĄCE ZGODNOŚCI Z PRZEPISAMI OBOWIĄZUJĄCYMI W EOG: aby wyświetlać dane o miejscach na mapie w Europejskim Obszarze Gospodarczym (EOG), nie wywołuj usług internetowych Places API z serwera backendu. Użyj komponentów interfejsu Places UI Kit po stronie klienta na platformie docelowej (Maps JavaScript API w internecie, Places SDK for Android na Androidzie lub Places SDK for iOS na iOS). Pełne wymagania i najczęstsze pytania: https://developers.google.com/maps/comms/eea/faq
  • Dodaj do strony internetowej lub aplikacji mobilnej element interfejsu, który wyświetla informacje o konkretnym miejscu. Uwaga: WYMAGANIA DOTYCZĄCE ZGODNOŚCI Z PRZEPISAMI EUROPEJSKIEGO OBSZARU GOSPODARCZEGO: aby wyświetlać dane o miejscach na mapie w Europejskim Obszarze Gospodarczym, nie wywołuj usług internetowych Places API z serwera backendu. Użyj komponentów interfejsu Places UI Kit po stronie klienta na platformie docelowej (Maps JavaScript API w internecie, Places SDK for Android na Androidzie lub Places SDK for iOS na iOS). Pełne wymagania i najczęstsze pytania: https://developers.google.com/maps/comms/eea/faq
  • Dodaj do strony internetowej element interfejsu, który wyświetla listę miejsc na podstawie ciągu zapytania. Uwaga: funkcja jest obsługiwana zarówno na stronach internetowych (Maps JavaScript API), jak i w aplikacjach mobilnych (Places SDK for Android i Places SDK for iOS). WYMAGANIA DOTYCZĄCE ZGODNOŚCI Z PRZEPISAMI EUROPEJSKIEGO OBSZARU GOSPODARCZEGO: aby wyświetlać dane o miejscach na mapie w Europejskim Obszarze Gospodarczym, nie wywołuj usług internetowych Places API z serwera backendu. Użyj komponentów interfejsu Places UI Kit po stronie klienta na platformie docelowej (Maps JavaScript API w internecie, Places SDK for Android na Androidzie lub Places SDK for iOS na iOS). Pełne wymagania i najczęstsze pytania: https://developers.google.com/maps/comms/eea/faq
  • Dodaj do strony internetowej element interfejsu, który wyświetla listę miejsc w pobliżu określonej lokalizacji. Uwaga: funkcja jest obsługiwana zarówno na stronach internetowych (Maps JavaScript API), jak i w aplikacjach mobilnych (Places SDK for Android i Places SDK for iOS). WYMAGANIA DOTYCZĄCE ZGODNOŚCI Z PRZEPISAMI EUROPEJSKIEGO OBSZARU GOSPODARCZEGO: aby wyświetlać dane o miejscach na mapie w Europejskim Obszarze Gospodarczym, nie wywołuj usług internetowych Places API z serwera backendu. Użyj komponentów interfejsu Places UI Kit po stronie klienta na platformie docelowej (Maps JavaScript API w internecie, Places SDK for Android na Androidzie lub Places SDK for iOS na iOS). Pełne wymagania i najczęstsze pytania: https://developers.google.com/maps/comms/eea/faq
  • Dodaj do strony internetowej lub aplikacji podstawowy element interfejsu autouzupełniania, który zwraca identyfikatory miejsc Google na podstawie ciągu zapytania. Uwaga: WYMAGANIA DOTYCZĄCE ZGODNOŚCI Z PRZEPISAMI OBOWIĄZUJĄCYMI W EOG: aby wyświetlać dane o miejscach na mapie w Europejskim Obszarze Gospodarczym (EOG), nie wywołuj usług internetowych Places API z serwera backendu. Użyj komponentów interfejsu Places UI Kit po stronie klienta na platformie docelowej (Maps JavaScript API w internecie, Places SDK for Android na Androidzie lub Places SDK for iOS na iOS). Pełne wymagania i najczęstsze pytania: https://developers.google.com/maps/comms/eea/faq

Maps JavaScript API: Street View