Google Maps API – jak zacząć: klucz, mapa na stronie i kontrola kosztów

Google Maps API (formalnie Google Maps Platform) to zestaw płatnych, rozliczanych za użycie interfejsów Google do map, geokodowania i wyznaczania tras. Żeby z niego skorzystać, potrzebujesz trzech rzeczy: projektu w Google Cloud, włączonej płatności oraz klucza API, który zabezpieczysz ograniczeniami. Prostą mapę na stronie wyświetlisz w kilkunastu liniach JavaScriptu.

Ten poradnik przeprowadza przez całość: od założenia klucza, przez działający przykład mapy z markerem, po zabezpieczenie klucza i kontrolę kosztów — bo przy Google Maps to właśnie rachunek bywa największą niespodzianką. Zakładam, że znasz podstawy HTML, CSS i JavaScriptu.

Czym jest Google Maps Platform i z jakich API się składa

Nie ma jednego „Google Maps API”. To rodzina usług podzielonych na grupy. Najczęściej używane:

Każde API rozliczane jest osobno i ma inną stawkę, dlatego włączaj tylko te, których faktycznie używasz. Dalej skupiam się na Maps JavaScript API, bo od niego zaczyna większość osób.

Krok 1: Projekt w Google Cloud i klucz API

1. Zaloguj się do Google Cloud Console kontem Google.
2. Utwórz nowy projekt (menu projektów u góry → Nowy projekt).
3. Włącz płatności dla projektu — bez tego API zwróci błąd nawet w ramach darmowego limitu. Google wymaga karty, ale dopóki mieścisz się w limicie, nie nalicza opłat.
4. Włącz potrzebne API: APIs & Services → Library → wyszukaj „Maps JavaScript API” → Enable.
5. Utwórz klucz: APIs & Services → Credentials → Create credentials → API key.
6. Od razu kliknij utworzony klucz i przejdź do jego ograniczeń (opisane niżej) — nie zostawiaj klucza bez ograniczeń.

Krok 2: Mapa z markerem na stronie

Współczesny, zalecany sposób to ładowanie API przez tzw. bootstrap loader i import bibliotek funkcją importLibrary, zamiast starego, pojedynczego tagu <script> z callback. Poniżej minimalny, kompletny przykład. Zamień TWOJ_KLUCZ na własny klucz.

<!doctype html>
<html lang="pl">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <style>
    /* Mapa musi mieć jawnie ustaloną wysokość, inaczej się nie pokaże */
    #mapa { height: 400px; width: 100%; }
  </style>
</head>
<body>
  <div id="mapa"></div>

  <script>
    // Oficjalny loader Google Maps (bootstrap)
    (g => { var h, a, k, p = "The Google Maps JavaScript API";
      var c = "google", l = "importLibrary", q = "__ib__", m = document,
      b = window; b = b[c] || (b[c] = {}); var d = b.maps || (b.maps = {}),
      r = new Set, e = new URLSearchParams, u = () => h || (h = new Promise(
      async (f, n) => { await (a = m.createElement("script"));
      e.set("libraries", [...r] + ""); for (k in g) e.set(k.replace(/[A-Z]/g,
      t => "_" + t[0].toLowerCase()), g[k]); e.set("callback", c + ".maps." + q);
      a.src = `https://maps.${c}apis.com/maps/api/js?` + e; d[q] = f;
      a.onerror = () => h = n(Error(p + " could not load.")); a.nonce =
      m.querySelector("script[nonce]")?.nonce || ""; m.head.append(a) }));
      d[l] ? console.warn(p + " only loads once. Ignoring:", g) :
      d[l] = (f, ...n) => r.add(f) && u().then(() => d[l](f, ...n)) })({
        key: "TWOJ_KLUCZ",
        v: "weekly",
      });

    async function initMap() {
      const { Map } = await google.maps.importLibrary("maps");
      const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

      const pozycja = { lat: 52.2297, lng: 21.0122 }; // Warszawa

      const mapa = new Map(document.getElementById("mapa"), {
        center: pozycja,
        zoom: 12,
        mapId: "DEMO_MAP_ID", // wymagane przez AdvancedMarkerElement
      });

      new AdvancedMarkerElement({
        map: mapa,
        position: pozycja,
        title: "Warszawa",
      });
    }

    initMap();
  </script>
</body>
</html>

Dwie rzeczy, na których najczęściej potykają się początkujący:

• Kontener mapy musi mieć wysokość. Bez height w CSS <div> ma 0 pikseli i mapy nie widać. Gdy mapa ma stać obok listy lokalizacji, oba elementy wygodnie ułożysz w siatce CSS Grid.
• AdvancedMarkerElement wymaga mapId. Identyfikator mapy tworzy się w konsoli (Map Management); na potrzeby testów można użyć dowolnej wartości, ale do stylowania mapy potrzebny jest prawdziwy identyfikator.

Stary new google.maps.Marker(...) nadal działa, ale jest oznaczony jako przestarzały (deprecated) — w nowych projektach używaj AdvancedMarkerElement.

Krok 3: Zabezpieczenie klucza API

