Mapa Google nie wyświetla się na stronie? Jak skonfigurować Google Maps API w 2026 roku

Zamiast mapy na stronie kontaktowej pojawia się komunikat „Ups... Coś poszło nie tak. Ta strona nie wczytała Map Google prawidłowo”? Nie musi to oznaczać awarii Google Maps.

W przypadku stron korzystających z Google Maps JavaScript API przyczyną może być m.in. nieprawidłowy klucz API, brak aktywnej usługi, problem z rozliczeniami, błędne ograniczenia klucza lub nieaktualny sposób uwierzytelniania. Dokładną przyczynę można ustalić na podstawie komunikatu wyświetlanego w konsoli przeglądarki.

W ostatnich latach Google wprowadził również istotne zmiany w Google Maps Platform. Dlatego konfiguracja mapy, która działała przez wiele lat, może obecnie wymagać aktualizacji.

Co zmieniło się w Google Maps Platform?

1. Stare identyfikatory Client ID przestały działać

To jedna z najważniejszych zmian dla starszych stron internetowych.

Google zdeprecjonował identyfikatory Maps Platform Client ID 26 maja 2025 roku. Od 31 maja 2026 roku nie można już używać ich do uwierzytelniania ruchu Google Maps Platform. Google wymaga migracji na klucze API.

Jeżeli więc starsza integracja zawiera parametr:
client=

zamiast:
key=

warto sprawdzić, czy strona nie korzysta jeszcze z wycofanego sposobu uwierzytelniania. Google wprost zaleca w takim przypadku migrację z Client ID na API Key.

2. Zmienił się sposób naliczania bezpłatnego wykorzystania Google Maps

1 marca 2025 roku Google zmienił model rozliczeń Google Maps Platform. Wcześniejszy miesięczny kredyt w wysokości 200 USD został zastąpiony bezpłatnymi miesięcznymi limitami przypisanymi do konkretnych usług i SKU.

Przykładowo Dynamic Maps, czyli usługa związana z typowym wykorzystaniem interaktywnej mapy w Maps JavaScript API, należy obecnie do kategorii Essentials i obejmuje 10 000 bezpłatnych zdarzeń rozliczeniowych miesięcznie. Po przekroczeniu tego poziomu naliczane są opłaty zgodnie z aktualnym cennikiem Google.

Nie oznacza to jednak, że można pominąć konfigurację rozliczeń. Dla produkcyjnego wykorzystania Maps JavaScript API Google nadal wymaga aktywnego projektu z włączonym billingiem i prawidłowym uwierzytelnieniem.

3. Część starszych usług Google Maps ma status Legacy

Od 1 marca 2025 roku m.in. Directions API, Distance Matrix API oraz wcześniejsze Places API mają status Legacy.

Istniejące projekty, które wcześniej z nich korzystały, mogą nadal je wykorzystywać. Usługi Legacy nie są jednak dostępne do aktywacji w nowych projektach Google Cloud i Google zaleca stosowanie ich aktualnych odpowiedników, np. Routes API lub Places API (New).

Dla zwykłej mapy wyświetlanej na stronie nie zawsze będzie miało to znaczenie. Problem pojawi się przede wszystkim wtedy, gdy witryna korzysta również z wyszukiwania miejsc, wyznaczania tras, obliczania odległości lub innych dodatkowych funkcji.

Co musi zrobić klient, a co może przejąć agencja?

To ważne rozróżnienie, ponieważ właściciel strony nie musi samodzielnie konfigurować całego Google Maps API. Najlepszym rozwiązaniem organizacyjnym jest zasada:
konto, własność projektu i rozliczenia pozostają po stronie klienta, natomiast konfigurację techniczną i wdrożenie może przejąć agencja.

Po stronie klienta

Właściciel strony powinien przede wszystkim:

• posiadać firmowe konto Google,
• mieć kontrolę nad projektem Google Cloud wykorzystywanym przez stronę,
• posiadać aktywne konto rozliczeniowe Google Cloud,
• samodzielnie dodać metodę płatności, jeśli jest wymagana,
• nadać agencji odpowiednie uprawnienia do projektu.

Nie ma potrzeby przekazywania agencji hasła do konta Google ani danych karty płatniczej.

