EN API-ключ Google Maps Platform — це унікальний ідентифікатор, який ви отримуєте у Google Cloud Console і вставляєте у код сайту чи застосунку, щоб дозволити виклик карт, геокодування та пошуку місць. Щоб отримати ключ: створіть проєкт у Google Cloud, підключіть платіжний акаунт, увімкніть потрібні API, згенеруйте ключ у розділі «Credentials» і одразу обмежте його за доменом чи додатком та списком дозволених API. У межах щомісячного безкоштовного ліміту використання ключ фактично безкоштовний для більшості малих і середніх сайтів.
Сьогодні жоден сучасний веб-проект чи мобільний додаток не обходиться без інтеграції геолокаційних сервісів. Серед них Google Maps Platform залишається лідером, пропонуючи потужний набір інструментів для відображення карт, маршрутизації та пошуку місць.
Щоб розпочати роботу з цими інструментами, вам потрібен API-ключ. У цьому посібнику ми крок за кроком покажемо, як його отримати та правильно налаштувати для безпечної та ефективної роботи, відповідно до нових алгоритмів та правил Google.
Типи ключів Google Maps API
Перш ніж переходити до покрокової інструкції, варто розуміти, що ключі Google Maps Platform розрізняються не за «рівнем», а за способом обмеження і місцем використання. Від правильного вибору типу ключа залежить і безпека проєкту, і зручність його підтримки.
- Клієнтський (браузерний) ключ: використовується у фронтенд-коді сайту (Maps JavaScript API, Places Autocomplete у формах). Обмежується за HTTP-реферером — доменом, на якому дозволено його викликати.
- Серверний ключ: застосовується для викликів із бекенду (масове геокодування адрес, розрахунок маршрутів у фоновому режимі). Обмежується за IP-адресою сервера, а не за реферером, оскільки на сервері немає «браузера», що передає домен.
- Мобільний ключ: для Android і iOS застосунків, обмежується за SHA-1 сертифікатом або Bundle ID відповідно.
- Необмежений ключ: технічно можливий, але Google прямо не рекомендує його для продакшн-проєктів — такий ключ може викликати будь-хто, хто його побачить у вихідному коді сторінки.
Найпоширеніша помилка початківців — використання одного й того самого ключа і на фронтенді, і на бекенді. Це працює технічно, але суперечить принципу мінімальних привілеїв: якщо клієнтський ключ витече, зловмисник отримає доступ і до серверних викликів. Тому для будь-якого проєкту, де є і сайт, і бекенд-логіка, варто одразу створювати окремі ключі під кожен сценарій.
| Тип ключа | Де використовується | Спосіб обмеження |
|---|---|---|
| Клієнтський (браузерний) | Maps JavaScript API на сайті, Places Autocomplete у формах | HTTP referrer (домен сайту) |
| Серверний | Geocoding, Distance Matrix, масові фонові запити з бекенду | IP-адреса сервера |
| Android | Maps SDK у мобільному застосунку | SHA-1 сертифікат + package name |
| iOS | Maps SDK у мобільному застосунку | Bundle ID |
| Необмежений | Локальне тестування (не для продакшну) | Без обмежень — ризиковано |
Крок 1: Створення облікового запису Google Cloud Platform (GCP)
Для використання Google Maps API вам необхідно мати обліковий запис на Google Cloud Platform (GCP). Це уніфікована платформа, яка керує всіма сервісами Google, включаючи карти.
Налаштування платіжного облікового запису (Billing Account)
Це найважливіший крок, який часто ігнорують. Google Maps Platform працює за моделлю Pay-as-you-go (оплата за використання). Однак, Google надає безкоштовний щомісячний ліміт (на момент публікації це близько $200), якого достатньо для більшості невеликих та середніх проектів.
- Чому це обов’язково: Навіть якщо ви не перевищите безкоштовний ліміт, API-ключ не буде активований без прив’язки активного платіжного профілю.
- Дія: Перейдіть до розділу Billing (Оплата) на GCP і створіть новий обліковий запис, додавши свою банківську картку.
Крок 2: Створення нового проекту та активація API
Кожен API-ключ прив’язаний до певного проекту на GCP.
Створення проекту
- У верхньому меню GCP Console виберіть “Select a project” (Обрати проект).
- Натисніть “New Project” (Новий проект).
- Назвіть його відповідно до вашого додатку (наприклад, “My-Awesome-Map-App”).
Активація потрібних API
Google Maps Platform складається з десятків різних API. Щоб ваш ключ працював, ви повинні активувати ті, які плануєте використовувати. Найпопулярніші:
- Maps JavaScript API: Для відображення інтерактивної карти на сайті.
- Places API: Для пошуку місць, автозаповнення адрес.
- Geocoding API: Для перетворення адреси в координати (і навпаки).
- Перейдіть до “APIs & Services” (API та Сервіси) -> “Library” (Бібліотека).
- У пошуку введіть назву потрібного API і натисніть “Enable” (Активувати).
Крок 3: Отримання та обмеження API-ключа (Best Practice)
Цей етап є критичним для безпеки. Необмежений ключ може бути використаний зловмисниками, що призведе до неконтрольованих витрат з вашого платіжного облікового запису.
Генерація ключа
- Перейдіть до “APIs & Services” -> “Credentials” (Облікові дані).
- Натисніть “Create Credentials” (Створити облікові дані) і виберіть “API key” (API-ключ).
- Система згенерує ваш унікальний ключ. Збережіть його негайно, але не робіть його публічним!
Встановлення обмежень (API Restrictions)
Відповідно до нових рекомендацій Google, ви повинні обмежити використання ключа.
Обмеження додатків (Application Restrictions)
Це запобігає використанню вашого ключа на сторонніх сайтах.
- Для веб-сайтів (Websites): Виберіть “HTTP referrers” (HTTP-реферери) і вкажіть домен вашого сайту:
*.yourdomain.com/*(для доступу на всіх субдоменах)yourdomain.com/*(для доступу на основному домені)
- Для мобільних додатків: Виберіть “Android apps” або “iOS apps” і вкажіть SHA-1 сертифікат або Bundle ID вашого додатка відповідно.
Обмеження API (API Restrictions)
Це гарантує, що ключ може викликати лише ті API, які ви активували.
- Виберіть опцію “Restrict key” (Обмежити ключ).
- Поставте галочки лише навпроти тих API, які ви плануєте використовувати (наприклад, Maps JavaScript API, Places API).
Крок 4: Впровадження ключа у ваш проект
Після успішного отримання та обмеження, ви можете вставити ключ у свій код.
Приклад для веб-сайту (JavaScript API)
Для підключення карти на веб-сторінці використовуйте наступний шаблон, замінивши YOUR_API_KEY на ваш ключ:
HTML
<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"> </script>Скільки коштує Google Maps Platform і як контролювати витрати
Google Maps Platform працює за моделлю pay-as-you-go: ви платите лише за фактичні виклики API понад безкоштовний щомісячний ліміт, про який згадувалося вище. Для типового корпоративного сайту з картою «Як нас знайти» або формою з автозаповненням адреси цього ліміту зазвичай вистачає з запасом — витрати починаються там, де є висока відвідуваність або масові фонові виклики (наприклад, геокодування великої бази адрес клієнтів).
Щоб не отримати неприємний сюрприз у рахунку, варто одразу налаштувати кілька речей у Google Cloud Console:
- Бюджети та сповіщення (Budgets & Alerts): у розділі Billing можна встановити місячний ліміт і отримувати листа, коли витрати наближаються до порогу.
- Квоти на API (Quotas): для кожного API можна встановити максимальну кількість запитів на день, щоб застрахуватися від різкого сплеску трафіку чи атаки ботів.
- Кешування результатів: якщо адреса чи координати не змінюються часто, немає сенсу викликати Geocoding API повторно — результат варто зберігати у своїй базі даних.
- Активація лише потрібних API: чим менше сервісів увімкнено, тим менша поверхня для непередбачених витрат і тим простіше стежити за звітами Billing.
Актуальні тарифи на кожен конкретний API Google публікує у власному прайс-листі Google Maps Platform Pricing — орієнтуватися варто саме на нього, оскільки розцінки періодично переглядаються.
Типові помилки при роботі з API-ключем і як їх виправити
Навіть при уважному налаштуванні розробники регулярно стикаються з однаковим набором помилок. Ось найпоширеніші з них і що зазвичай є причиною.
- RefererNotAllowedMapError: домен, з якого викликається карта, не додано до списку дозволених HTTP-реферерів. Перевірте, чи вказаний домен точно (з www чи без, http чи https, зі слешем в кінці чи ні).
- ApiNotActivatedMapError: потрібний API не увімкнено в бібліотеці для цього проєкту. Рішення — зайти в «APIs & Services > Library» і активувати саме той API, який викликає ваш код.
- Напис «For development purposes only» на карті: означає, що до проєкту не прив’язано активний платіжний акаунт. Карта продовжує працювати, але з водяним знаком, поки не буде додано білінг.
- InvalidKeyMapError: ключ скопійовано з помилкою, видалено в Google Cloud Console або належить іншому проєкту. Перегенеруйте ключ і уважно скопіюйте його ще раз.
- Карта не з’являється взагалі: найчастіше причина — відсутній тег
<script>з правильним ключем або конфлікт версій API JavaScript. Перевірте консоль розробника в браузері — Google Maps завжди виводить туди конкретний код помилки.
Google Maps Platform чи альтернативи: коли варто розглянути інше рішення
Google Maps Platform — не єдиний варіант для інтеграції карт. Якщо проєкт має дуже великий обсяг трафіку або специфічні вимоги до дизайну карти, варто порівняти його з альтернативами.
| Критерій | Google Maps Platform | Mapbox | OpenStreetMap + Leaflet |
|---|---|---|---|
| Модель оплати | Pay-as-you-go, є безкоштовний ліміт | Pay-as-you-go, є безкоштовний ліміт | Безкоштовно (open source), платиться лише хостинг тайлів за потреби) |
| Якість даних по Україні | Висока, регулярно оновлюється | Хороша, використовує дані OSM | Залежить від активності локальних контриб’юторів OSM |
| Кастомізація вигляду карти | Обмежена стандартними стилями | Дуже гнучка, власні стилі карти | Повна свобода, потребує більше налаштувань вручну |
| Складність інтеграції | Низька, багато готових прикладів | Середня | Середня-висока, потрібні додаткові бібліотеки |
| Найкраще підходить для | Бізнес-сайтів, форм із автозаповненням адрес | Продуктів із кастомним дизайном карти | Проєктів з обмеженим бюджетом на карти |
Для більшості бізнес-сайтів і лендингів, де карта потрібна для показу адреси офісу чи мережі точок продажу, Google Maps Platform залишається найпростішим рішенням — саме тому ми інтегруємо карти під час розробки сайтів здебільшого на його основі, підключаючи альтернативи лише за окремим запитом клієнта.
Поради для роботи з Google Maps Platform
- Моніторинг: Регулярно перевіряйте розділ “Billing” та “APIs & Services” для моніторингу використання та витрат. Ви можете встановити бюджети та сповіщення, щоб уникнути несподіваних нарахувань.
- Ротація ключів: Для підвищення безпеки періодично генеруйте нові API-ключі та видаляйте старі.
- Server-Side Ключі: Якщо ви використовуєте API, які викликаються з вашого бекенду (наприклад, Geocoding для масової обробки), завжди використовуйте окремий ключ, обмежений за IP-адресою вашого сервера, а не за HTTP-реферером.
Отримання API-ключа Google Maps Platform — це перший і найважливіший крок до створення потужного географічного рішення. Дотримуючись цих інструкцій, ви забезпечите безпеку та стабільність вашого проекту!
Часті питання
Чи можна користуватися Google Maps API безкоштовно?
Так, у межах щомісячного безкоштовного ліміту використання, який покриває виклики API. Для більшості невеликих і середніх сайтів цього ліміту достатньо, щоб не платити нічого понад нього. Платіжний акаунт все одно потрібно прив’язати — без цього ключ не активується, навіть якщо ви не плануєте виходити за межі безкоштовного ліміту.
Що робити, якщо API-ключ «протік» і опублікований у відкритому доступі?
Негайно перегенеруйте ключ у розділі Credentials і видаліть старий. Якщо ключ був правильно обмежений за доменом чи IP-адресою, ризик зловживання значно нижчий, навіть якщо його побачили сторонні особи — саме тому обмеження варто ставити одразу при створенні ключа, а не «колись потім».
Один ключ можна використовувати для кількох API одразу?
Так, один ключ може мати доступ одразу до декількох API (наприклад, Maps JavaScript API і Places API), якщо у налаштуваннях обмежень API ви позначите всі потрібні сервіси. Головне — не залишати ключ без обмежень «про всяк випадок», а вказувати рівно ті API, які реально викликаються з коду.
Чи потрібна банківська картка, якщо трафік дуже маленький?
Так. Google вимагає прив’язати платіжний акаунт до проєкту незалежно від очікуваного обсягу трафіку — це технічна вимога для активації ключа, а не ознака того, що з вас точно спишуть кошти. Списання відбудеться, лише якщо виклики API перевищать безкоштовний ліміт.
Скільки часу займає весь процес отримання ключа?
Для одного проєкту з базовими налаштуваннями — від 10 до 20 хвилин, якщо у вас вже є обліковий запис Google і банківська картка під рукою. Більшість часу зазвичай іде на коректне налаштування обмежень ключа, а не на технічну генерацію самого ключа.
