Google Places API — jak wygenerować klucz krok po kroku

W tym odcinku kursu WP Importer robię krok w bok od kodu i pokazuję coś, co wielu początkującym zajmuje niepotrzebnie godzinę: wygenerowanie klucza do Google Places API. Bez niego kolejne odcinki nie ruszą — to Places API pozwoli nam wyszukać firmę (Text Search) i pobrać jej szczegóły (Place Details: godziny otwarcia, telefon, strona WWW, koordynaty, nawet zdjęcia i opinie).

Przewodnik jest celowo krótki, bo sama czynność trwa 4 minuty. Warto jednak od razu zrobić to dobrze — z restrykcjami i bez commitowania klucza do repo.

Google Cloud Console w 5 minut

Otwórz console.cloud.google.com. Jeśli logujesz się pierwszy raz, Google poprosi o akceptację regulaminu i (dla niektórych API) o podpięcie karty do billingu. Spokojnie — Places API ma darmowy limit miesięczny (tzw. free tier), więc przy nauce nie zapłacisz ani grosza, o ile nie zaczniesz strzelać tysięcy requestów dziennie.

Zacznij od utworzenia nowego projektu:

1. W pasku górnym kliknij listę projektów → New Project.
2. Nazwę daj roboczą, np. wp-importer-dev albo testowy-projekt. Nazwa ma sens tylko dla Ciebie.
3. Organization i Location zostaw domyślnie (chyba że masz firmowe konto Google Workspace).
4. Create — i poczekaj ~20 sekund, aż projekt się utworzy. Nie przeskakuj dalej, dopóki w prawym górnym rogu nie pojawi się jego nazwa jako aktywny kontekst.

Cały Google Cloud działa w kontekście aktywnego projektu. Jeśli za chwilę "nie widać" włączonego API albo klucza — upewnij się, że nie siedzisz w starym projekcie z dropdowna.

Włącz Places API

Usługi w Google Cloud są domyślnie wyłączone. Musisz każdą włączyć ręcznie w danym projekcie, nawet jeśli Twoje konto już kiedyś jej używało.

1. W wyszukiwarce na górze wpisz Places API (albo Places API (New) — w 2022 roku używałem klasycznego, ale w nowych projektach Google promuje już wersję nową; oba mają to samo API key i ten sam panel).
2. Wejdź w wynik → zobaczysz ekran produktu z niebieskim przyciskiem Enable.
3. Kliknij Enable i poczekaj chwilę. Po włączeniu zostaniesz automatycznie przeniesiony do panelu usługi z zakładkami Metrics, Quotas, Credentials.

Warto od razu rzucić okiem na zakładkę Quotas — to tam zobaczysz, ile requestów dziennie możesz wykonać i jaki masz limit godzinowy. Dla nauki limity są aż nadto szerokie.

Klucz + restrykcje

Teraz najważniejsze — klucz.

1. Wejdź w APIs & Services → Credentials (lub skrót: Dane logowania w polskiej wersji).
2. Create credentials → API key.
3. Google wyrzuci modal z długim stringiem zaczynającym się od AIzaSy.... Skopiuj go od razu — przyda się w następnym odcinku.

Sam klucz już działa, ale zostawienie go „otwartym” to prośba o kłopoty. Każdy, kto go zdobędzie, może strzelać na Twój limit (czytaj: na Twoją kartę, jeśli przekroczysz free tier). Dlatego zaraz po utworzeniu kliknij Edit API key i ustaw Application restrictions oraz API restrictions.

Application restrictions — wybierz wariant pasujący do tego, skąd będziesz uderzał:

• HTTP referrers (web sites) — gdy klucz ma być używany w JavaScript w przeglądarce. Podaj konkretne domeny (https://twojadomena.pl/*).
• IP addresses — gdy klucz chodzi z backendu (nasz przypadek: aplikacja konsolowa .NET na Twoim VPS-ie albo lokalnie). Wpisz IP maszyny, która będzie wykonywała zapytania.
• None — zostaw tylko na czas debugowania, potem natychmiast zmień.

API restrictions — wybierz Restrict key i zaznacz tylko Places API (i ewentualnie Geocoding API, jeśli planujesz). Dzięki temu nawet gdyby klucz wyciekł, nie uruchomi np. Maps JavaScript API czy Routes API, które potrafią naliczyć zdecydowanie wyższe koszty.

Zapisz — restrykcje wchodzą w życie w ciągu ~5 minut.

Jak trzymać klucz w projekcie .NET (user-secrets)

Klucz mamy. Do następnego odcinka poprzedzę Cię jednym krokiem, który ratuje życie: nie trzymaj go w appsettings.json.

Pliki appsettings.json są commitowane do repo, a wrzucenie klucza na GitHub to najkrótsza droga do tego, żeby w nocy boty wyczyściły Ci limit (albo gorzej — portfel). Zamiast tego użyj mechanizmu User Secrets, który zapisuje konfigurację poza katalogiem projektu, w profilu użytkownika systemu.

W katalogu projektu konsolowego:

dotnet user-secrets init
dotnet user-secrets set "GoogleApi:Key" "AIzaSy..."

Pierwsza komenda dodaje do .csproj atrybut UserSecretsId z losowym GUID-em. Druga zapisuje klucz w pliku secrets.json w ~/.microsoft/usersecrets/<guid>/ (Linux/Mac) albo %APPDATA%\Microsoft\UserSecrets\<guid>\ (Windows). W kodzie odczytasz go potem tak samo jak z appsettings.json — ale fizycznie plik nie leży w repo.

⚠️ Nigdy nie wrzucaj klucza API do repozytorium. Nawet do prywatnego, nawet „na chwilę, zaraz usunę”. GitHub skanuje publiczne repo i w większości przypadków sam wykryje Google API key i go unieważni — ale boty skanują jeszcze szybciej. Jeśli mimo wszystko zdarzyło Ci się zacommitować klucz: natychmiast idź do Cloud Console, usuń/obroć klucz (nie wystarczy usunąć pliku z repo — klucz zostaje w historii gita).

Drugie zabezpieczenie, które warto mieć nawykowo: .gitignore z wpisem appsettings.*.json dla środowisk deweloperskich plus .env — o ile używasz zmiennych środowiskowych. Do deploymentu na produkcję używaj zmiennych środowiskowych serwera albo secret managera (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault).

Co dalej?

W kolejnym odcinku (#4) pokażę, jak przeczytać ten klucz w aplikacji poprzez klasę Options i sensownie poskładać appsettings.json z User Secrets. A potem — #5 — pierwsze realne uderzenie do Text Search i Place Details, czyli pobranie Place ID po nazwie firmy i doprawienie wyniku godzinami otwarcia, telefonem oraz koordynatami.

Jeśli utknąłeś przy włączaniu API albo Google prosi Cię o billing, a Ty się wahasz — daj znać w komentarzu pod filmem. W 90% przypadków wystarcza karta do weryfikacji tożsamości, billing nie startuje, dopóki nie przekroczysz free tiera.