Jeżeli projekt Google Cloud jeszcze nie istnieje, klient może utworzyć go samodzielnie lub – po nadaniu odpowiednich uprawnień – poprosić agencję o pomoc w jego konfiguracji. Najważniejsze jest, aby projekt pozostał pod kontrolą firmy, do której należy strona.

Co może zrobić agencja?

Po uzyskaniu odpowiedniego dostępu agencja może przejąć całą część techniczną, czyli:

• sprawdzić aktualną konfigurację Google Maps,
• zweryfikować, czy strona korzysta ze starego Client ID,
• włączyć potrzebne API,
• utworzyć lub zweryfikować klucz API,
• odpowiednio zabezpieczyć klucz,
• przypisać go do właściwej domeny i usług,
• wprowadzić klucz do kodu strony, WordPressa lub wtyczki,
• przeanalizować komunikaty błędów,
• przetestować poprawne działanie mapy.

W praktyce klient powinien więc zadbać przede wszystkim o dostęp i rozliczenia, a konfigurację wymagającą wiedzy technicznej może przekazać wykonawcy strony.

Jak uruchomić Google Maps API? Krok po kroku

Poniższa instrukcja dotyczy przede wszystkim stron wykorzystujących Maps JavaScript API.

Jeżeli na stronie znajduje się jedynie prosta mapa osadzona jako iframe bezpośrednio z Google Maps, sposób konfiguracji jest inny i poniższe kroki mogą nie być potrzebne.

Krok 1. Zaloguj się do Google Cloud Console

Po stronie klienta

Należy zalogować się do Google Cloud na konto Google, które ma być powiązane z firmą i projektem strony internetowej.

Nie trzeba zakładać osobnego „konta Google Developers”. Google Maps Platform działa w ramach projektu Google Cloud. Standardowa konfiguracja obejmuje projekt, billing, włączenie odpowiednich API oraz uwierzytelnienie za pomocą klucza API.

Krok 2. Wybierz istniejący projekt lub utwórz nowy

Po stronie klienta lub z pomocą agencji

W górnej części Google Cloud Console należy wybrać projekt powiązany ze stroną.

Jeżeli odpowiedni projekt już istnieje – korzystamy z niego.

Jeśli nie:
Select a project → New Project / Create Project

Projekt warto nazwać w czytelny sposób, np.:
Nazwa firmy – strona WWW

Google oficjalnie wskazuje utworzenie projektu Cloud jako jeden z podstawowych etapów rozpoczęcia korzystania z Google Maps Platform.

Krok 3. Skonfiguruj lub sprawdź rozliczenia

Po stronie klienta

Należy sprawdzić, czy projekt jest powiązany z aktywnym kontem rozliczeniowym.

W Google Cloud Console należy przejść do sekcji:
Billing / Rozliczenia

Jeżeli projekt nie jest połączony z kontem billingowym, należy je utworzyć lub przypisać istniejące.

Właśnie ten etap powinien pozostać po stronie właściciela strony – szczególnie jeżeli konieczne jest podanie danych płatniczych.

Dla standardowego, produkcyjnego Maps JavaScript API Google wymaga konfiguracji billingu.

Od tego momentu dalszą konfigurację techniczną może przejąć agencja.

Krok 4. Włącz Maps JavaScript API

Może wykonać agencja

W Google Cloud Console przechodzimy do biblioteki API i wyszukujemy:
Maps JavaScript API

Jeżeli usługa nie jest jeszcze aktywna, wybieramy:
Enable / Włącz

Jeżeli zamiast „Enable” widoczna jest opcja zarządzania usługą, API jest już aktywne. Google wymaga włączenia tych API lub SDK, z których faktycznie korzysta projekt.

W bardziej rozbudowanych witrynach mogą być potrzebne również dodatkowe usługi, np. Places API, Geocoding API czy Routes API.

Nie należy jednak aktywować dodatkowych usług bez potrzeby.

Krok 5. Utwórz lub sprawdź klucz API

Może wykonać agencja

W Google Cloud Console należy przejść do:
Google Maps Platform → Credentials

Następnie można utworzyć klucz przez:
Create credentials → API key

Google wymaga klucza API do uwierzytelniania standardowych żądań Maps JavaScript API.