Klucz do Maps JavaScript API jest wysyłany do przeglądarki, więc każdy może go odczytać w kodzie strony. Nie da się go ukryć — zabezpiecza się go inaczej, ograniczając to, skąd i do czego może być użyty. To kluczowy krok, bo skradziony, nieograniczony klucz może wygenerować Ci duży rachunek.

W konsoli, w ustawieniach klucza (APIs & Services → Credentials → Twój klucz):

1. Application restrictions → Websites (HTTP referrers). Dodaj dokładnie swoje domeny, np. https://twojadomena.pl/* oraz http://localhost:*/* do testów. Klucz zadziała wtedy tylko na Twoich stronach.
2. API restrictions. Ogranicz klucz wyłącznie do API, których używasz (np. tylko Maps JavaScript API). Klucz uniwersalny jest groźny, bo nadaje się do wszystkich płatnych usług.

Uwaga: Klucze do API wywoływanych z serwera (Geocoding, Routes, Places bez komponentów przeglądarkowych) trzymaj po stronie serwera, nigdy w kodzie frontendu. Ogranicz je przez adres IP serwera i przechowuj w zmiennych środowiskowych, a nie w repozytorium. Zasady bezpiecznego projektowania takich usług opisuje tekst Wprowadzenie do REST API.

Jeśli klucz przypadkiem wyciekł (np. trafił do publicznego repozytorium), od razu go usuń lub wygeneruj nowy i podmień — to częsty mechanizm przejmowania, pokrewny kradzieży poświadczeń opisanej przy API.

Krok 4: Kontrola kosztów

Google Maps Platform rozlicza się za liczbę zapytań, a stawki różnią się między API — inaczej liczone jest wyświetlenie mapy, inaczej geokodowanie, a inaczej wyznaczenie trasy. Jest darmowy limit miesięczny, poniżej którego nie płacisz, ale po jego przekroczeniu naliczane są opłaty.

Dokładne, aktualne stawki i wielkość darmowego limitu podaje wyłącznie oficjalny cennik Google Maps Platform — Google okresowo zmienia zarówno ceny, jak i zasady darmowego progu, dlatego nie opieraj się na liczbach z artykułów sprzed kilku lat.

Niezależnie od stawek zrób trzy rzeczy, które chronią przed niespodziewanym rachunkiem:

1. Ustaw budżet z alertami w Billing → Budgets & alerts (np. powiadomienie przy 50%, 90% i 100% zakładanej kwoty). Alert nie zablokuje usługi, ale ostrzeże.
2. Ustaw limity zapytań na dobę dla każdego API w APIs & Services → wybrane API → Quotas. To twarde ograniczenie, które powstrzyma lawinę opłat przy błędzie w kodzie lub ataku.
3. Ogranicz klucz jak w kroku 3 — to jednocześnie zabezpieczenie przed kosztami generowanymi przez cudze strony.

Technicznie koszty obniżysz też, nie odświeżając mapy bez potrzeby: dla wielu statycznych podglądów taniej jest użyć Maps Static API (obrazek) niż pełnej mapy JavaScript, a przy dużej liczbie markerów stosować ich grupowanie (klastrowanie) biblioteką MarkerClusterer.

Najczęstsze problemy

• „This page can’t load Google Maps correctly” / szara mapa.** Zwykle brak włączonej płatności, nieaktywne API albo niepoprawne ograniczenia klucza (np. zła domena w HTTP referrer). Szczegół błędu zawsze podpowiada konsola przeglądarki.
• RefererNotAllowedMapError. Domena, z której ładujesz mapę, nie pasuje do ograniczeń klucza. Dodaj ją (pamiętaj o http://localhost:*/* przy pracy lokalnej).
• ApiNotActivatedMapError. Nie włączyłeś danego API w projekcie.
• Mapa niewidoczna, choć brak błędów.** Kontener nie ma wysokości w CSS.
• Marker się nie pokazuje przy AdvancedMarkerElement.** Brak mapId w konfiguracji mapy.

Czy warto wybrać Google Maps

Google Maps API ma bardzo dobrą jakość danych, globalne pokrycie i bogate funkcje (Street View, Places, Routes), więc dla wielu projektów komercyjnych jest naturalnym wyborem. Ma jednak dwie wady: wymaga podania karty i potrafi być drogie przy dużym ruchu.

Jeśli potrzebujesz tylko prostej mapy bez funkcji Google, warto rozważyć alternatywy oparte na OpenStreetMap, np. biblioteki Leaflet lub MapLibre GL z danymi od dostawców takich jak MapTiler. Są tańsze (często z hojniejszym darmowym progiem) i otwarte, choć bez usług typu Street View czy pełnej bazy miejsc Google. Wybór zależy od tego, czy korzystasz z unikalnych danych Google, czy wystarczy Ci sama mapa. Dobrą praktyką, niezależnie od dostawcy, jest wczytywanie mapy dopiero, gdy jest potrzebna (lazy loading), bo biblioteki mapowe są ciężkie i spowalniają start strony — ich realny wpływ na czas ładowania sprawdzisz narzędziem w rodzaju WebPageTest.