Jeżeli klucz już istnieje, nie zawsze trzeba tworzyć nowy. Najpierw warto sprawdzić, czy jest to właściwy klucz przypisany do odpowiedniego projektu.

Krok 6. Zabezpiecz klucz przed użyciem na innych stronach

Może wykonać agencja

Samo wygenerowanie klucza to nie koniec konfiguracji.

Google zaleca zabezpieczanie kluczy zarówno poprzez ograniczenia aplikacji, jak i ograniczenia API.

Dla strony internetowej należy w ustawieniach klucza wybrać ograniczenie przeznaczone dla witryn internetowych / HTTP referrers i dodać domenę, z której klucz może być używany.

Przykładowo:
https://twojadomena.pl/*

oraz – jeśli jest wykorzystywany:
https://www.twojadomena.pl/*

Jeżeli mapa działa również na subdomenie lub środowisku testowym, odpowiednie adresy także należy uwzględnić.

Dzięki temu klucz nie może być swobodnie wykorzystywany na przypadkowych zewnętrznych stronach. Google wskazuje ograniczenie klucza do konkretnych witryn jako zalecaną praktykę bezpieczeństwa.

Krok 7. Ogranicz klucz do właściwych API

Może wykonać agencja

W ustawieniach klucza należy również znaleźć:
API restrictions
i wskazać tylko te usługi, których rzeczywiście potrzebuje strona.

Dla standardowej mapy będzie to przede wszystkim:
Maps JavaScript API

Jeżeli witryna korzysta dodatkowo np. z wyszukiwania lokalizacji czy geokodowania, mogą być potrzebne kolejne usługi.

Google rekomenduje stosowanie jednocześnie ograniczenia aplikacji oraz ograniczeń API.

Krok 8. Wprowadź klucz API na stronie

Po stronie agencji lub administratora strony

Sposób wprowadzenia klucza zależy od technologii, w której działa serwis.

W przypadku własnego kodu Maps JavaScript API może być ładowane np. w następujący sposób:

<script async

  src="https://maps.googleapis.com/maps/api/js?key=TWÓJ_KLUCZ_API&callback=initMap">

</script>

Google wskazuje parametr key jako sposób przekazywania klucza przy ładowaniu Maps JavaScript API.

A co z WordPressem?

W WordPressie klucz może znajdować się w ustawieniach:

• motywu,
• page buildera,
• modułu mapy,
• dedykowanej wtyczki.

Najczęściej należy szukać pola o nazwie:
Google Maps API Key

lub:
Google API Key.

Po podmianie klucza warto wyczyścić cache strony i ponownie sprawdzić działanie mapy.

Krok 9. W starszych stronach sprawdź Client ID

Po stronie agencji

Jeżeli mapa działała przez wiele lat i nagle przestała się poprawnie wyświetlać, warto sprawdzić sposób jej uwierzytelniania.

Jeśli w kodzie znajduje się:
client=

np. z identyfikatorem rozpoczynającym się od:
gme-

strona może nadal korzystać ze starego Client ID.

Google wymaga migracji takich wdrożeń do kluczy API, ponieważ Client ID nie mogą być używane po 31 maja 2026 roku. W kodzie parametr client powinien zostać zastąpiony aktualnym sposobem uwierzytelniania przy użyciu key.

Mapa nadal nie działa? Sprawdź konsolę przeglądarki

Komunikat: „Ta strona nie wczytała Map Google prawidłowo”
sam w sobie nie wskazuje jeszcze konkretnej przyczyny.

Google udostępnia dokładniejsze informacje w konsoli JavaScript przeglądarki.

W Google Chrome można ją otworzyć w następujący sposób:
prawy przycisk myszy na stronie → Zbadaj / Inspect → Console
Następnie odśwież stronę.

W konsoli powinien pojawić się dokładny kod błędu.

Najczęstsze błędy Google Maps

MissingKeyMapError
W żądaniu brakuje klucza API.

InvalidKeyMapError
Podany klucz API jest nieprawidłowy.

BillingNotEnabledMapError
Projekt nie ma prawidłowo skonfigurowanych rozliczeń.

ApiNotActivatedMapError
Usługa potrzebna do działania mapy nie została aktywowana dla danego projektu.

RefererNotAllowedMapError
Adres strony nie znajduje się wśród dozwolonych witryn przypisanych do klucza.

ApiTargetBlockedMapError
Ograniczenia ustawione na kluczu blokują usługę, z której próbuje korzystać strona.

Google opisuje aktualne komunikaty błędów oraz sposób ich diagnozowania w dokumentacji Maps JavaScript API.

Uwaga na usługi Legacy

Podczas naprawy starszej witryny może pojawić się również błąd związany z usługą Legacy.

Od marca 2025 roku starsze wersje m.in. Places API, Directions API i Distance Matrix API mają status Legacy. Istniejące projekty, które wcześniej korzystały z tych usług, mogą nadal ich używać, ale usługi Legacy nie są udostępniane do aktywacji w nowych projektach.

Jeżeli nowy projekt próbuje uruchomić funkcjonalność opartą na starym API, prawidłowym rozwiązaniem może być migracja do jego aktualnego odpowiednika zamiast próby aktywowania starej usługi.

Czy Google Maps na stronie jest nadal bezpłatne?

To zależy od sposobu wykorzystania mapy i liczby wywołań.

Od marca 2025 roku Google nie stosuje już wcześniejszego modelu opartego na jednym miesięcznym kredycie 200 USD. Każde SKU posiada własny miesięczny bezpłatny limit.

W przypadku Dynamic Maps obecny bezpłatny limit wynosi 10 000 zdarzeń rozliczeniowych miesięcznie. Po jego przekroczeniu obowiązuje rozliczenie według aktualnego cennika Google Maps Platform.

Dla niewielkiej strony firmowej może to oznaczać brak faktycznych opłat, jeżeli wykorzystanie mieści się w darmowym limicie. Nadal jednak należy prawidłowo skonfigurować projekt Google Cloud i billing.

Warto również monitorować wykorzystanie usług oraz ustawić odpowiednie limity i alerty kosztowe. Google udostępnia w Cloud Console narzędzia służące do kontroli wykorzystania i kosztów Google Maps Platform.

Google Maps nie działa – szybka checklista

Jeżeli mapa przestała wyświetlać się na stronie, warto sprawdzić kolejno:

1. Czy strona korzysta z Maps JavaScript API?
2. Czy istnieje właściwy projekt w Google Cloud?
3. Czy projekt ma aktywne rozliczenia?
4. Czy Maps JavaScript API jest włączone?
5. Czy strona korzysta z aktualnego klucza API?
6. Czy domena została prawidłowo dodana do ograniczeń klucza?
7. Czy klucz ma dostęp do wymaganych API?
8. Czy klucz został poprawnie wpisany w kodzie, motywie lub wtyczce?
9. Czy starsza strona nie korzysta jeszcze z wycofanego Client ID?
10. Jaki dokładnie błąd pojawia się w konsoli JavaScript?

Co musi zrobić klient?

W większości przypadków wystarczy, że właściciel strony:
zapewni firmowe konto Google → będzie miał kontrolę nad projektem Google Cloud → skonfiguruje billing → nada agencji dostęp.

Nie musi samodzielnie konfigurować API ani ingerować w kod strony.

Co może zrobić agencja?

Po uzyskaniu dostępu wykonawca strony może przejąć:
diagnostykę → konfigurację usług Google Maps → utworzenie i zabezpieczenie klucza → migrację ze starego Client ID → wdrożenie klucza na stronie → testy.

Podsumowanie

Jeżeli mapa Google działała przez lata, a następnie przestała się wyświetlać, nie należy od razu zakładać awarii samego Google Maps.

Przyczyną może być konfiguracja projektu, API, billingu, klucza lub starszy sposób uwierzytelniania. W 2026 roku szczególne znaczenie ma zakończenie obsługi Maps Platform Client ID, których nie można już używać po 31 maja 2026 roku.

Właściciel strony nie musi jednak samodzielnie przechodzić przez całą konfigurację Google Cloud. Najbezpieczniejszy i najbardziej praktyczny model to pozostawienie własności konta, projektu oraz rozliczeń po stronie klienta, a przekazanie konfiguracji technicznej i wdrożenia agencji.

Dzięki temu firma zachowuje pełną kontrolę nad swoimi usługami Google, a stroną i prawidłowym działaniem integracji może zajmować się jej wykonawca.